From 4b0668fe2110b27c94ee6ae7fc69b9f94439a0ee Mon Sep 17 00:00:00 2001 From: DongHun Kwak Date: Thu, 15 Apr 2021 10:21:03 +0900 Subject: [PATCH 1/1] Imported Upstream version ceres 1.13.0 --- CMakeLists.txt | 911 + LICENSE | 27 + README.md | 26 + cmake/AddCeresCXX11RequirementsToTarget.cmake | 84 + cmake/AddGerritCommitHook.cmake | 84 + cmake/AppendTargetProperty.cmake | 61 + cmake/CeresCompileOptionsToComponents.cmake | 91 + cmake/CeresConfig.cmake.in | 407 + cmake/CeresConfigVersion.cmake.in | 50 + ...kIfUnderscorePrefixedBesselFunctionsExist.cmake | 54 + cmake/CreateCeresConfig.cmake | 115 + cmake/FindCXSparse.cmake | 240 + cmake/FindEigen.cmake | 263 + cmake/FindGflags.cmake | 591 + cmake/FindGlog.cmake | 346 + cmake/FindSharedPtr.cmake | 108 + cmake/FindSphinx.cmake | 66 + cmake/FindSuiteSparse.cmake | 518 + cmake/FindUnorderedMap.cmake | 94 + cmake/ReadCeresVersionFromSource.cmake | 81 + cmake/UpdateCacheVariable.cmake | 43 + cmake/config.h.in | 96 + cmake/iOS.cmake | 327 + cmake/uninstall.cmake.in | 97 + config/ceres/internal/config.h | 48 + data/2x2.foe | 8 + data/3x3.foe | 13 + data/5x5.foe | 32 + data/README.foe | 14 + data/ceres_noisy.pgm | 6 + data/libmv-ba-problems/Readme.txt | 5 + data/libmv-ba-problems/problem_01.bin | Bin 0 -> 104514 bytes data/libmv-ba-problems/problem_02.bin | Bin 0 -> 291550 bytes data/libmv-ba-problems/problem_03.bin | Bin 0 -> 125582 bytes data/nist/Bennett5.dat | 214 + data/nist/BoxBOD.dat | 66 + data/nist/Chwirut1.dat | 274 + data/nist/Chwirut2.dat | 114 + data/nist/DanWood.dat | 66 + data/nist/ENSO.dat | 228 + data/nist/Eckerle4.dat | 95 + data/nist/Gauss1.dat | 310 + data/nist/Gauss2.dat | 310 + data/nist/Gauss3.dat | 310 + data/nist/Hahn1.dat | 296 + data/nist/Kirby2.dat | 211 + data/nist/Lanczos1.dat | 84 + data/nist/Lanczos2.dat | 84 + data/nist/Lanczos3.dat | 84 + data/nist/MGH09.dat | 71 + data/nist/MGH10.dat | 76 + data/nist/MGH17.dat | 93 + data/nist/Misra1a.dat | 74 + data/nist/Misra1b.dat | 74 + data/nist/Misra1c.dat | 74 + data/nist/Misra1d.dat | 74 + data/nist/Nelson.dat | 188 + data/nist/Rat42.dat | 69 + data/nist/Rat43.dat | 75 + data/nist/Roszman1.dat | 85 + data/nist/Thurber.dat | 97 + data/problem-16-22106-pre.txt | 150181 ++++++++++++++++++ docs/CMakeLists.txt | 29 + docs/source/CMakeLists.txt | 19 + docs/source/_templates/layout.html | 13 + docs/source/analytical_derivatives.rst | 192 + docs/source/automatic_derivatives.rst | 307 + docs/source/bibliography.rst | 132 + docs/source/conf.py | 242 + docs/source/contributing.rst | 131 + docs/source/derivatives.rst | 60 + docs/source/faqs.rst | 29 + docs/source/features.rst | 86 + docs/source/forward_central_error.png | Bin 0 -> 57776 bytes docs/source/forward_central_ridders_error.png | Bin 0 -> 75579 bytes docs/source/gradient_solver.rst | 502 + docs/source/gradient_tutorial.rst | 138 + docs/source/index.rst | 67 + docs/source/installation.rst | 1052 + docs/source/interfacing_with_autodiff.rst | 293 + docs/source/least_squares_fit.png | Bin 0 -> 52627 bytes docs/source/license.rst | 30 + docs/source/loss.png | Bin 0 -> 92462 bytes docs/source/manhattan_olson_3500_result.png | Bin 0 -> 109029 bytes docs/source/modeling_faqs.rst | 134 + docs/source/nnls_covariance.rst | 376 + docs/source/nnls_modeling.rst | 2041 + docs/source/nnls_solving.rst | 2257 + docs/source/nnls_tutorial.rst | 1037 + docs/source/non_robust_least_squares_fit.png | Bin 0 -> 55181 bytes docs/source/numerical_derivatives.rst | 403 + docs/source/pose_graph_3d_ex.png | Bin 0 -> 105676 bytes docs/source/robust_least_squares_fit.png | Bin 0 -> 53967 bytes docs/source/slam2d.png | Bin 0 -> 10116 bytes docs/source/solving_faqs.rst | 171 + docs/source/spivak_notation.rst | 53 + docs/source/tutorial.rst | 11 + docs/source/users.rst | 75 + docs/source/version_history.rst | 1306 + examples/CMakeLists.txt | 113 + examples/Makefile.example | 82 + examples/bal_problem.cc | 339 + examples/bal_problem.h | 109 + examples/bundle_adjuster.cc | 343 + examples/circle_fit.cc | 164 + examples/curve_fitting.c | 187 + examples/curve_fitting.cc | 163 + examples/denoising.cc | 220 + examples/ellipse_approximation.cc | 452 + examples/fields_of_experts.cc | 152 + examples/fields_of_experts.h | 145 + examples/helloworld.cc | 83 + examples/helloworld_analytic_diff.cc | 107 + examples/helloworld_numeric_diff.cc | 79 + examples/libmv_bundle_adjuster.cc | 843 + examples/libmv_homography.cc | 414 + examples/more_garbow_hillstrom.cc | 674 + examples/nist.cc | 646 + examples/pgm_image.h | 319 + examples/powell.cc | 154 + examples/random.h | 64 + examples/robot_pose_mle.cc | 316 + examples/robust_curve_fitting.cc | 165 + examples/rosenbrock.cc | 74 + examples/sampled_function/CMakeLists.txt | 32 + examples/sampled_function/README.md | 42 + examples/sampled_function/sampled_function.cc | 94 + examples/simple_bundle_adjuster.cc | 218 + examples/slam/CMakeLists.txt | 33 + examples/slam/common/read_g2o.h | 141 + examples/slam/pose_graph_2d/CMakeLists.txt | 39 + examples/slam/pose_graph_2d/README.md | 46 + .../pose_graph_2d/angle_local_parameterization.h | 63 + examples/slam/pose_graph_2d/normalize_angle.h | 53 + examples/slam/pose_graph_2d/plot_results.py | 45 + examples/slam/pose_graph_2d/pose_graph_2d.cc | 182 + .../slam/pose_graph_2d/pose_graph_2d_error_term.h | 112 + examples/slam/pose_graph_2d/types.h | 105 + examples/slam/pose_graph_3d/CMakeLists.txt | 34 + examples/slam/pose_graph_3d/README.md | 54 + examples/slam/pose_graph_3d/plot_results.py | 80 + examples/slam/pose_graph_3d/pose_graph_3d.cc | 174 + .../slam/pose_graph_3d/pose_graph_3d_error_term.h | 131 + examples/slam/pose_graph_3d/types.h | 114 + examples/snavely_reprojection_error.h | 177 + include/ceres/autodiff_cost_function.h | 227 + include/ceres/autodiff_local_parameterization.h | 154 + include/ceres/c_api.h | 146 + include/ceres/ceres.h | 59 + include/ceres/conditioned_cost_function.h | 99 + include/ceres/cost_function.h | 147 + include/ceres/cost_function_to_functor.h | 683 + include/ceres/covariance.h | 467 + include/ceres/crs_matrix.h | 86 + include/ceres/cubic_interpolation.h | 439 + include/ceres/dynamic_autodiff_cost_function.h | 251 + include/ceres/dynamic_cost_function.h | 56 + include/ceres/dynamic_cost_function_to_functor.h | 190 + include/ceres/dynamic_numeric_diff_cost_function.h | 180 + include/ceres/fpclassify.h | 70 + include/ceres/gradient_checker.h | 149 + include/ceres/gradient_problem.h | 127 + include/ceres/gradient_problem_solver.h | 370 + include/ceres/internal/autodiff.h | 324 + include/ceres/internal/disable_warnings.h | 44 + include/ceres/internal/eigen.h | 93 + include/ceres/internal/fixed_array.h | 191 + include/ceres/internal/macros.h | 170 + include/ceres/internal/manual_constructor.h | 208 + include/ceres/internal/numeric_diff.h | 446 + include/ceres/internal/port.h | 98 + include/ceres/internal/reenable_warnings.h | 38 + include/ceres/internal/scoped_ptr.h | 310 + include/ceres/internal/variadic_evaluate.h | 194 + include/ceres/iteration_callback.h | 225 + include/ceres/jet.h | 923 + include/ceres/local_parameterization.h | 323 + include/ceres/loss_function.h | 428 + include/ceres/normal_prior.h | 78 + include/ceres/numeric_diff_cost_function.h | 319 + include/ceres/numeric_diff_options.h | 79 + include/ceres/ordered_groups.h | 208 + include/ceres/problem.h | 488 + include/ceres/rotation.h | 626 + include/ceres/sized_cost_function.h | 96 + include/ceres/solver.h | 1059 + include/ceres/types.h | 514 + include/ceres/version.h | 48 + internal/ceres/CMakeLists.txt | 363 + internal/ceres/array_utils.cc | 108 + internal/ceres/array_utils.h | 87 + internal/ceres/array_utils_test.cc | 124 + internal/ceres/autodiff_cost_function_test.cc | 172 + .../ceres/autodiff_local_parameterization_test.cc | 224 + internal/ceres/autodiff_test.cc | 677 + internal/ceres/blas.cc | 81 + internal/ceres/blas.h | 57 + internal/ceres/block_evaluate_preparer.cc | 83 + internal/ceres/block_evaluate_preparer.h | 77 + internal/ceres/block_jacobi_preconditioner.cc | 106 + internal/ceres/block_jacobi_preconditioner.h | 75 + internal/ceres/block_jacobi_preconditioner_test.cc | 105 + internal/ceres/block_jacobian_writer.cc | 214 + internal/ceres/block_jacobian_writer.h | 128 + internal/ceres/block_random_access_dense_matrix.cc | 88 + internal/ceres/block_random_access_dense_matrix.h | 98 + .../ceres/block_random_access_dense_matrix_test.cc | 115 + .../ceres/block_random_access_diagonal_matrix.cc | 154 + .../ceres/block_random_access_diagonal_matrix.h | 101 + .../block_random_access_diagonal_matrix_test.cc | 160 + internal/ceres/block_random_access_matrix.cc | 40 + internal/ceres/block_random_access_matrix.h | 132 + .../ceres/block_random_access_sparse_matrix.cc | 196 + internal/ceres/block_random_access_sparse_matrix.h | 129 + .../block_random_access_sparse_matrix_test.cc | 186 + internal/ceres/block_sparse_matrix.cc | 398 + internal/ceres/block_sparse_matrix.h | 143 + internal/ceres/block_sparse_matrix_test.cc | 218 + internal/ceres/block_structure.cc | 44 + internal/ceres/block_structure.h | 98 + internal/ceres/bundle_adjustment_test.cc | 561 + internal/ceres/c_api.cc | 188 + internal/ceres/c_api_test.cc | 221 + internal/ceres/callbacks.cc | 111 + internal/ceres/callbacks.h | 71 + internal/ceres/canonical_views_clustering.cc | 240 + internal/ceres/canonical_views_clustering.h | 130 + internal/ceres/canonical_views_clustering_test.cc | 143 + internal/ceres/casts.h | 108 + internal/ceres/cgnr_linear_operator.h | 120 + internal/ceres/cgnr_solver.cc | 88 + internal/ceres/cgnr_solver.h | 69 + internal/ceres/collections_port.h | 196 + .../ceres/compressed_col_sparse_matrix_utils.cc | 122 + .../ceres/compressed_col_sparse_matrix_utils.h | 144 + .../compressed_col_sparse_matrix_utils_test.cc | 255 + internal/ceres/compressed_row_jacobian_writer.cc | 245 + internal/ceres/compressed_row_jacobian_writer.h | 112 + internal/ceres/compressed_row_sparse_matrix.cc | 567 + internal/ceres/compressed_row_sparse_matrix.h | 234 + .../ceres/compressed_row_sparse_matrix_test.cc | 414 + internal/ceres/conditioned_cost_function.cc | 130 + internal/ceres/conditioned_cost_function_test.cc | 126 + internal/ceres/conjugate_gradients_solver.cc | 248 + internal/ceres/conjugate_gradients_solver.h | 74 + internal/ceres/conjugate_gradients_solver_test.cc | 135 + internal/ceres/coordinate_descent_minimizer.cc | 278 + internal/ceres/coordinate_descent_minimizer.h | 102 + internal/ceres/corrector.cc | 158 + internal/ceres/corrector.h | 90 + internal/ceres/corrector_test.cc | 276 + internal/ceres/cost_function_to_functor_test.cc | 351 + internal/ceres/covariance.cc | 99 + internal/ceres/covariance_impl.cc | 928 + internal/ceres/covariance_impl.h | 101 + internal/ceres/covariance_test.cc | 1277 + internal/ceres/cubic_interpolation_test.cc | 510 + internal/ceres/cxsparse.cc | 283 + internal/ceres/cxsparse.h | 178 + internal/ceres/dense_jacobian_writer.h | 108 + internal/ceres/dense_linear_solver_test.cc | 134 + internal/ceres/dense_normal_cholesky_solver.cc | 166 + internal/ceres/dense_normal_cholesky_solver.h | 107 + internal/ceres/dense_qr_solver.cc | 170 + internal/ceres/dense_qr_solver.h | 115 + internal/ceres/dense_sparse_matrix.cc | 183 + internal/ceres/dense_sparse_matrix.h | 109 + internal/ceres/dense_sparse_matrix_test.cc | 169 + internal/ceres/detect_structure.cc | 120 + internal/ceres/detect_structure.h | 67 + internal/ceres/detect_structure_test.cc | 294 + internal/ceres/dogleg_strategy.cc | 718 + internal/ceres/dogleg_strategy.h | 165 + internal/ceres/dogleg_strategy_test.cc | 287 + .../ceres/dynamic_autodiff_cost_function_test.cc | 775 + internal/ceres/dynamic_compressed_row_finalizer.h | 51 + .../dynamic_compressed_row_jacobian_writer.cc | 102 + .../ceres/dynamic_compressed_row_jacobian_writer.h | 83 + .../ceres/dynamic_compressed_row_sparse_matrix.cc | 107 + .../ceres/dynamic_compressed_row_sparse_matrix.h | 101 + .../dynamic_compressed_row_sparse_matrix_test.cc | 219 + .../dynamic_numeric_diff_cost_function_test.cc | 521 + .../ceres/dynamic_sparse_normal_cholesky_solver.cc | 285 + .../ceres/dynamic_sparse_normal_cholesky_solver.h | 85 + .../dynamic_sparse_normal_cholesky_solver_test.cc | 128 + internal/ceres/dynamic_sparsity_test.cc | 449 + internal/ceres/eigensparse.cc | 143 + internal/ceres/eigensparse.h | 69 + internal/ceres/evaluator.cc | 86 + internal/ceres/evaluator.h | 205 + internal/ceres/evaluator_test.cc | 668 + internal/ceres/evaluator_test_utils.cc | 89 + internal/ceres/evaluator_test_utils.h | 60 + internal/ceres/execution_summary.h | 90 + internal/ceres/file.cc | 95 + internal/ceres/file.h | 53 + internal/ceres/function_sample.cc | 73 + internal/ceres/function_sample.h | 94 + .../ceres/generate_template_specializations.py | 244 + .../generated/partitioned_matrix_view_2_2_2.cc | 58 + .../generated/partitioned_matrix_view_2_2_3.cc | 58 + .../generated/partitioned_matrix_view_2_2_4.cc | 58 + .../generated/partitioned_matrix_view_2_2_d.cc | 58 + .../generated/partitioned_matrix_view_2_3_3.cc | 58 + .../generated/partitioned_matrix_view_2_3_4.cc | 58 + .../generated/partitioned_matrix_view_2_3_6.cc | 58 + .../generated/partitioned_matrix_view_2_3_9.cc | 58 + .../generated/partitioned_matrix_view_2_3_d.cc | 58 + .../generated/partitioned_matrix_view_2_4_3.cc | 58 + .../generated/partitioned_matrix_view_2_4_4.cc | 58 + .../generated/partitioned_matrix_view_2_4_8.cc | 58 + .../generated/partitioned_matrix_view_2_4_9.cc | 58 + .../generated/partitioned_matrix_view_2_4_d.cc | 58 + .../generated/partitioned_matrix_view_2_d_d.cc | 58 + .../generated/partitioned_matrix_view_4_4_2.cc | 58 + .../generated/partitioned_matrix_view_4_4_3.cc | 58 + .../generated/partitioned_matrix_view_4_4_4.cc | 58 + .../generated/partitioned_matrix_view_4_4_d.cc | 58 + .../generated/partitioned_matrix_view_d_d_d.cc | 52 + internal/ceres/generated/schur_eliminator_2_2_2.cc | 58 + internal/ceres/generated/schur_eliminator_2_2_3.cc | 58 + internal/ceres/generated/schur_eliminator_2_2_4.cc | 58 + internal/ceres/generated/schur_eliminator_2_2_d.cc | 58 + internal/ceres/generated/schur_eliminator_2_3_3.cc | 58 + internal/ceres/generated/schur_eliminator_2_3_4.cc | 58 + internal/ceres/generated/schur_eliminator_2_3_6.cc | 58 + internal/ceres/generated/schur_eliminator_2_3_9.cc | 58 + internal/ceres/generated/schur_eliminator_2_3_d.cc | 58 + internal/ceres/generated/schur_eliminator_2_4_3.cc | 58 + internal/ceres/generated/schur_eliminator_2_4_4.cc | 58 + internal/ceres/generated/schur_eliminator_2_4_8.cc | 58 + internal/ceres/generated/schur_eliminator_2_4_9.cc | 58 + internal/ceres/generated/schur_eliminator_2_4_d.cc | 58 + internal/ceres/generated/schur_eliminator_2_d_d.cc | 58 + internal/ceres/generated/schur_eliminator_4_4_2.cc | 58 + internal/ceres/generated/schur_eliminator_4_4_3.cc | 58 + internal/ceres/generated/schur_eliminator_4_4_4.cc | 58 + internal/ceres/generated/schur_eliminator_4_4_d.cc | 58 + internal/ceres/generated/schur_eliminator_d_d_d.cc | 52 + internal/ceres/gmock/gmock.h | 14978 ++ internal/ceres/gmock/mock-log.h | 153 + internal/ceres/gmock_gtest_all.cc | 12265 ++ internal/ceres/gmock_main.cc | 69 + internal/ceres/gradient_checker.cc | 276 + internal/ceres/gradient_checker_test.cc | 586 + internal/ceres/gradient_checking_cost_function.cc | 277 + internal/ceres/gradient_checking_cost_function.h | 112 + .../ceres/gradient_checking_cost_function_test.cc | 414 + internal/ceres/gradient_problem.cc | 81 + internal/ceres/gradient_problem_evaluator.h | 107 + internal/ceres/gradient_problem_solver.cc | 289 + internal/ceres/gradient_problem_solver_test.cc | 76 + internal/ceres/gradient_problem_test.cc | 111 + internal/ceres/graph.h | 225 + internal/ceres/graph_algorithms.h | 364 + internal/ceres/graph_algorithms_test.cc | 246 + internal/ceres/graph_test.cc | 152 + internal/ceres/gtest/gtest.h | 21202 +++ internal/ceres/householder_vector.h | 85 + internal/ceres/householder_vector_test.cc | 115 + internal/ceres/implicit_schur_complement.cc | 225 + internal/ceres/implicit_schur_complement.h | 167 + internal/ceres/implicit_schur_complement_test.cc | 200 + internal/ceres/inner_product_computer.cc | 372 + internal/ceres/inner_product_computer.h | 157 + internal/ceres/inner_product_computer_test.cc | 228 + internal/ceres/integral_types.h | 91 + internal/ceres/invert_psd_matrix.h | 78 + internal/ceres/invert_psd_matrix_test.cc | 86 + internal/ceres/is_close.cc | 59 + internal/ceres/is_close.h | 51 + internal/ceres/is_close_test.cc | 177 + .../ceres/iterative_schur_complement_solver.cc | 174 + internal/ceres/iterative_schur_complement_solver.h | 94 + .../iterative_schur_complement_solver_test.cc | 132 + internal/ceres/jet_test.cc | 674 + internal/ceres/lapack.cc | 193 + internal/ceres/lapack.h | 100 + internal/ceres/levenberg_marquardt_strategy.cc | 167 + internal/ceres/levenberg_marquardt_strategy.h | 87 + .../ceres/levenberg_marquardt_strategy_test.cc | 169 + internal/ceres/line_search.cc | 852 + internal/ceres/line_search.h | 329 + internal/ceres/line_search_direction.cc | 372 + internal/ceres/line_search_direction.h | 72 + internal/ceres/line_search_minimizer.cc | 444 + internal/ceres/line_search_minimizer.h | 77 + internal/ceres/line_search_minimizer_test.cc | 67 + internal/ceres/line_search_preprocessor.cc | 106 + internal/ceres/line_search_preprocessor.h | 50 + internal/ceres/line_search_preprocessor_test.cc | 136 + internal/ceres/linear_least_squares_problems.cc | 732 + internal/ceres/linear_least_squares_problems.h | 85 + internal/ceres/linear_operator.cc | 40 + internal/ceres/linear_operator.h | 59 + internal/ceres/linear_solver.cc | 124 + internal/ceres/linear_solver.h | 372 + internal/ceres/local_parameterization.cc | 377 + internal/ceres/local_parameterization_test.cc | 775 + internal/ceres/loss_function.cc | 174 + internal/ceres/loss_function_test.cc | 252 + internal/ceres/low_rank_inverse_hessian.cc | 188 + internal/ceres/low_rank_inverse_hessian.h | 108 + internal/ceres/map_util.h | 130 + internal/ceres/miniglog/glog/logging.cc | 39 + internal/ceres/miniglog/glog/logging.h | 425 + internal/ceres/minimizer.cc | 87 + internal/ceres/minimizer.h | 202 + internal/ceres/minimizer_test.cc | 100 + internal/ceres/mutex.h | 329 + internal/ceres/normal_prior.cc | 66 + internal/ceres/normal_prior_test.cc | 133 + internal/ceres/numeric_diff_cost_function_test.cc | 389 + internal/ceres/numeric_diff_test_utils.cc | 270 + internal/ceres/numeric_diff_test_utils.h | 152 + internal/ceres/ordered_groups_test.cc | 233 + internal/ceres/parameter_block.h | 407 + internal/ceres/parameter_block_ordering.cc | 173 + internal/ceres/parameter_block_ordering.h | 89 + internal/ceres/parameter_block_ordering_test.cc | 179 + internal/ceres/parameter_block_test.cc | 252 + internal/ceres/partitioned_matrix_view.cc | 153 + internal/ceres/partitioned_matrix_view.h | 152 + internal/ceres/partitioned_matrix_view_impl.h | 380 + internal/ceres/partitioned_matrix_view_template.py | 152 + internal/ceres/partitioned_matrix_view_test.cc | 174 + internal/ceres/polynomial.cc | 394 + internal/ceres/polynomial.h | 116 + internal/ceres/polynomial_test.cc | 517 + internal/ceres/preconditioner.cc | 73 + internal/ceres/preconditioner.h | 177 + internal/ceres/preprocessor.cc | 113 + internal/ceres/preprocessor.h | 122 + internal/ceres/problem.cc | 277 + internal/ceres/problem_impl.cc | 946 + internal/ceres/problem_impl.h | 228 + internal/ceres/problem_test.cc | 1532 + internal/ceres/program.cc | 524 + internal/ceres/program.h | 192 + internal/ceres/program_evaluator.h | 384 + internal/ceres/program_test.cc | 435 + internal/ceres/random.h | 74 + internal/ceres/reorder_program.cc | 601 + internal/ceres/reorder_program.h | 101 + internal/ceres/reorder_program_test.cc | 254 + internal/ceres/residual_block.cc | 219 + internal/ceres/residual_block.h | 148 + internal/ceres/residual_block_test.cc | 328 + internal/ceres/residual_block_utils.cc | 142 + internal/ceres/residual_block_utils.h | 80 + internal/ceres/residual_block_utils_test.cc | 167 + internal/ceres/rotation_test.cc | 1132 + internal/ceres/schur_complement_solver.cc | 425 + internal/ceres/schur_complement_solver.h | 190 + internal/ceres/schur_complement_solver_test.cc | 233 + internal/ceres/schur_eliminator.cc | 151 + internal/ceres/schur_eliminator.h | 364 + internal/ceres/schur_eliminator_impl.h | 699 + internal/ceres/schur_eliminator_template.py | 155 + internal/ceres/schur_eliminator_test.cc | 227 + internal/ceres/schur_jacobi_preconditioner.cc | 117 + internal/ceres/schur_jacobi_preconditioner.h | 106 + internal/ceres/schur_templates.cc | 211 + internal/ceres/schur_templates.h | 46 + internal/ceres/scratch_evaluate_preparer.cc | 78 + internal/ceres/scratch_evaluate_preparer.h | 69 + internal/ceres/single_linkage_clustering.cc | 103 + internal/ceres/single_linkage_clustering.h | 68 + internal/ceres/single_linkage_clustering_test.cc | 125 + internal/ceres/small_blas.h | 381 + internal/ceres/small_blas_test.cc | 302 + internal/ceres/solver.cc | 915 + internal/ceres/solver_test.cc | 402 + internal/ceres/solver_utils.cc | 86 + internal/ceres/solver_utils.h | 61 + internal/ceres/sparse_cholesky.cc | 100 + internal/ceres/sparse_cholesky.h | 122 + internal/ceres/sparse_cholesky_test.cc | 211 + internal/ceres/sparse_matrix.cc | 40 + internal/ceres/sparse_matrix.h | 107 + internal/ceres/sparse_normal_cholesky_solver.cc | 110 + internal/ceres/sparse_normal_cholesky_solver.h | 74 + .../ceres/sparse_normal_cholesky_solver_test.cc | 169 + internal/ceres/split.cc | 123 + internal/ceres/split.h | 50 + internal/ceres/stl_util.h | 91 + internal/ceres/stringprintf.cc | 145 + internal/ceres/stringprintf.h | 89 + internal/ceres/suitesparse.cc | 416 + internal/ceres/suitesparse.h | 332 + internal/ceres/system_test.cc | 191 + internal/ceres/test_util.cc | 146 + internal/ceres/test_util.h | 189 + internal/ceres/triplet_sparse_matrix.cc | 317 + internal/ceres/triplet_sparse_matrix.h | 155 + internal/ceres/triplet_sparse_matrix_test.cc | 319 + internal/ceres/trust_region_minimizer.cc | 789 + internal/ceres/trust_region_minimizer.h | 166 + internal/ceres/trust_region_minimizer_test.cc | 425 + internal/ceres/trust_region_preprocessor.cc | 375 + internal/ceres/trust_region_preprocessor.h | 50 + internal/ceres/trust_region_preprocessor_test.cc | 376 + internal/ceres/trust_region_step_evaluator.cc | 107 + internal/ceres/trust_region_step_evaluator.h | 122 + internal/ceres/trust_region_strategy.cc | 59 + internal/ceres/trust_region_strategy.h | 164 + internal/ceres/types.cc | 393 + internal/ceres/visibility.cc | 159 + internal/ceres/visibility.h | 78 + internal/ceres/visibility_based_preconditioner.cc | 587 + internal/ceres/visibility_based_preconditioner.h | 197 + .../ceres/visibility_based_preconditioner_test.cc | 342 + internal/ceres/visibility_test.cc | 206 + internal/ceres/wall_time.cc | 96 + internal/ceres/wall_time.h | 88 + jni/Android.mk | 254 + jni/Application.mk | 39 + jni/assert_ndk_version.sh | 100 + package.xml | 53 + scripts/make_docs.py | 124 + scripts/make_release | 82 + 521 files changed, 304672 insertions(+) create mode 100644 CMakeLists.txt create mode 100644 LICENSE create mode 100644 README.md create mode 100644 cmake/AddCeresCXX11RequirementsToTarget.cmake create mode 100644 cmake/AddGerritCommitHook.cmake create mode 100644 cmake/AppendTargetProperty.cmake create mode 100644 cmake/CeresCompileOptionsToComponents.cmake create mode 100644 cmake/CeresConfig.cmake.in create mode 100644 cmake/CeresConfigVersion.cmake.in create mode 100644 cmake/CheckIfUnderscorePrefixedBesselFunctionsExist.cmake create mode 100644 cmake/CreateCeresConfig.cmake create mode 100644 cmake/FindCXSparse.cmake create mode 100644 cmake/FindEigen.cmake create mode 100644 cmake/FindGflags.cmake create mode 100644 cmake/FindGlog.cmake create mode 100644 cmake/FindSharedPtr.cmake create mode 100644 cmake/FindSphinx.cmake create mode 100644 cmake/FindSuiteSparse.cmake create mode 100644 cmake/FindUnorderedMap.cmake create mode 100644 cmake/ReadCeresVersionFromSource.cmake create mode 100644 cmake/UpdateCacheVariable.cmake create mode 100644 cmake/config.h.in create mode 100644 cmake/iOS.cmake create mode 100644 cmake/uninstall.cmake.in create mode 100644 config/ceres/internal/config.h create mode 100644 data/2x2.foe create mode 100644 data/3x3.foe create mode 100644 data/5x5.foe create mode 100644 data/README.foe create mode 100644 data/ceres_noisy.pgm create mode 100644 data/libmv-ba-problems/Readme.txt create mode 100644 data/libmv-ba-problems/problem_01.bin create mode 100644 data/libmv-ba-problems/problem_02.bin create mode 100644 data/libmv-ba-problems/problem_03.bin create mode 100644 data/nist/Bennett5.dat create mode 100644 data/nist/BoxBOD.dat create mode 100644 data/nist/Chwirut1.dat create mode 100644 data/nist/Chwirut2.dat create mode 100644 data/nist/DanWood.dat create mode 100644 data/nist/ENSO.dat create mode 100644 data/nist/Eckerle4.dat create mode 100644 data/nist/Gauss1.dat create mode 100644 data/nist/Gauss2.dat create mode 100644 data/nist/Gauss3.dat create mode 100644 data/nist/Hahn1.dat create mode 100644 data/nist/Kirby2.dat create mode 100644 data/nist/Lanczos1.dat create mode 100644 data/nist/Lanczos2.dat create mode 100644 data/nist/Lanczos3.dat create mode 100644 data/nist/MGH09.dat create mode 100644 data/nist/MGH10.dat create mode 100644 data/nist/MGH17.dat create mode 100644 data/nist/Misra1a.dat create mode 100644 data/nist/Misra1b.dat create mode 100644 data/nist/Misra1c.dat create mode 100644 data/nist/Misra1d.dat create mode 100644 data/nist/Nelson.dat create mode 100644 data/nist/Rat42.dat create mode 100644 data/nist/Rat43.dat create mode 100644 data/nist/Roszman1.dat create mode 100644 data/nist/Thurber.dat create mode 100644 data/problem-16-22106-pre.txt create mode 100644 docs/CMakeLists.txt create mode 100644 docs/source/CMakeLists.txt create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/analytical_derivatives.rst create mode 100644 docs/source/automatic_derivatives.rst create mode 100644 docs/source/bibliography.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/contributing.rst create mode 100644 docs/source/derivatives.rst create mode 100644 docs/source/faqs.rst create mode 100644 docs/source/features.rst create mode 100644 docs/source/forward_central_error.png create mode 100644 docs/source/forward_central_ridders_error.png create mode 100644 docs/source/gradient_solver.rst create mode 100644 docs/source/gradient_tutorial.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/interfacing_with_autodiff.rst create mode 100644 docs/source/least_squares_fit.png create mode 100644 docs/source/license.rst create mode 100644 docs/source/loss.png create mode 100644 docs/source/manhattan_olson_3500_result.png create mode 100644 docs/source/modeling_faqs.rst create mode 100644 docs/source/nnls_covariance.rst create mode 100644 docs/source/nnls_modeling.rst create mode 100644 docs/source/nnls_solving.rst create mode 100644 docs/source/nnls_tutorial.rst create mode 100644 docs/source/non_robust_least_squares_fit.png create mode 100644 docs/source/numerical_derivatives.rst create mode 100644 docs/source/pose_graph_3d_ex.png create mode 100644 docs/source/robust_least_squares_fit.png create mode 100644 docs/source/slam2d.png create mode 100644 docs/source/solving_faqs.rst create mode 100644 docs/source/spivak_notation.rst create mode 100644 docs/source/tutorial.rst create mode 100644 docs/source/users.rst create mode 100644 docs/source/version_history.rst create mode 100644 examples/CMakeLists.txt create mode 100644 examples/Makefile.example create mode 100644 examples/bal_problem.cc create mode 100644 examples/bal_problem.h create mode 100644 examples/bundle_adjuster.cc create mode 100644 examples/circle_fit.cc create mode 100644 examples/curve_fitting.c create mode 100644 examples/curve_fitting.cc create mode 100644 examples/denoising.cc create mode 100644 examples/ellipse_approximation.cc create mode 100644 examples/fields_of_experts.cc create mode 100644 examples/fields_of_experts.h create mode 100644 examples/helloworld.cc create mode 100644 examples/helloworld_analytic_diff.cc create mode 100644 examples/helloworld_numeric_diff.cc create mode 100644 examples/libmv_bundle_adjuster.cc create mode 100644 examples/libmv_homography.cc create mode 100644 examples/more_garbow_hillstrom.cc create mode 100644 examples/nist.cc create mode 100644 examples/pgm_image.h create mode 100644 examples/powell.cc create mode 100644 examples/random.h create mode 100644 examples/robot_pose_mle.cc create mode 100644 examples/robust_curve_fitting.cc create mode 100644 examples/rosenbrock.cc create mode 100644 examples/sampled_function/CMakeLists.txt create mode 100644 examples/sampled_function/README.md create mode 100644 examples/sampled_function/sampled_function.cc create mode 100644 examples/simple_bundle_adjuster.cc create mode 100644 examples/slam/CMakeLists.txt create mode 100644 examples/slam/common/read_g2o.h create mode 100644 examples/slam/pose_graph_2d/CMakeLists.txt create mode 100644 examples/slam/pose_graph_2d/README.md create mode 100644 examples/slam/pose_graph_2d/angle_local_parameterization.h create mode 100644 examples/slam/pose_graph_2d/normalize_angle.h create mode 100755 examples/slam/pose_graph_2d/plot_results.py create mode 100644 examples/slam/pose_graph_2d/pose_graph_2d.cc create mode 100644 examples/slam/pose_graph_2d/pose_graph_2d_error_term.h create mode 100644 examples/slam/pose_graph_2d/types.h create mode 100644 examples/slam/pose_graph_3d/CMakeLists.txt create mode 100644 examples/slam/pose_graph_3d/README.md create mode 100755 examples/slam/pose_graph_3d/plot_results.py create mode 100644 examples/slam/pose_graph_3d/pose_graph_3d.cc create mode 100644 examples/slam/pose_graph_3d/pose_graph_3d_error_term.h create mode 100644 examples/slam/pose_graph_3d/types.h create mode 100644 examples/snavely_reprojection_error.h create mode 100644 include/ceres/autodiff_cost_function.h create mode 100644 include/ceres/autodiff_local_parameterization.h create mode 100644 include/ceres/c_api.h create mode 100644 include/ceres/ceres.h create mode 100644 include/ceres/conditioned_cost_function.h create mode 100644 include/ceres/cost_function.h create mode 100644 include/ceres/cost_function_to_functor.h create mode 100644 include/ceres/covariance.h create mode 100644 include/ceres/crs_matrix.h create mode 100644 include/ceres/cubic_interpolation.h create mode 100644 include/ceres/dynamic_autodiff_cost_function.h create mode 100644 include/ceres/dynamic_cost_function.h create mode 100644 include/ceres/dynamic_cost_function_to_functor.h create mode 100644 include/ceres/dynamic_numeric_diff_cost_function.h create mode 100644 include/ceres/fpclassify.h create mode 100644 include/ceres/gradient_checker.h create mode 100644 include/ceres/gradient_problem.h create mode 100644 include/ceres/gradient_problem_solver.h create mode 100644 include/ceres/internal/autodiff.h create mode 100644 include/ceres/internal/disable_warnings.h create mode 100644 include/ceres/internal/eigen.h create mode 100644 include/ceres/internal/fixed_array.h create mode 100644 include/ceres/internal/macros.h create mode 100644 include/ceres/internal/manual_constructor.h create mode 100644 include/ceres/internal/numeric_diff.h create mode 100644 include/ceres/internal/port.h create mode 100644 include/ceres/internal/reenable_warnings.h create mode 100644 include/ceres/internal/scoped_ptr.h create mode 100644 include/ceres/internal/variadic_evaluate.h create mode 100644 include/ceres/iteration_callback.h create mode 100644 include/ceres/jet.h create mode 100644 include/ceres/local_parameterization.h create mode 100644 include/ceres/loss_function.h create mode 100644 include/ceres/normal_prior.h create mode 100644 include/ceres/numeric_diff_cost_function.h create mode 100644 include/ceres/numeric_diff_options.h create mode 100644 include/ceres/ordered_groups.h create mode 100644 include/ceres/problem.h create mode 100644 include/ceres/rotation.h create mode 100644 include/ceres/sized_cost_function.h create mode 100644 include/ceres/solver.h create mode 100644 include/ceres/types.h create mode 100644 include/ceres/version.h create mode 100644 internal/ceres/CMakeLists.txt create mode 100644 internal/ceres/array_utils.cc create mode 100644 internal/ceres/array_utils.h create mode 100644 internal/ceres/array_utils_test.cc create mode 100644 internal/ceres/autodiff_cost_function_test.cc create mode 100644 internal/ceres/autodiff_local_parameterization_test.cc create mode 100644 internal/ceres/autodiff_test.cc create mode 100644 internal/ceres/blas.cc create mode 100644 internal/ceres/blas.h create mode 100644 internal/ceres/block_evaluate_preparer.cc create mode 100644 internal/ceres/block_evaluate_preparer.h create mode 100644 internal/ceres/block_jacobi_preconditioner.cc create mode 100644 internal/ceres/block_jacobi_preconditioner.h create mode 100644 internal/ceres/block_jacobi_preconditioner_test.cc create mode 100644 internal/ceres/block_jacobian_writer.cc create mode 100644 internal/ceres/block_jacobian_writer.h create mode 100644 internal/ceres/block_random_access_dense_matrix.cc create mode 100644 internal/ceres/block_random_access_dense_matrix.h create mode 100644 internal/ceres/block_random_access_dense_matrix_test.cc create mode 100644 internal/ceres/block_random_access_diagonal_matrix.cc create mode 100644 internal/ceres/block_random_access_diagonal_matrix.h create mode 100644 internal/ceres/block_random_access_diagonal_matrix_test.cc create mode 100644 internal/ceres/block_random_access_matrix.cc create mode 100644 internal/ceres/block_random_access_matrix.h create mode 100644 internal/ceres/block_random_access_sparse_matrix.cc create mode 100644 internal/ceres/block_random_access_sparse_matrix.h create mode 100644 internal/ceres/block_random_access_sparse_matrix_test.cc create mode 100644 internal/ceres/block_sparse_matrix.cc create mode 100644 internal/ceres/block_sparse_matrix.h create mode 100644 internal/ceres/block_sparse_matrix_test.cc create mode 100644 internal/ceres/block_structure.cc create mode 100644 internal/ceres/block_structure.h create mode 100644 internal/ceres/bundle_adjustment_test.cc create mode 100644 internal/ceres/c_api.cc create mode 100644 internal/ceres/c_api_test.cc create mode 100644 internal/ceres/callbacks.cc create mode 100644 internal/ceres/callbacks.h create mode 100644 internal/ceres/canonical_views_clustering.cc create mode 100644 internal/ceres/canonical_views_clustering.h create mode 100644 internal/ceres/canonical_views_clustering_test.cc create mode 100644 internal/ceres/casts.h create mode 100644 internal/ceres/cgnr_linear_operator.h create mode 100644 internal/ceres/cgnr_solver.cc create mode 100644 internal/ceres/cgnr_solver.h create mode 100644 internal/ceres/collections_port.h create mode 100644 internal/ceres/compressed_col_sparse_matrix_utils.cc create mode 100644 internal/ceres/compressed_col_sparse_matrix_utils.h create mode 100644 internal/ceres/compressed_col_sparse_matrix_utils_test.cc create mode 100644 internal/ceres/compressed_row_jacobian_writer.cc create mode 100644 internal/ceres/compressed_row_jacobian_writer.h create mode 100644 internal/ceres/compressed_row_sparse_matrix.cc create mode 100644 internal/ceres/compressed_row_sparse_matrix.h create mode 100644 internal/ceres/compressed_row_sparse_matrix_test.cc create mode 100644 internal/ceres/conditioned_cost_function.cc create mode 100644 internal/ceres/conditioned_cost_function_test.cc create mode 100644 internal/ceres/conjugate_gradients_solver.cc create mode 100644 internal/ceres/conjugate_gradients_solver.h create mode 100644 internal/ceres/conjugate_gradients_solver_test.cc create mode 100644 internal/ceres/coordinate_descent_minimizer.cc create mode 100644 internal/ceres/coordinate_descent_minimizer.h create mode 100644 internal/ceres/corrector.cc create mode 100644 internal/ceres/corrector.h create mode 100644 internal/ceres/corrector_test.cc create mode 100644 internal/ceres/cost_function_to_functor_test.cc create mode 100644 internal/ceres/covariance.cc create mode 100644 internal/ceres/covariance_impl.cc create mode 100644 internal/ceres/covariance_impl.h create mode 100644 internal/ceres/covariance_test.cc create mode 100644 internal/ceres/cubic_interpolation_test.cc create mode 100644 internal/ceres/cxsparse.cc create mode 100644 internal/ceres/cxsparse.h create mode 100644 internal/ceres/dense_jacobian_writer.h create mode 100644 internal/ceres/dense_linear_solver_test.cc create mode 100644 internal/ceres/dense_normal_cholesky_solver.cc create mode 100644 internal/ceres/dense_normal_cholesky_solver.h create mode 100644 internal/ceres/dense_qr_solver.cc create mode 100644 internal/ceres/dense_qr_solver.h create mode 100644 internal/ceres/dense_sparse_matrix.cc create mode 100644 internal/ceres/dense_sparse_matrix.h create mode 100644 internal/ceres/dense_sparse_matrix_test.cc create mode 100644 internal/ceres/detect_structure.cc create mode 100644 internal/ceres/detect_structure.h create mode 100644 internal/ceres/detect_structure_test.cc create mode 100644 internal/ceres/dogleg_strategy.cc create mode 100644 internal/ceres/dogleg_strategy.h create mode 100644 internal/ceres/dogleg_strategy_test.cc create mode 100644 internal/ceres/dynamic_autodiff_cost_function_test.cc create mode 100644 internal/ceres/dynamic_compressed_row_finalizer.h create mode 100644 internal/ceres/dynamic_compressed_row_jacobian_writer.cc create mode 100644 internal/ceres/dynamic_compressed_row_jacobian_writer.h create mode 100644 internal/ceres/dynamic_compressed_row_sparse_matrix.cc create mode 100644 internal/ceres/dynamic_compressed_row_sparse_matrix.h create mode 100644 internal/ceres/dynamic_compressed_row_sparse_matrix_test.cc create mode 100644 internal/ceres/dynamic_numeric_diff_cost_function_test.cc create mode 100644 internal/ceres/dynamic_sparse_normal_cholesky_solver.cc create mode 100644 internal/ceres/dynamic_sparse_normal_cholesky_solver.h create mode 100644 internal/ceres/dynamic_sparse_normal_cholesky_solver_test.cc create mode 100644 internal/ceres/dynamic_sparsity_test.cc create mode 100644 internal/ceres/eigensparse.cc create mode 100644 internal/ceres/eigensparse.h create mode 100644 internal/ceres/evaluator.cc create mode 100644 internal/ceres/evaluator.h create mode 100644 internal/ceres/evaluator_test.cc create mode 100644 internal/ceres/evaluator_test_utils.cc create mode 100644 internal/ceres/evaluator_test_utils.h create mode 100644 internal/ceres/execution_summary.h create mode 100644 internal/ceres/file.cc create mode 100644 internal/ceres/file.h create mode 100644 internal/ceres/function_sample.cc create mode 100644 internal/ceres/function_sample.h create mode 100644 internal/ceres/generate_template_specializations.py create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_2_2.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_2_3.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_2_4.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_2_d.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_3_3.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_3_4.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_3_6.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_3_9.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_3_d.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_4_3.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_4_4.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_4_8.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_4_9.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_4_d.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_2_d_d.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_4_4_2.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_4_4_3.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_4_4_4.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_4_4_d.cc create mode 100644 internal/ceres/generated/partitioned_matrix_view_d_d_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_2_2.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_2_3.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_2_4.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_2_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_3_3.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_3_4.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_3_6.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_3_9.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_3_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_4_3.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_4_4.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_4_8.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_4_9.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_4_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_2_d_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_4_4_2.cc create mode 100644 internal/ceres/generated/schur_eliminator_4_4_3.cc create mode 100644 internal/ceres/generated/schur_eliminator_4_4_4.cc create mode 100644 internal/ceres/generated/schur_eliminator_4_4_d.cc create mode 100644 internal/ceres/generated/schur_eliminator_d_d_d.cc create mode 100644 internal/ceres/gmock/gmock.h create mode 100644 internal/ceres/gmock/mock-log.h create mode 100644 internal/ceres/gmock_gtest_all.cc create mode 100644 internal/ceres/gmock_main.cc create mode 100644 internal/ceres/gradient_checker.cc create mode 100644 internal/ceres/gradient_checker_test.cc create mode 100644 internal/ceres/gradient_checking_cost_function.cc create mode 100644 internal/ceres/gradient_checking_cost_function.h create mode 100644 internal/ceres/gradient_checking_cost_function_test.cc create mode 100644 internal/ceres/gradient_problem.cc create mode 100644 internal/ceres/gradient_problem_evaluator.h create mode 100644 internal/ceres/gradient_problem_solver.cc create mode 100644 internal/ceres/gradient_problem_solver_test.cc create mode 100644 internal/ceres/gradient_problem_test.cc create mode 100644 internal/ceres/graph.h create mode 100644 internal/ceres/graph_algorithms.h create mode 100644 internal/ceres/graph_algorithms_test.cc create mode 100644 internal/ceres/graph_test.cc create mode 100644 internal/ceres/gtest/gtest.h create mode 100644 internal/ceres/householder_vector.h create mode 100644 internal/ceres/householder_vector_test.cc create mode 100644 internal/ceres/implicit_schur_complement.cc create mode 100644 internal/ceres/implicit_schur_complement.h create mode 100644 internal/ceres/implicit_schur_complement_test.cc create mode 100644 internal/ceres/inner_product_computer.cc create mode 100644 internal/ceres/inner_product_computer.h create mode 100644 internal/ceres/inner_product_computer_test.cc create mode 100644 internal/ceres/integral_types.h create mode 100644 internal/ceres/invert_psd_matrix.h create mode 100644 internal/ceres/invert_psd_matrix_test.cc create mode 100644 internal/ceres/is_close.cc create mode 100644 internal/ceres/is_close.h create mode 100644 internal/ceres/is_close_test.cc create mode 100644 internal/ceres/iterative_schur_complement_solver.cc create mode 100644 internal/ceres/iterative_schur_complement_solver.h create mode 100644 internal/ceres/iterative_schur_complement_solver_test.cc create mode 100644 internal/ceres/jet_test.cc create mode 100644 internal/ceres/lapack.cc create mode 100644 internal/ceres/lapack.h create mode 100644 internal/ceres/levenberg_marquardt_strategy.cc create mode 100644 internal/ceres/levenberg_marquardt_strategy.h create mode 100644 internal/ceres/levenberg_marquardt_strategy_test.cc create mode 100644 internal/ceres/line_search.cc create mode 100644 internal/ceres/line_search.h create mode 100644 internal/ceres/line_search_direction.cc create mode 100644 internal/ceres/line_search_direction.h create mode 100644 internal/ceres/line_search_minimizer.cc create mode 100644 internal/ceres/line_search_minimizer.h create mode 100644 internal/ceres/line_search_minimizer_test.cc create mode 100644 internal/ceres/line_search_preprocessor.cc create mode 100644 internal/ceres/line_search_preprocessor.h create mode 100644 internal/ceres/line_search_preprocessor_test.cc create mode 100644 internal/ceres/linear_least_squares_problems.cc create mode 100644 internal/ceres/linear_least_squares_problems.h create mode 100644 internal/ceres/linear_operator.cc create mode 100644 internal/ceres/linear_operator.h create mode 100644 internal/ceres/linear_solver.cc create mode 100644 internal/ceres/linear_solver.h create mode 100644 internal/ceres/local_parameterization.cc create mode 100644 internal/ceres/local_parameterization_test.cc create mode 100644 internal/ceres/loss_function.cc create mode 100644 internal/ceres/loss_function_test.cc create mode 100644 internal/ceres/low_rank_inverse_hessian.cc create mode 100644 internal/ceres/low_rank_inverse_hessian.h create mode 100644 internal/ceres/map_util.h create mode 100644 internal/ceres/miniglog/glog/logging.cc create mode 100644 internal/ceres/miniglog/glog/logging.h create mode 100644 internal/ceres/minimizer.cc create mode 100644 internal/ceres/minimizer.h create mode 100644 internal/ceres/minimizer_test.cc create mode 100644 internal/ceres/mutex.h create mode 100644 internal/ceres/normal_prior.cc create mode 100644 internal/ceres/normal_prior_test.cc create mode 100644 internal/ceres/numeric_diff_cost_function_test.cc create mode 100644 internal/ceres/numeric_diff_test_utils.cc create mode 100644 internal/ceres/numeric_diff_test_utils.h create mode 100644 internal/ceres/ordered_groups_test.cc create mode 100644 internal/ceres/parameter_block.h create mode 100644 internal/ceres/parameter_block_ordering.cc create mode 100644 internal/ceres/parameter_block_ordering.h create mode 100644 internal/ceres/parameter_block_ordering_test.cc create mode 100644 internal/ceres/parameter_block_test.cc create mode 100644 internal/ceres/partitioned_matrix_view.cc create mode 100644 internal/ceres/partitioned_matrix_view.h create mode 100644 internal/ceres/partitioned_matrix_view_impl.h create mode 100644 internal/ceres/partitioned_matrix_view_template.py create mode 100644 internal/ceres/partitioned_matrix_view_test.cc create mode 100644 internal/ceres/polynomial.cc create mode 100644 internal/ceres/polynomial.h create mode 100644 internal/ceres/polynomial_test.cc create mode 100644 internal/ceres/preconditioner.cc create mode 100644 internal/ceres/preconditioner.h create mode 100644 internal/ceres/preprocessor.cc create mode 100644 internal/ceres/preprocessor.h create mode 100644 internal/ceres/problem.cc create mode 100644 internal/ceres/problem_impl.cc create mode 100644 internal/ceres/problem_impl.h create mode 100644 internal/ceres/problem_test.cc create mode 100644 internal/ceres/program.cc create mode 100644 internal/ceres/program.h create mode 100644 internal/ceres/program_evaluator.h create mode 100644 internal/ceres/program_test.cc create mode 100644 internal/ceres/random.h create mode 100644 internal/ceres/reorder_program.cc create mode 100644 internal/ceres/reorder_program.h create mode 100644 internal/ceres/reorder_program_test.cc create mode 100644 internal/ceres/residual_block.cc create mode 100644 internal/ceres/residual_block.h create mode 100644 internal/ceres/residual_block_test.cc create mode 100644 internal/ceres/residual_block_utils.cc create mode 100644 internal/ceres/residual_block_utils.h create mode 100644 internal/ceres/residual_block_utils_test.cc create mode 100644 internal/ceres/rotation_test.cc create mode 100644 internal/ceres/schur_complement_solver.cc create mode 100644 internal/ceres/schur_complement_solver.h create mode 100644 internal/ceres/schur_complement_solver_test.cc create mode 100644 internal/ceres/schur_eliminator.cc create mode 100644 internal/ceres/schur_eliminator.h create mode 100644 internal/ceres/schur_eliminator_impl.h create mode 100644 internal/ceres/schur_eliminator_template.py create mode 100644 internal/ceres/schur_eliminator_test.cc create mode 100644 internal/ceres/schur_jacobi_preconditioner.cc create mode 100644 internal/ceres/schur_jacobi_preconditioner.h create mode 100644 internal/ceres/schur_templates.cc create mode 100644 internal/ceres/schur_templates.h create mode 100644 internal/ceres/scratch_evaluate_preparer.cc create mode 100644 internal/ceres/scratch_evaluate_preparer.h create mode 100644 internal/ceres/single_linkage_clustering.cc create mode 100644 internal/ceres/single_linkage_clustering.h create mode 100644 internal/ceres/single_linkage_clustering_test.cc create mode 100644 internal/ceres/small_blas.h create mode 100644 internal/ceres/small_blas_test.cc create mode 100644 internal/ceres/solver.cc create mode 100644 internal/ceres/solver_test.cc create mode 100644 internal/ceres/solver_utils.cc create mode 100644 internal/ceres/solver_utils.h create mode 100644 internal/ceres/sparse_cholesky.cc create mode 100644 internal/ceres/sparse_cholesky.h create mode 100644 internal/ceres/sparse_cholesky_test.cc create mode 100644 internal/ceres/sparse_matrix.cc create mode 100644 internal/ceres/sparse_matrix.h create mode 100644 internal/ceres/sparse_normal_cholesky_solver.cc create mode 100644 internal/ceres/sparse_normal_cholesky_solver.h create mode 100644 internal/ceres/sparse_normal_cholesky_solver_test.cc create mode 100644 internal/ceres/split.cc create mode 100644 internal/ceres/split.h create mode 100644 internal/ceres/stl_util.h create mode 100644 internal/ceres/stringprintf.cc create mode 100644 internal/ceres/stringprintf.h create mode 100644 internal/ceres/suitesparse.cc create mode 100644 internal/ceres/suitesparse.h create mode 100644 internal/ceres/system_test.cc create mode 100644 internal/ceres/test_util.cc create mode 100644 internal/ceres/test_util.h create mode 100644 internal/ceres/triplet_sparse_matrix.cc create mode 100644 internal/ceres/triplet_sparse_matrix.h create mode 100644 internal/ceres/triplet_sparse_matrix_test.cc create mode 100644 internal/ceres/trust_region_minimizer.cc create mode 100644 internal/ceres/trust_region_minimizer.h create mode 100644 internal/ceres/trust_region_minimizer_test.cc create mode 100644 internal/ceres/trust_region_preprocessor.cc create mode 100644 internal/ceres/trust_region_preprocessor.h create mode 100644 internal/ceres/trust_region_preprocessor_test.cc create mode 100644 internal/ceres/trust_region_step_evaluator.cc create mode 100644 internal/ceres/trust_region_step_evaluator.h create mode 100644 internal/ceres/trust_region_strategy.cc create mode 100644 internal/ceres/trust_region_strategy.h create mode 100644 internal/ceres/types.cc create mode 100644 internal/ceres/visibility.cc create mode 100644 internal/ceres/visibility.h create mode 100644 internal/ceres/visibility_based_preconditioner.cc create mode 100644 internal/ceres/visibility_based_preconditioner.h create mode 100644 internal/ceres/visibility_based_preconditioner_test.cc create mode 100644 internal/ceres/visibility_test.cc create mode 100644 internal/ceres/wall_time.cc create mode 100644 internal/ceres/wall_time.h create mode 100644 jni/Android.mk create mode 100644 jni/Application.mk create mode 100755 jni/assert_ndk_version.sh create mode 100644 package.xml create mode 100644 scripts/make_docs.py create mode 100755 scripts/make_release diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..0174824 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,911 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Authors: keir@google.com (Keir Mierle) +# alexs.mac@gmail.com (Alex Stewart) + +cmake_minimum_required(VERSION 2.8.0) +cmake_policy(VERSION 2.8) + +cmake_policy(SET CMP0003 NEW) +if (POLICY CMP0042) + cmake_policy(SET CMP0042 NEW) +endif() + +project(Ceres C CXX) + +# NOTE: The 'generic' CMake variables CMAKE_[SOURCE/BINARY]_DIR should not be +# used. Always use the project-specific variants (generated by CMake): +# _[SOURCE/BINARY]_DIR, e.g. +# Ceres_SOURCE_DIR (note, *not* CERES_SOURCE_DIR) instead, as these will +# always point to the correct directories for the Ceres project, even if +# it is nested inside another source tree, whereas the 'generic' +# CMake variables refer to the *first* project() declaration, i.e. the +# top-level project, not Ceres, if Ceres is nested. + +# Make CMake aware of the cmake folder for local FindXXX scripts, +# append rather than set in case the user has passed their own +# additional paths via -D. +list(APPEND CMAKE_MODULE_PATH "${Ceres_SOURCE_DIR}/cmake") +include(UpdateCacheVariable) + +# Set up the git hook to make Gerrit Change-Id: lines in commit messages. +include(AddGerritCommitHook) +add_gerrit_commit_hook(${Ceres_SOURCE_DIR} ${Ceres_BINARY_DIR}) + +# On OS X, add the Homebrew prefix to the set of prefixes searched by +# CMake in find_path & find_library. This should ensure that we can +# still build Ceres even if Homebrew is installed in a non-standard +# location (not /usr/local). +if (CMAKE_SYSTEM_NAME MATCHES "Darwin") + find_program(HOMEBREW_EXECUTABLE brew) + mark_as_advanced(FORCE HOMEBREW_EXECUTABLE) + if (HOMEBREW_EXECUTABLE) + # Detected a Homebrew install, query for its install prefix. + execute_process(COMMAND ${HOMEBREW_EXECUTABLE} --prefix + OUTPUT_VARIABLE HOMEBREW_INSTALL_PREFIX + OUTPUT_STRIP_TRAILING_WHITESPACE) + message(STATUS "Detected Homebrew with install prefix: " + "${HOMEBREW_INSTALL_PREFIX}, adding to CMake search paths.") + list(APPEND CMAKE_PREFIX_PATH "${HOMEBREW_INSTALL_PREFIX}") + endif() +endif() + +set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${Ceres_BINARY_DIR}/bin) +set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${Ceres_BINARY_DIR}/lib) +set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${Ceres_BINARY_DIR}/lib) +# Set postfixes for generated libraries based on buildtype. +set(CMAKE_RELEASE_POSTFIX "") +set(CMAKE_DEBUG_POSTFIX "-debug") + +# Read the Ceres version from the source, such that we only ever have a single +# definition of the Ceres version. +include(ReadCeresVersionFromSource) +read_ceres_version_from_source(${Ceres_SOURCE_DIR}) + +enable_testing() + +option(MINIGLOG "Use a stripped down version of glog." OFF) +option(GFLAGS "Enable Google Flags." ON) +option(SUITESPARSE "Enable SuiteSparse." ON) +option(CXSPARSE "Enable CXSparse." ON) +option(LAPACK "Enable use of LAPACK." ON) +# Template specializations for the Schur complement based solvers. If +# compile time, binary size or compiler performance is an issue, you +# may consider disabling this. +option(SCHUR_SPECIALIZATIONS "Enable fixed-size schur specializations." ON) +option(CUSTOM_BLAS + "Use handcoded BLAS routines (usually faster) instead of Eigen." + ON) +# Multithreading using OpenMP +option(OPENMP "Enable threaded solving in Ceres (requires OpenMP)" ON) +# Enable the use of Eigen as a sparse linear algebra library for +# solving the nonlinear least squares problems. Enabling this +# option will result in an LGPL licensed version of Ceres Solver +# as the Simplicial Cholesky factorization in Eigen is licensed under the LGPL. +# This does not affect the covariance estimation algorithm, as it +# depends on the sparse QR factorization algorithm, which is licensed +# under the MPL. +OPTION(EIGENSPARSE + "Enable Eigen as a sparse linear algebra library, WARNING: results in an LGPL licensed Ceres." OFF) +if (NOT MSVC) + # Ceres does not use C++11 internally, however it does use shared_ptr + # (required) and unordered_map (if available), both of which were present in + # previous iterations of what became C++11. GCC & Clang can have both TR1 & + # C++11 versions of both shared_ptr & unordered_map and by default on Linux, + # we will detect the TR1 versions if they exist, as they do NOT require + # -std=c++11 to be passed when compiling Ceres, and any client code that uses + # Ceres. This will result in conflicts if the client code uses C++11. + # Enabling this option forces the use of the C++11 versions (& -std=c++11) if + # available. + # + # This option is not available on Windows when using MSVC, as there, any new + # (C++11 etc) features available are on by default and there is no analogue to + # -std=c++11. It will however be available for MinGW & CygWin, which can + # support -std=c++11. + option(CXX11 "Enable use of C++11 headers if available (requires client code use C++11)." OFF) +endif(NOT MSVC) +option(EXPORT_BUILD_DIR + "Export build directory using CMake (enables external use without install)." OFF) +option(BUILD_TESTING "Enable tests" ON) +option(BUILD_DOCUMENTATION "Build User's Guide (html)" OFF) +option(BUILD_EXAMPLES "Build examples" ON) +option(BUILD_SHARED_LIBS "Build Ceres as a shared library." OFF) +if (MSVC) + option(MSVC_USE_STATIC_CRT + "MS Visual Studio: Use static C-Run Time Library in place of shared." OFF) + + if (BUILD_TESTING AND BUILD_SHARED_LIBS) + message( + "-- Disabling tests. The flags BUILD_TESTING and BUILD_SHARED_LIBS" + " are incompatible with MSVC.") + update_cache_variable(BUILD_TESTING OFF) + endif (BUILD_TESTING AND BUILD_SHARED_LIBS) +endif (MSVC) +# Allow user to specify a suffix for the library install directory, the only +# really sensible option (other than "") being "64", such that: +# ${CMAKE_INSTALL_PREFIX}/lib -> ${CMAKE_INSTALL_PREFIX}/lib64. +# +# Heuristic for determining LIB_SUFFIX. FHS recommends that 64-bit systems +# install native libraries to lib64 rather than lib. Most distros seem to +# follow this convention with a couple notable exceptions (Debian-based and +# Arch-based distros) which we try to detect here. +if (CMAKE_SYSTEM_NAME MATCHES "Linux" AND + NOT DEFINED LIB_SUFFIX AND + NOT CMAKE_CROSSCOMPILING AND + CMAKE_SIZEOF_VOID_P EQUAL "8" AND + NOT EXISTS "/etc/debian_version" AND + NOT EXISTS "/etc/arch-release") + message("-- Detected non-Debian/Arch-based 64-bit Linux distribution. " + "Defaulting to library install directory: lib${LIB_SUFFIX}. You can " + "override this by specifying LIB_SUFFIX.") + set(LIB_SUFFIX "64") +endif () +# Only create the cache variable (for the CMake GUI) after attempting to detect +# the suffix *if not specified by the user* (NOT DEFINED LIB_SUFFIX in if()) +# s/t the user could override our autodetected suffix with "" if desired. +set(LIB_SUFFIX "${LIB_SUFFIX}" CACHE STRING + "Suffix of library install directory (to support lib/lib64)." FORCE) + +# IOS is defined iff using the iOS.cmake CMake toolchain to build a static +# library for iOS. +if (IOS) + message(STATUS "Building Ceres for iOS platform: ${IOS_PLATFORM}") + + # Ceres requires at least iOS 7.0+. + if (IOS_DEPLOYMENT_TARGET VERSION_LESS 7.0) + message(FATAL_ERROR "Unsupported iOS version: ${IOS_DEPLOYMENT_TARGET}, Ceres " + "requires at least iOS version 7.0") + endif() + + update_cache_variable(MINIGLOG ON) + message(STATUS "Building for iOS: Forcing use of miniglog instead of glog.") + + update_cache_variable(SUITESPARSE OFF) + update_cache_variable(CXSPARSE OFF) + update_cache_variable(GFLAGS OFF) + update_cache_variable(OPENMP OFF) + # Apple claims that the BLAS call dsyrk_ is a private API, and will not allow + # you to submit to the Apple Store if the symbol is present. + update_cache_variable(LAPACK OFF) + message(STATUS "Building for iOS: SuiteSparse, CXSparse, LAPACK, gflags, " + "and OpenMP are not available.") + + update_cache_variable(BUILD_EXAMPLES OFF) + message(STATUS "Building for iOS: Will not build examples.") +endif (IOS) + +unset(CERES_COMPILE_OPTIONS) + +# Eigen. +find_package(Eigen REQUIRED) +if (EIGEN_FOUND) + if (EIGEN_VERSION VERSION_LESS 3.1.0) + message(FATAL_ERROR "-- Ceres requires Eigen version >= 3.1.0 in order " + "that Eigen/SparseCore be available, detected version of Eigen is: " + "${EIGEN_VERSION}") + endif (EIGEN_VERSION VERSION_LESS 3.1.0) + + message("-- Found Eigen version ${EIGEN_VERSION}: ${EIGEN_INCLUDE_DIRS}") + # Ensure that only MPL2 licensed code is part of the default build. + message("") + message(" ===============================================================") + if (EIGENSPARSE) + list(APPEND CERES_COMPILE_OPTIONS CERES_USE_EIGEN_SPARSE) + message(" Enabling the use of Eigen as a sparse linear algebra library ") + message(" for solving the nonlinear least squares problems. Enabling ") + message(" this option results in an LGPL licensed version of ") + message(" Ceres Solver as the Simplicial Cholesky factorization in Eigen") + message(" is licensed under the LGPL. ") + + if (EIGEN_VERSION VERSION_LESS 3.2.2) + message(" WARNING:") + message("") + message(" Your version of Eigen is older than version 3.2.2.") + message(" The performance of SPARSE_NORMAL_CHOLESKY and SPARSE_SCHUR") + message(" linear solvers will suffer. ") + endif (EIGEN_VERSION VERSION_LESS 3.2.2) + + else (EIGENSPARSE) + message(" Disabling the use of Eigen as a sparse linear algebra library.") + message(" This does not affect the covariance estimation algorithm ") + message(" which can still use the EIGEN_SPARSE_QR algorithm.") + add_definitions(-DEIGEN_MPL2_ONLY) + endif (EIGENSPARSE) + message(" ===============================================================") + message("") +endif (EIGEN_FOUND) + +# LAPACK (& BLAS). +if (LAPACK) + find_package(LAPACK QUIET) + if (LAPACK_FOUND) + message("-- Found LAPACK library: ${LAPACK_LIBRARIES}") + else (LAPACK_FOUND) + message("-- Did not find LAPACK library, disabling LAPACK support.") + endif (LAPACK_FOUND) + + find_package(BLAS QUIET) + if (BLAS_FOUND) + message("-- Found BLAS library: ${BLAS_LIBRARIES}") + else (BLAS_FOUND) + message("-- Did not find BLAS library, disabling LAPACK support.") + endif (BLAS_FOUND) + + if (NOT (LAPACK_FOUND AND BLAS_FOUND)) + update_cache_variable(LAPACK OFF) + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_LAPACK) + endif (NOT (LAPACK_FOUND AND BLAS_FOUND)) +else (LAPACK) + message("-- Building without LAPACK.") + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_LAPACK) +endif (LAPACK) + +# SuiteSparse. +if (SUITESPARSE AND NOT LAPACK) + # If user has disabled LAPACK, but left SUITESPARSE ON, turn it OFF, + # LAPACK controls whether Ceres will be linked, directly or indirectly + # via SuiteSparse to LAPACK. + message("-- Disabling SuiteSparse as use of LAPACK has been disabled, " + "turn ON LAPACK to enable (optional) building with SuiteSparse.") + update_cache_variable(SUITESPARSE OFF) +endif (SUITESPARSE AND NOT LAPACK) +if (SUITESPARSE) + # By default, if SuiteSparse and all dependencies are found, Ceres is + # built with SuiteSparse support. + + # Check for SuiteSparse and dependencies. + find_package(SuiteSparse) + if (SUITESPARSE_FOUND) + # On Ubuntu the system install of SuiteSparse (v3.4.0) up to at least + # Ubuntu 13.10 cannot be used to link shared libraries. + if (BUILD_SHARED_LIBS AND + SUITESPARSE_IS_BROKEN_SHARED_LINKING_UBUNTU_SYSTEM_VERSION) + message(FATAL_ERROR "You are attempting to build Ceres as a shared " + "library on Ubuntu using a system package install of SuiteSparse " + "3.4.0. This package is broken and does not support the " + "construction of shared libraries (you can still build Ceres as " + "a static library). If you wish to build a shared version of Ceres " + "you should uninstall the system install of SuiteSparse " + "(libsuitesparse-dev) and perform a source install of SuiteSparse " + "(we recommend that you use the latest version), " + "see http://ceres-solver.org/building.html for more information.") + endif (BUILD_SHARED_LIBS AND + SUITESPARSE_IS_BROKEN_SHARED_LINKING_UBUNTU_SYSTEM_VERSION) + + # By default, if all of SuiteSparse's dependencies are found, Ceres is + # built with SuiteSparse support. + message("-- Found SuiteSparse ${SUITESPARSE_VERSION}, " + "building with SuiteSparse.") + else (SUITESPARSE_FOUND) + # Disable use of SuiteSparse if it cannot be found and continue. + message("-- Did not find all SuiteSparse dependencies, disabling " + "SuiteSparse support.") + update_cache_variable(SUITESPARSE OFF) + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_SUITESPARSE) + endif (SUITESPARSE_FOUND) +else (SUITESPARSE) + message("-- Building without SuiteSparse.") + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_SUITESPARSE) +endif (SUITESPARSE) + +# CXSparse. +if (CXSPARSE) + # Don't search with REQUIRED as we can continue without CXSparse. + find_package(CXSparse) + if (CXSPARSE_FOUND) + # By default, if CXSparse and all dependencies are found, Ceres is + # built with CXSparse support. + message("-- Found CXSparse version: ${CXSPARSE_VERSION}, " + "building with CXSparse.") + else (CXSPARSE_FOUND) + # Disable use of CXSparse if it cannot be found and continue. + message("-- Did not find CXSparse, Building without CXSparse.") + update_cache_variable(CXSPARSE OFF) + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_CXSPARSE) + endif (CXSPARSE_FOUND) +else (CXSPARSE) + message("-- Building without CXSparse.") + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_CXSPARSE) + # Mark as advanced (remove from default GUI view) the CXSparse search + # variables in case user enabled CXSPARSE, FindCXSparse did not find it, so + # made search variables visible in GUI for user to set, but then user disables + # CXSPARSE instead of setting them. + mark_as_advanced(FORCE CXSPARSE_INCLUDE_DIR + CXSPARSE_LIBRARY) +endif (CXSPARSE) + +# Ensure that the user understands they have disabled all sparse libraries. +if (NOT SUITESPARSE AND NOT CXSPARSE AND NOT EIGENSPARSE) + message(" ===============================================================") + message(" Compiling without any sparse library: SuiteSparse, CXSparse ") + message(" & Eigen (Sparse) are all disabled or unavailable. No sparse ") + message(" linear solvers (SPARSE_NORMAL_CHOLESKY & SPARSE_SCHUR)") + message(" will be available when Ceres is used.") + message(" ===============================================================") +endif(NOT SUITESPARSE AND NOT CXSPARSE AND NOT EIGENSPARSE) + +# GFlags. +if (GFLAGS) + # Don't search with REQUIRED as we can continue without gflags. + find_package(Gflags) + if (GFLAGS_FOUND) + message("-- Found Google Flags header in: ${GFLAGS_INCLUDE_DIRS}, " + "in namespace: ${GFLAGS_NAMESPACE}") + add_definitions(-DCERES_GFLAGS_NAMESPACE=${GFLAGS_NAMESPACE}) + else (GFLAGS_FOUND) + message("-- Did not find Google Flags (gflags), Building without gflags " + "- no tests or tools will be built!") + update_cache_variable(GFLAGS OFF) + endif (GFLAGS_FOUND) +else (GFLAGS) + message("-- Google Flags disabled; no tests or tools will be built!") + # Mark as advanced (remove from default GUI view) the gflags search + # variables in case user enabled GFLAGS, FindGflags did not find it, so + # made search variables visible in GUI for user to set, but then user disables + # GFLAGS instead of setting them. + mark_as_advanced(FORCE GFLAGS_INCLUDE_DIR + GFLAGS_LIBRARY + GFLAGS_NAMESPACE) +endif (GFLAGS) + +# MiniGLog. +if (MINIGLOG) + message("-- Compiling minimal glog substitute into Ceres.") + set(GLOG_INCLUDE_DIRS internal/ceres/miniglog) + set(MINIGLOG_MAX_LOG_LEVEL 2 CACHE STRING "The maximum message severity level to be logged") + add_definitions("-DMAX_LOG_LEVEL=${MINIGLOG_MAX_LOG_LEVEL}") + message("-- Using minimal glog substitute (include): ${GLOG_INCLUDE_DIRS}") + message("-- Max log level for minimal glog substitute: ${MINIGLOG_MAX_LOG_LEVEL}") + + # Mark as advanced (remove from default GUI view) the glog search + # variables in case user disables MINIGLOG, FindGlog did not find it, so + # made search variables visible in GUI for user to set, but then user enables + # MINIGLOG instead of setting them. + mark_as_advanced(FORCE GLOG_INCLUDE_DIR + GLOG_LIBRARY) +else (MINIGLOG) + unset(MINIGLOG_MAX_LOG_LEVEL CACHE) + # Don't search with REQUIRED so that configuration continues if not found and + # we can output an error messages explaining MINIGLOG option. + find_package(Glog) + if (NOT GLOG_FOUND) + message(FATAL_ERROR "Can't find Google Log (glog). Please set either: " + "glog_DIR (newer CMake built versions of glog) or GLOG_INCLUDE_DIR & " + "GLOG_LIBRARY or enable MINIGLOG option to use minimal glog " + "implementation.") + endif(NOT GLOG_FOUND) + # By default, assume gflags was found, updating the message if it was not. + set(GLOG_GFLAGS_DEPENDENCY_MESSAGE + " Assuming glog was built with gflags support as gflags was found. " + "This will make gflags a public dependency of Ceres.") + if (NOT GFLAGS_FOUND) + set(GLOG_GFLAGS_DEPENDENCY_MESSAGE + " Assuming glog was NOT built with gflags support as gflags was " + "not found. If glog was built with gflags, please set the " + "gflags search locations such that it can be found by Ceres. " + "Otherwise, Ceres may fail to link due to missing gflags symbols.") + endif(NOT GFLAGS_FOUND) + message("-- Found Google Log (glog)." ${GLOG_GFLAGS_DEPENDENCY_MESSAGE}) +endif (MINIGLOG) + +if (NOT SCHUR_SPECIALIZATIONS) + list(APPEND CERES_COMPILE_OPTIONS CERES_RESTRICT_SCHUR_SPECIALIZATION) + message("-- Disabling Schur specializations (faster compiles)") +endif (NOT SCHUR_SPECIALIZATIONS) + +if (NOT CUSTOM_BLAS) + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_CUSTOM_BLAS) + message("-- Disabling custom blas") +endif (NOT CUSTOM_BLAS) + +if (OPENMP) + # Find quietly, as we can continue without OpenMP if it is not found. + find_package(OpenMP QUIET) + if (OPENMP_FOUND) + message("-- Building with OpenMP.") + list(APPEND CERES_COMPILE_OPTIONS CERES_USE_OPENMP) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${OpenMP_CXX_FLAGS}") + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${OpenMP_C_FLAGS}") + if (UNIX) + # At least on Linux, we need pthreads to be enabled for mutex to + # compile. This may not work on Windows or Android. + find_package(Threads REQUIRED) + list(APPEND CERES_COMPILE_OPTIONS CERES_HAVE_PTHREAD) + list(APPEND CERES_COMPILE_OPTIONS CERES_HAVE_RWLOCK) + endif (UNIX) + else (OPENMP_FOUND) + message("-- Failed to find OpenMP, disabling. This is expected on " + "Clang < 3.8, and at least Xcode <= 7.") + update_cache_variable(OPENMP OFF) + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_THREADS) + endif (OPENMP_FOUND) +else (OPENMP) + message("-- Building without OpenMP (disabling multithreading).") + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_THREADS) +endif (OPENMP) + +# Initialise CMAKE_REQUIRED_FLAGS used by CheckCXXSourceCompiles with the +# contents of CMAKE_CXX_FLAGS such that if the user has passed extra flags +# they are used when discovering shared_ptr/unordered_map. +set(CMAKE_REQUIRED_FLAGS ${CMAKE_CXX_FLAGS}) + +include(CheckCXXCompilerFlag) +check_cxx_compiler_flag("-std=c++11" COMPILER_HAS_CXX11_FLAG) +if (CXX11 AND COMPILER_HAS_CXX11_FLAG) + # Update CMAKE_REQUIRED_FLAGS used by CheckCXXSourceCompiles to include + # -std=c++11 s/t we will detect the C++11 versions of unordered_map & + # shared_ptr if they exist. + set(CMAKE_REQUIRED_FLAGS "${CMAKE_REQUIRED_FLAGS} -std=c++11") +endif (CXX11 AND COMPILER_HAS_CXX11_FLAG) + +# Set the Ceres compile definitions for the unordered_map configuration. +include(FindUnorderedMap) +find_unordered_map() +if (UNORDERED_MAP_FOUND) + if (HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + list(APPEND CERES_COMPILE_OPTIONS CERES_STD_UNORDERED_MAP) + endif(HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + if (HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + list(APPEND CERES_COMPILE_OPTIONS CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE) + endif(HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + if (HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) + list(APPEND CERES_COMPILE_OPTIONS CERES_TR1_UNORDERED_MAP) + endif(HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) +else (UNORDERED_MAP_FOUND) + message("-- Replacing unordered_map/set with map/set (warning: slower!), " + "try enabling CXX11 option if you expect C++11 to be available.") + list(APPEND CERES_COMPILE_OPTIONS CERES_NO_UNORDERED_MAP) +endif() + +# Set the Ceres compile definitions for the shared_ptr configuration. +include(FindSharedPtr) +find_shared_ptr() +if (SHARED_PTR_FOUND) + if (SHARED_PTR_TR1_MEMORY_HEADER) + list(APPEND CERES_COMPILE_OPTIONS CERES_TR1_MEMORY_HEADER) + endif (SHARED_PTR_TR1_MEMORY_HEADER) + if (SHARED_PTR_TR1_NAMESPACE) + list(APPEND CERES_COMPILE_OPTIONS CERES_TR1_SHARED_PTR) + endif (SHARED_PTR_TR1_NAMESPACE) +else (SHARED_PTR_FOUND) + message(FATAL_ERROR "Unable to find shared_ptr, try enabling CXX11 option " + "if you expect C++11 to be available.") +endif (SHARED_PTR_FOUND) + +# To ensure that CXX11 accurately reflects whether we are using C++11, +# check if it is required given where the potentially C++11 features Ceres +# uses were found, and disable it if C++11 is not being used. +if (CXX11) + if (NOT HAVE_SHARED_PTR_IN_STD_NAMESPACE AND + NOT HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + message("-- Failed to find C++11 components in C++11 locations & " + "namespaces, disabling CXX11.") + update_cache_variable(CXX11 OFF) + else() + message(" ==============================================================") + message(" Compiling Ceres using C++11. This will result in a version ") + message(" of Ceres that will require the use of C++11 in client code.") + message(" ==============================================================") + list(APPEND CERES_COMPILE_OPTIONS CERES_USE_CXX11) + if (COMPILER_HAS_CXX11_FLAG AND + CMAKE_VERSION VERSION_LESS "2.8.12") + # For CMake versions > 2.8.12, the C++11 dependency is rolled into the + # Ceres target, and all dependent targets, but for older versions of CMake + # the flag must be specified explicitly both for Ceres and the + # examples/tests. + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11") + endif() + endif() +endif(CXX11) + +include_directories( + include + internal + internal/ceres + ${GLOG_INCLUDE_DIRS}) +# Eigen SparseQR generates various compiler warnings related to unused and +# uninitialised local variables. To avoid having to individually suppress these +# warnings around the #include statments for Eigen headers across all GCC/Clang +# versions, we tell CMake to treat Eigen headers as system headers. This +# results in all compiler warnings from them being suppressed. +# +# Note that this is *not* propagated to clients, ie CERES_INCLUDE_DIRS +# used by clients after find_package(Ceres) does not identify Eigen as +# as system headers. +include_directories(SYSTEM ${EIGEN_INCLUDE_DIRS}) + +if (SUITESPARSE) + include_directories(${SUITESPARSE_INCLUDE_DIRS}) +endif (SUITESPARSE) + +if (CXSPARSE) + include_directories(${CXSPARSE_INCLUDE_DIRS}) +endif (CXSPARSE) + +if (GFLAGS) + include_directories(${GFLAGS_INCLUDE_DIRS}) +endif (GFLAGS) + +if (BUILD_SHARED_LIBS) + message("-- Building Ceres as a shared library.") + # The CERES_BUILDING_SHARED_LIBRARY compile definition is NOT stored in + # CERES_COMPILE_OPTIONS as it must only be defined when Ceres is compiled + # not when it is used as it controls the CERES_EXPORT macro which provides + # dllimport/export support in MSVC. + add_definitions(-DCERES_BUILDING_SHARED_LIBRARY) + list(APPEND CERES_COMPILE_OPTIONS CERES_USING_SHARED_LIBRARY) +else (BUILD_SHARED_LIBS) + message("-- Building Ceres as a static library.") +endif (BUILD_SHARED_LIBS) + +# Change the default build type from Debug to Release, while still +# supporting overriding the build type. +# +# The CACHE STRING logic here and elsewhere is needed to force CMake +# to pay attention to the value of these variables. +if (NOT CMAKE_BUILD_TYPE) + message("-- No build type specified; defaulting to CMAKE_BUILD_TYPE=Release.") + set(CMAKE_BUILD_TYPE Release CACHE STRING + "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel." + FORCE) +else (NOT CMAKE_BUILD_TYPE) + if (CMAKE_BUILD_TYPE STREQUAL "Debug") + message("\n=================================================================================") + message("\n-- Build type: Debug. Performance will be terrible!") + message("-- Add -DCMAKE_BUILD_TYPE=Release to the CMake command line to get an optimized build.") + message("\n=================================================================================") + endif (CMAKE_BUILD_TYPE STREQUAL "Debug") +endif (NOT CMAKE_BUILD_TYPE) + +# Set the default Ceres flags to an empty string. +set (CERES_CXX_FLAGS) + +if (CMAKE_BUILD_TYPE STREQUAL "Release") + if (CMAKE_COMPILER_IS_GNUCXX) + # Linux + if (CMAKE_SYSTEM_NAME MATCHES "Linux") + if (NOT GCC_VERSION VERSION_LESS 4.2) + set (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -march=native -mtune=native") + endif (NOT GCC_VERSION VERSION_LESS 4.2) + endif (CMAKE_SYSTEM_NAME MATCHES "Linux") + # Mac OS X + if (CMAKE_SYSTEM_NAME MATCHES "Darwin") + set (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -msse3") + # Use of -fast only applicable for Apple's GCC + # Assume this is being used if GCC version < 4.3 on OSX + execute_process(COMMAND ${CMAKE_C_COMPILER} + ARGS ${CMAKE_CXX_COMPILER_ARG1} -dumpversion + OUTPUT_VARIABLE GCC_VERSION + OUTPUT_STRIP_TRAILING_WHITESPACE) + if (GCC_VERSION VERSION_LESS 4.3) + set (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -fast") + endif (GCC_VERSION VERSION_LESS 4.3) + endif (CMAKE_SYSTEM_NAME MATCHES "Darwin") + endif (CMAKE_COMPILER_IS_GNUCXX) +endif (CMAKE_BUILD_TYPE STREQUAL "Release") + +set (CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} ${CERES_CXX_FLAGS}") + +if (MINGW) + # MinGW produces code that segfaults when performing matrix multiplications + # in Eigen when compiled with -O3 (see [1]), as such force the use of -O2 + # which works. + # + # [1] http://eigen.tuxfamily.org/bz/show_bug.cgi?id=556 + message("-- MinGW detected, forcing -O2 instead of -O3 in Release for Eigen due " + "to a MinGW bug: http://eigen.tuxfamily.org/bz/show_bug.cgi?id=556") + string(REPLACE "-O3" "-O2" CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE}") + update_cache_variable(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE}") +endif (MINGW) + +# After the tweaks for the compile settings, disable some warnings on MSVC. +if (MSVC) + # On MSVC, math constants are not included in or unless + # _USE_MATH_DEFINES is defined [1]. As we use M_PI in the examples, ensure + # that _USE_MATH_DEFINES is defined before the first inclusion of . + # + # [1] https://msdn.microsoft.com/en-us/library/4hwaceh6.aspx + add_definitions("-D_USE_MATH_DEFINES") + # Disable signed/unsigned int conversion warnings. + add_definitions("/wd4018") + # Disable warning about using struct/class for the same symobl. + add_definitions("/wd4099") + # Disable warning about the insecurity of using "std::copy". + add_definitions("/wd4996") + # Disable performance warning about int-to-bool conversion. + add_definitions("/wd4800") + # Disable performance warning about fopen insecurity. + add_definitions("/wd4996") + # Disable warning about int64 to int32 conversion. Disabling + # this warning may not be correct; needs investigation. + # TODO(keir): Investigate these warnings in more detail. + add_definitions("/wd4244") + # It's not possible to use STL types in DLL interfaces in a portable and + # reliable way. However, that's what happens with Google Log and Google Flags + # on Windows. MSVC gets upset about this and throws warnings that we can't do + # much about. The real solution is to link static versions of Google Log and + # Google Test, but that seems tricky on Windows. So, disable the warning. + add_definitions("/wd4251") + + # Google Flags doesn't have their DLL import/export stuff set up correctly, + # which results in linker warnings. This is irrelevant for Ceres, so ignore + # the warnings. + set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /ignore:4049") + + # Update the C/CXX flags for MSVC to use either the static or shared + # C-Run Time (CRT) library based on the user option: MSVC_USE_STATIC_CRT. + list(APPEND C_CXX_FLAGS + CMAKE_CXX_FLAGS + CMAKE_CXX_FLAGS_DEBUG + CMAKE_CXX_FLAGS_RELEASE + CMAKE_CXX_FLAGS_MINSIZEREL + CMAKE_CXX_FLAGS_RELWITHDEBINFO) + + foreach(FLAG_VAR ${C_CXX_FLAGS}) + if (MSVC_USE_STATIC_CRT) + # Use static CRT. + if (${FLAG_VAR} MATCHES "/MD") + string(REGEX REPLACE "/MD" "/MT" ${FLAG_VAR} "${${FLAG_VAR}}") + endif (${FLAG_VAR} MATCHES "/MD") + else (MSVC_USE_STATIC_CRT) + # Use shared, not static, CRT. + if (${FLAG_VAR} MATCHES "/MT") + string(REGEX REPLACE "/MT" "/MD" ${FLAG_VAR} "${${FLAG_VAR}}") + endif (${FLAG_VAR} MATCHES "/MT") + endif (MSVC_USE_STATIC_CRT) + endforeach() + + # Tuple sizes of 10 are used by Gtest. + add_definitions("-D_VARIADIC_MAX=10") + + include(CheckIfUnderscorePrefixedBesselFunctionsExist) + check_if_underscore_prefixed_bessel_functions_exist( + HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + if (HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + list(APPEND CERES_COMPILE_OPTIONS + CERES_MSVC_USE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + endif() +endif (MSVC) + +if (UNIX) + # GCC is not strict enough by default, so enable most of the warnings. + set(CMAKE_CXX_FLAGS + "${CMAKE_CXX_FLAGS} -Wno-unknown-pragmas -Wno-sign-compare -Wno-unused-parameter -Wno-missing-field-initializers") +endif (UNIX) + +# Use a larger inlining threshold for Clang, since it hobbles Eigen, +# resulting in an unreasonably slow version of the blas routines. The +# -Qunused-arguments is needed because CMake passes the inline +# threshold to the linker and clang complains about it and dies. +if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + set(CMAKE_CXX_FLAGS + "${CMAKE_CXX_FLAGS} -Qunused-arguments -mllvm -inline-threshold=600") + + # Older versions of Clang (<= 2.9) do not support the 'return-type-c-linkage' + # option, so check for its presence before adding it to the default flags set. + include(CheckCXXCompilerFlag) + check_cxx_compiler_flag("-Wno-return-type-c-linkage" + HAVE_RETURN_TYPE_C_LINKAGE) + if (HAVE_RETURN_TYPE_C_LINKAGE) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-return-type-c-linkage") + endif(HAVE_RETURN_TYPE_C_LINKAGE) +endif () + +# Xcode 4.5.x used Clang 4.1 (Apple version), this has a bug that prevents +# compilation of Ceres. +if (APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + execute_process(COMMAND ${CMAKE_CXX_COMPILER} + ARGS ${CMAKE_CXX_COMPILER_ARG1} -dumpversion + OUTPUT_VARIABLE CLANG_VERSION + OUTPUT_STRIP_TRAILING_WHITESPACE) + # Use version > 4.0 & < 4.2 to catch all 4.1(.x) versions. + if (CLANG_VERSION VERSION_GREATER 4.0 AND + CLANG_VERSION VERSION_LESS 4.2) + message(FATAL_ERROR "You are attempting to build Ceres on OS X using Xcode " + "4.5.x (Clang version: ${CLANG_VERSION}). This version of Clang has a " + "bug that prevents compilation of Ceres, please update to " + "Xcode >= 4.6.3.") + endif (CLANG_VERSION VERSION_GREATER 4.0 AND + CLANG_VERSION VERSION_LESS 4.2) +endif (APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + +# Configure the Ceres config.h compile options header using the current +# compile options and put the configured header into the Ceres build +# directory. Note that the ceres/internal subdir in /config where +# the configured config.h is placed is important, because Ceres will be +# built against this configured header, it needs to have the same relative +# include path as it would if it were in the source tree (or installed). +list(REMOVE_DUPLICATES CERES_COMPILE_OPTIONS) +include(CreateCeresConfig) +create_ceres_config("${CERES_COMPILE_OPTIONS}" + ${Ceres_BINARY_DIR}/config/ceres/internal) +# Force the location containing the configured config.h to the front of the +# include_directories list (by default it is appended to the back) to ensure +# that if the user has an installed version of Ceres in the same location as one +# of the dependencies (e.g. /usr/local) that we find the config.h we just +# configured, not the (older) installed config.h. +include_directories(BEFORE ${Ceres_BINARY_DIR}/config) + +add_subdirectory(internal/ceres) + +if (BUILD_DOCUMENTATION) + set(CERES_DOCS_INSTALL_DIR "share/doc/ceres" CACHE STRING + "Ceres docs install path relative to CMAKE_INSTALL_PREFIX") + + find_package(Sphinx QUIET) + if (NOT SPHINX_FOUND) + message("-- Failed to find Sphinx, disabling build of documentation.") + update_cache_variable(BUILD_DOCUMENTATION OFF) + else() + # Generate the User's Guide (html). + # The corresponding target is ceres_docs, but is included in ALL. + message("-- Build the HTML documentation.") + add_subdirectory(docs) + endif() +endif (BUILD_DOCUMENTATION) + +if (BUILD_EXAMPLES) + message("-- Build the examples.") + add_subdirectory(examples) +else (BUILD_EXAMPLES) + message("-- Do not build any example.") +endif (BUILD_EXAMPLES) + +# Setup installation of Ceres public headers. +file(GLOB CERES_HDRS ${Ceres_SOURCE_DIR}/include/ceres/*.h) +install(FILES ${CERES_HDRS} DESTINATION include/ceres) + +file(GLOB CERES_PUBLIC_INTERNAL_HDRS ${Ceres_SOURCE_DIR}/include/ceres/internal/*.h) +install(FILES ${CERES_PUBLIC_INTERNAL_HDRS} DESTINATION include/ceres/internal) + +# Also setup installation of Ceres config.h configured with the current +# build options into the installed headers directory. +install(FILES ${Ceres_BINARY_DIR}/config/ceres/internal/config.h + DESTINATION include/ceres/internal) + +if (MINIGLOG) + # Install miniglog header if being used as logging #includes appear in + # installed public Ceres headers. + install(FILES ${Ceres_SOURCE_DIR}/internal/ceres/miniglog/glog/logging.h + DESTINATION include/ceres/internal/miniglog/glog) +endif (MINIGLOG) + +# Ceres supports two mechanisms by which it can be detected & imported into +# client code which uses CMake via find_package(Ceres): +# +# 1) Installation (e.g. to /usr/local), using CMake's install() function. +# +# 2) (Optional) Export of the current build directory into the local CMake +# package registry, using CMake's export() function. This allows use of +# Ceres from other projects without requiring installation. +# +# In both cases, we need to generate a configured CeresConfig.cmake which +# includes additional autogenerated files which in concert create an imported +# target for Ceres in a client project when find_package(Ceres) is invoked. +# The key distinctions are where this file is located, and whether client code +# references installed copies of the compiled Ceres headers/libraries, +# (option #1: installation), or the originals in the source/build directories +# (option #2: export of build directory). +# +# NOTE: If Ceres is both exported and installed, provided that the installation +# path is present in CMAKE_MODULE_PATH when find_package(Ceres) is called, +# the installed version is preferred. + +# Build the list of Ceres components for CeresConfig.cmake from the current set +# of compile options. +include(CeresCompileOptionsToComponents) +ceres_compile_options_to_components("${CERES_COMPILE_OPTIONS}" + CERES_COMPILED_COMPONENTS) + +# Create a CeresConfigVersion.cmake file containing the version information, +# used by both export() & install(). +configure_file("${Ceres_SOURCE_DIR}/cmake/CeresConfigVersion.cmake.in" + "${Ceres_BINARY_DIR}/CeresConfigVersion.cmake" @ONLY) + +# Install method #1: Put Ceres in CMAKE_INSTALL_PREFIX: /usr/local or equivalent. + +# Set the install path for the installed CeresConfig.cmake configuration file +# relative to CMAKE_INSTALL_PREFIX. +if (WIN32) + set(RELATIVE_CMAKECONFIG_INSTALL_DIR CMake) +else () + set(RELATIVE_CMAKECONFIG_INSTALL_DIR lib${LIB_SUFFIX}/cmake/Ceres) +endif () + +# This "exports" for installation all targets which have been put into the +# export set "CeresExport". This generates a CeresTargets.cmake file which, +# when read in by a client project as part of find_package(Ceres) creates +# imported library targets for Ceres (with dependency relations) which can be +# used in target_link_libraries() calls in the client project to use Ceres. +install(EXPORT CeresExport + DESTINATION ${RELATIVE_CMAKECONFIG_INSTALL_DIR} FILE CeresTargets.cmake) + +# Save the relative path from the installed CeresConfig.cmake file to the +# install prefix. We do not save an absolute path in case the installed package +# is subsequently relocated after installation (on Windows). +file(RELATIVE_PATH INSTALL_ROOT_REL_CONFIG_INSTALL_DIR + ${CMAKE_INSTALL_PREFIX}/${RELATIVE_CMAKECONFIG_INSTALL_DIR} + ${CMAKE_INSTALL_PREFIX}) + +# Configure a CeresConfig.cmake file for an installed version of Ceres from the +# template, reflecting the current build options. +# +# NOTE: The -install suffix is necessary to distinguish the install version from +# the exported version, which must be named CeresConfig.cmake in +# Ceres_BINARY_DIR to be detected. The suffix is removed when +# it is installed. +set(SETUP_CERES_CONFIG_FOR_INSTALLATION TRUE) +configure_file("${Ceres_SOURCE_DIR}/cmake/CeresConfig.cmake.in" + "${Ceres_BINARY_DIR}/CeresConfig-install.cmake" @ONLY) + +# Install the configuration files into the same directory as the autogenerated +# CeresTargets.cmake file. We include the find_package() scripts for libraries +# whose headers are included in the public API of Ceres and should thus be +# present in CERES_INCLUDE_DIRS. +install(FILES "${Ceres_BINARY_DIR}/CeresConfig-install.cmake" + RENAME CeresConfig.cmake + DESTINATION ${RELATIVE_CMAKECONFIG_INSTALL_DIR}) +install(FILES "${Ceres_BINARY_DIR}/CeresConfigVersion.cmake" + "${Ceres_SOURCE_DIR}/cmake/FindEigen.cmake" + "${Ceres_SOURCE_DIR}/cmake/FindGlog.cmake" + "${Ceres_SOURCE_DIR}/cmake/FindGflags.cmake" + DESTINATION ${RELATIVE_CMAKECONFIG_INSTALL_DIR}) + +# Create an uninstall target to remove all installed files. +configure_file("${Ceres_SOURCE_DIR}/cmake/uninstall.cmake.in" + "${Ceres_BINARY_DIR}/cmake/uninstall.cmake" + @ONLY) +add_custom_target(uninstall + COMMAND ${CMAKE_COMMAND} -P ${Ceres_BINARY_DIR}/cmake/uninstall.cmake) + +# Install method #2: Put Ceres build into local CMake registry. +# +# Optionally export the Ceres build directory into the local CMake package +# registry (~/.cmake/packages on *nix & OS X). This allows the detection & +# use of Ceres without requiring that it be installed. +if (EXPORT_BUILD_DIR) + message("-- Export Ceres build directory to local CMake package registry.") + + # Save the relative path from the build directory to the source directory. + file(RELATIVE_PATH INSTALL_ROOT_REL_CONFIG_INSTALL_DIR + ${Ceres_BINARY_DIR} + ${Ceres_SOURCE_DIR}) + + # Analogously to install(EXPORT ...), export the Ceres target from the build + # directory as a package called Ceres into the local CMake package registry. + export(TARGETS ceres FILE ${Ceres_BINARY_DIR}/CeresTargets.cmake) + export(PACKAGE ${CMAKE_PROJECT_NAME}) + + # Configure a CeresConfig.cmake file for the export of the Ceres build + # directory from the template, reflecting the current build options. + set(SETUP_CERES_CONFIG_FOR_INSTALLATION FALSE) + configure_file("${Ceres_SOURCE_DIR}/cmake/CeresConfig.cmake.in" + "${Ceres_BINARY_DIR}/CeresConfig.cmake" @ONLY) + +endif (EXPORT_BUILD_DIR) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cae4255 --- /dev/null +++ b/LICENSE @@ -0,0 +1,27 @@ +Ceres Solver - A fast non-linear least squares minimizer +Copyright 2015 Google Inc. All rights reserved. +http://ceres-solver.org/ + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. +* Neither the name of Google Inc. nor the names of its contributors may be + used to endorse or promote products derived from this software without + specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..3f8dbe1 --- /dev/null +++ b/README.md @@ -0,0 +1,26 @@ +Ceres Solver +============ + +Ceres Solver is an open source C++ library for modeling and solving +large, complicated optimization problems. It is a feature rich, mature +and performant library which has been used in production at Google +since 2010. Ceres Solver can solve two kinds of problems. + +1. Non-linear Least Squares problems with bounds constraints. +2. General unconstrained optimization problems. + +Please see [ceres-solver.org](http://ceres-solver.org/) for more +information. + +WARNING - Do not make GitHub pull requests! +------------------------------------------- + +Ceres development happens on +[Gerrit](https://ceres-solver.googlesource.com/), including both +repository hosting and code reviews. The GitHub Repository is a +continuously updated mirror which is primarily meant for issue +tracking. Please see our [Contributing to Ceres Guide](http://ceres-solver.org/contributing.html) for more details. + +The upstream Gerrit repository is + + https://ceres-solver.googlesource.com/ceres-solver diff --git a/cmake/AddCeresCXX11RequirementsToTarget.cmake b/cmake/AddCeresCXX11RequirementsToTarget.cmake new file mode 100644 index 0000000..107eb58 --- /dev/null +++ b/cmake/AddCeresCXX11RequirementsToTarget.cmake @@ -0,0 +1,84 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2017 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) + +# Adds Ceres' C++11 requirements to a target such that they are exported when +# the target is exported (if the version of CMake supports it). +# +# add_ceres_cxx11_requirements_to_target( [target1 [target2 [...]]] ) +function(add_ceres_cxx11_requirements_to_target) + include(CheckCXXCompilerFlag) + check_cxx_compiler_flag("-std=c++11" COMPILER_HAS_CXX11_FLAG) + + foreach(TARGET ${ARGN}) + if (NOT TARGET ${TARGET}) + message(FATAL_ERROR "Specified target to append Ceres C++11 requirements " + "to: ${TARGET} is not a declared CMake target.") + endif() + + if (COMPILER_HAS_CXX11_FLAG) + # IMPORTANT: It is not sufficient to specify the + # CXX_STANDARD/CXX_STANDARD_REQUIRED target properties + # as these target properties are NOT exported. + if (CMAKE_VERSION VERSION_LESS "2.8.12") + # CMake version < 2.8.12 does not support target_compile_options(), warn + # user that they will have to add compile flags to their own projects + # manually. + message(WARNING "-- Warning: Detected CMake version: ${CMAKE_VERSION} " + "< 2.8.12, which is the minimum required for compile options to be " + "included in an exported CMake target and the detected. compiler " + "requires -std=c++11. The client is responsible for adding " + "-std=c++11 when linking against: ${TARGET}.") + elseif (COMMAND target_compile_features) + # CMake >= 3.1, use new target_compile_features() to specify Ceres' + # C++11 requirements as used in the public API. This assumes that + # C++11 STL features are available if the specified features are + # available. We do not use the cxx_std_11 feature to specify this as + # this did not come in until CMake 3.8. + # + # The reason to prefer using target_compile_features() if it exists is + # that this handles 'upgrading' of the C++ standard required more + # gracefully, e.g. if a client of Ceres requires C++14, but Ceres was + # compiled against C++11 then target_compile_options() may not work as + # expected. + target_compile_features( + ${TARGET} PUBLIC cxx_alignas cxx_alignof cxx_constexpr) + else() + # CMake version >= 2.8.12 && < 3.1 supports target_compile_options() + # but not target_compile_features(). For these intermediary versions, + # we use target_compile_options() to manually specify the C++11 flag and + # export it for client targets that depend on the target iff they are + # NOT compiling for C. We check for not C, rather than C++ as + # LINKER_LANGUAGE is often NOTFOUND and then uses the default (C++). + target_compile_options(${TARGET} PUBLIC + $<$,C>>:-std=c++11>) + endif() + endif() + endforeach() +endfunction() diff --git a/cmake/AddGerritCommitHook.cmake b/cmake/AddGerritCommitHook.cmake new file mode 100644 index 0000000..65b2fab --- /dev/null +++ b/cmake/AddGerritCommitHook.cmake @@ -0,0 +1,84 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Authors: keir@google.com (Keir Mierle) +# alexs.mac@gmail.com (Alex Stewart) + +# Set up the git hook to make Gerrit Change-Id: lines in commit messages. +function(ADD_GERRIT_COMMIT_HOOK SOURCE_DIR BINARY_DIR) + if (NOT (EXISTS ${SOURCE_DIR} AND IS_DIRECTORY ${SOURCE_DIR})) + message(FATAL_ERROR "Specified SOURCE_DIR: ${SOURCE_DIR} does not exist, " + "or is not a directory, cannot add Gerrit commit hook.") + endif() + if (NOT (EXISTS ${BINARY_DIR} AND IS_DIRECTORY ${BINARY_DIR})) + message(FATAL_ERROR "Specified BINARY_DIR: ${BINARY_DIR} does not exist, " + "or is not a directory, cannot add Gerrit commit hook.") + endif() + unset (LOCAL_GIT_DIRECTORY) + if (EXISTS ${SOURCE_DIR}/.git) + if (IS_DIRECTORY ${SOURCE_DIR}/.git) + # .git directory can be found on Unix based system, or on Windows with + # Git Bash (shipped with msysgit). + set (LOCAL_GIT_DIRECTORY ${SOURCE_DIR}/.git) + else(IS_DIRECTORY ${SOURCE_DIR}/.git) + # .git is a file, this means Ceres is a git submodule of another project + # and our .git file contains the path to the git directory which manages + # Ceres, so we should add the gerrit hook there. + file(READ ${SOURCE_DIR}/.git GIT_SUBMODULE_FILE_CONTENTS) + # Strip any trailing newline characters, s/t we get a valid path. + string(REGEX REPLACE "gitdir:[ ]*([^$].*)[\n].*" "${SOURCE_DIR}/\\1" + GIT_SUBMODULE_GIT_DIRECTORY_PATH "${GIT_SUBMODULE_FILE_CONTENTS}") + get_filename_component(GIT_SUBMODULE_GIT_DIRECTORY_PATH + "${GIT_SUBMODULE_GIT_DIRECTORY_PATH}" ABSOLUTE) + if (EXISTS ${GIT_SUBMODULE_GIT_DIRECTORY_PATH} + AND IS_DIRECTORY ${GIT_SUBMODULE_GIT_DIRECTORY_PATH}) + set(LOCAL_GIT_DIRECTORY "${GIT_SUBMODULE_GIT_DIRECTORY_PATH}") + endif() + endif() + else (EXISTS ${SOURCE_DIR}/.git) + # TODO(keir) Add proper Windows support. + endif (EXISTS ${SOURCE_DIR}/.git) + + if (EXISTS ${LOCAL_GIT_DIRECTORY}) + if (NOT EXISTS ${LOCAL_GIT_DIRECTORY}/hooks/commit-msg) + message(STATUS "Detected Ceres being used as a git submodule, adding " + "commit hook for Gerrit to: ${LOCAL_GIT_DIRECTORY}") + # Download the hook only if it is not already present. + file(DOWNLOAD https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg + ${BINARY_DIR}/commit-msg) + + # Make the downloaded file executable, since it is not by default. + file(COPY ${BINARY_DIR}/commit-msg + DESTINATION ${LOCAL_GIT_DIRECTORY}/hooks/ + FILE_PERMISSIONS + OWNER_READ OWNER_WRITE OWNER_EXECUTE + GROUP_READ GROUP_WRITE GROUP_EXECUTE + WORLD_READ WORLD_EXECUTE) + endif (NOT EXISTS ${LOCAL_GIT_DIRECTORY}/hooks/commit-msg) + endif (EXISTS ${LOCAL_GIT_DIRECTORY}) +endfunction() diff --git a/cmake/AppendTargetProperty.cmake b/cmake/AppendTargetProperty.cmake new file mode 100644 index 0000000..e0bc3a4 --- /dev/null +++ b/cmake/AppendTargetProperty.cmake @@ -0,0 +1,61 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) + +# Append item(s) to a property on a declared CMake target: +# +# append_target_property(target property item_to_append1 +# [... item_to_appendN]) +# +# The set_target_properties() CMake function will overwrite the contents of the +# specified target property. This function instead appends to it, so can +# be called multiple times with the same target & property to iteratively +# populate it. +function(append_target_property TARGET PROPERTY) + if (NOT TARGET ${TARGET}) + message(FATAL_ERROR "Invalid target: ${TARGET} cannot append: ${ARGN} " + "to property: ${PROPERTY}") + endif() + if (NOT PROPERTY) + message(FATAL_ERROR "Invalid property to update for target: ${TARGET}") + endif() + # Get the initial state of the specified property for the target s/t + # we can append to it (not overwrite it). + get_target_property(INITIAL_PROPERTY_STATE ${TARGET} ${PROPERTY}) + if (NOT INITIAL_PROPERTY_STATE) + # Ensure that if the state is unset, we do not insert the XXX-NOTFOUND + # returned by CMake into the property. + set(INITIAL_PROPERTY_STATE "") + endif() + # Delistify (remove ; separators) the potentially set of items to append + # to the specified target property. + string(REPLACE ";" " " ITEMS_TO_APPEND "${ARGN}") + set_target_properties(${TARGET} PROPERTIES ${PROPERTY} + "${INITIAL_PROPERTY_STATE} ${ITEMS_TO_APPEND}") +endfunction() diff --git a/cmake/CeresCompileOptionsToComponents.cmake b/cmake/CeresCompileOptionsToComponents.cmake new file mode 100644 index 0000000..7177475 --- /dev/null +++ b/cmake/CeresCompileOptionsToComponents.cmake @@ -0,0 +1,91 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2016 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Authors: alexs.mac@gmail.com (Alex Stewart) +# + +# Conditionally add a value to the output list based on whether the specified +# value is found in the input list. +function(update_output_if_found INPUT_LIST_VAR OUTPUT_LIST_VAR ITEM_TO_FIND VAR_TO_COPY_IF_FOUND VAR_TO_COPY_IF_NOT_FOUND) + list(FIND ${INPUT_LIST_VAR} "${ITEM_TO_FIND}" HAVE_ITEM) + # list(FIND ..) returns -1 if the element was not in the list, but CMake + # interprets if (VAR) to be true if VAR is any non-zero number, even + # negative ones, hence we have to explicitly check for >= 0. + if (HAVE_ITEM GREATER -1) + list(APPEND ${OUTPUT_LIST_VAR} "${VAR_TO_COPY_IF_FOUND}") + else() + list(APPEND ${OUTPUT_LIST_VAR} "${VAR_TO_COPY_IF_NOT_FOUND}") + endif() + set(${OUTPUT_LIST_VAR} ${${OUTPUT_LIST_VAR}} PARENT_SCOPE) +endfunction() + +# Helpers for update_output_if_found() to improve legibility when dealing with +# USE_XXX & NO_XXX option types in ceres_compile_options_to_components(). +macro(add_to_output_if_found INPUT_LIST_VAR OUTPUT_LIST_VAR ITEM_TO_FIND VAR_TO_COPY_IF_FOUND) + update_output_if_found(${INPUT_LIST_VAR} + ${OUTPUT_LIST_VAR} + "${ITEM_TO_FIND}" + "${VAR_TO_COPY_IF_FOUND}" + "") # Copy nothing if not found. +endmacro() + +macro(add_to_output_if_not_found INPUT_LIST_VAR OUTPUT_LIST_VAR ITEM_TO_FIND VAR_TO_COPY_IF_NOT_FOUND) + update_output_if_found(${INPUT_LIST_VAR} + ${OUTPUT_LIST_VAR} + "${ITEM_TO_FIND}" + "" # Copy nothing if found + "${VAR_TO_COPY_IF_NOT_FOUND}") +endmacro() + +# Convert the Ceres compile options specified by: CURRENT_CERES_COMPILE_OPTIONS +# into the correponding list of Ceres components (names), which may be used in: +# find_package(Ceres COMPONENTS ). +function(ceres_compile_options_to_components CURRENT_CERES_COMPILE_OPTIONS CERES_COMPONENTS_VAR) + # To enable users to specify that they want *a* sparse linear algebra backend + # without having to specify explicitly which one, for each sparse library we + # add the 'meta-module': SparseLinearAlgebraLibrary in addition to their own + # module name. + add_to_output_if_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_USE_EIGEN_SPARSE "EigenSparse;SparseLinearAlgebraLibrary") + add_to_output_if_not_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_NO_LAPACK "LAPACK") + add_to_output_if_not_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_NO_SUITESPARSE "SuiteSparse;SparseLinearAlgebraLibrary") + add_to_output_if_not_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_NO_CXSPARSE "CXSparse;SparseLinearAlgebraLibrary") + add_to_output_if_not_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_RESTRICT_SCHUR_SPECIALIZATION "SchurSpecializations") + add_to_output_if_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_USE_CXX11 "C++11") + add_to_output_if_found(CURRENT_CERES_COMPILE_OPTIONS ${CERES_COMPONENTS_VAR} + CERES_USE_OPENMP "OpenMP") + # Remove duplicates of SparseLinearAlgebraLibrary if multiple sparse backends + # are present. + list(REMOVE_DUPLICATES ${CERES_COMPONENTS_VAR}) + set(${CERES_COMPONENTS_VAR} "${${CERES_COMPONENTS_VAR}}" PARENT_SCOPE) +endfunction() diff --git a/cmake/CeresConfig.cmake.in b/cmake/CeresConfig.cmake.in new file mode 100644 index 0000000..fa0697a --- /dev/null +++ b/cmake/CeresConfig.cmake.in @@ -0,0 +1,407 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Authors: pablo.speciale@gmail.com (Pablo Speciale) +# alexs.mac@gmail.com (Alex Stewart) +# + +# Config file for Ceres Solver - Find Ceres & dependencies. +# +# This file is used by CMake when find_package(Ceres) is invoked and either +# the directory containing this file either is present in CMAKE_MODULE_PATH +# (if Ceres was installed), or exists in the local CMake package registry if +# the Ceres build directory was exported. +# +# This module defines the following variables: +# +# Ceres_FOUND / CERES_FOUND: True if Ceres has been successfully +# found. Both variables are set as although +# FindPackage() only references Ceres_FOUND +# in Config mode, given the conventions for +# _FOUND when FindPackage() is +# called in Module mode, users could +# reasonably expect to use CERES_FOUND +# instead. +# +# CERES_VERSION: Version of Ceres found. +# +# CERES_INCLUDE_DIRS: Include directories for Ceres and the +# dependencies which appear in the Ceres public +# API and are thus required to use Ceres. +# +# CERES_LIBRARIES: Libraries for Ceres and all +# dependencies against which Ceres was +# compiled. This will not include any optional +# dependencies that were disabled when Ceres was +# compiled. +# +# The following variables are also defined for legacy compatibility +# only. Any new code should not use them as they do not conform to +# the standard CMake FindPackage naming conventions. +# +# CERES_INCLUDES = ${CERES_INCLUDE_DIRS}. + +# Called if we failed to find Ceres or any of its required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(CERES_REPORT_NOT_FOUND REASON_MSG) + # FindPackage() only references Ceres_FOUND, and requires it to be + # explicitly set FALSE to denote not found (not merely undefined). + set(Ceres_FOUND FALSE) + set(CERES_FOUND FALSE) + unset(CERES_INCLUDE_DIRS) + unset(CERES_LIBRARIES) + + # Reset the CMake module path to its state when this script was called. + set(CMAKE_MODULE_PATH ${CALLERS_CMAKE_MODULE_PATH}) + + # Note _FIND_[REQUIRED/QUIETLY] variables defined by + # FindPackage() use the camelcase library name, not uppercase. + if (Ceres_FIND_QUIETLY) + message(STATUS "Failed to find Ceres - " ${REASON_MSG} ${ARGN}) + elseif (Ceres_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find Ceres - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use SEND_ERROR which emits an error + # that prevents generation, but continues configuration. + message(SEND_ERROR "Failed to find Ceres - " ${REASON_MSG} ${ARGN}) + endif () + return() +endmacro(CERES_REPORT_NOT_FOUND) + +# ceres_pretty_print_cmake_list( OUTPUT_VAR [item1 [item2 ... ]] ) +# +# Sets ${OUTPUT_VAR} in the caller's scope to a human-readable string +# representation of the list passed as the remaining arguments formed +# as: "[item1, item2, ..., itemN]". +function(ceres_pretty_print_cmake_list OUTPUT_VAR) + string(REPLACE ";" ", " PRETTY_LIST_STRING "[${ARGN}]") + set(${OUTPUT_VAR} "${PRETTY_LIST_STRING}" PARENT_SCOPE) +endfunction() + +# The list of (optional) components this version of Ceres was compiled with. +set(CERES_COMPILED_COMPONENTS "@CERES_COMPILED_COMPONENTS@") + +# If Ceres was not installed, then by definition it was exported +# from a build directory. +set(CERES_WAS_INSTALLED @SETUP_CERES_CONFIG_FOR_INSTALLATION@) + +# Record the state of the CMake module path when this script was +# called so that we can ensure that we leave it in the same state on +# exit as it was on entry, but modify it locally. +set(CALLERS_CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH}) + +# Get the (current, i.e. installed) directory containing this file. +get_filename_component(CERES_CURRENT_CONFIG_DIR + "${CMAKE_CURRENT_LIST_FILE}" PATH) + +if (CERES_WAS_INSTALLED) + # Reset CMake module path to the installation directory of this + # script, thus we will use the FindPackage() scripts shipped with + # Ceres to find Ceres' dependencies, even if the user has equivalently + # named FindPackage() scripts in their project. + set(CMAKE_MODULE_PATH ${CERES_CURRENT_CONFIG_DIR}) + + # Build the absolute root install directory as a relative path + # (determined when Ceres was configured & built) from the current + # install directory for this this file. This allows for the install + # tree to be relocated, after Ceres was built, outside of CMake. + get_filename_component(CURRENT_ROOT_INSTALL_DIR + ${CERES_CURRENT_CONFIG_DIR}/@INSTALL_ROOT_REL_CONFIG_INSTALL_DIR@ + ABSOLUTE) + if (NOT EXISTS ${CURRENT_ROOT_INSTALL_DIR}) + ceres_report_not_found( + "Ceres install root: ${CURRENT_ROOT_INSTALL_DIR}, " + "determined from relative path from CeresConfig.cmake install location: " + "${CERES_CURRENT_CONFIG_DIR}, does not exist. Either the install " + "directory was deleted, or the install tree was only partially relocated " + "outside of CMake after Ceres was built.") + endif (NOT EXISTS ${CURRENT_ROOT_INSTALL_DIR}) + + # Set the include directories for Ceres (itself). + set(CERES_INCLUDE_DIR "${CURRENT_ROOT_INSTALL_DIR}/include") + if (NOT EXISTS ${CERES_INCLUDE_DIR}/ceres/ceres.h) + ceres_report_not_found( + "Ceres install root: ${CURRENT_ROOT_INSTALL_DIR}, " + "determined from relative path from CeresConfig.cmake install location: " + "${CERES_CURRENT_CONFIG_DIR}, does not contain Ceres headers. " + "Either the install directory was deleted, or the install tree was only " + "partially relocated outside of CMake after Ceres was built.") + endif (NOT EXISTS ${CERES_INCLUDE_DIR}/ceres/ceres.h) + list(APPEND CERES_INCLUDE_DIRS ${CERES_INCLUDE_DIR}) + +else(CERES_WAS_INSTALLED) + # Ceres was exported from the build tree. + set(CERES_EXPORTED_BUILD_DIR ${CERES_CURRENT_CONFIG_DIR}) + get_filename_component(CERES_EXPORTED_SOURCE_DIR + ${CERES_EXPORTED_BUILD_DIR}/@INSTALL_ROOT_REL_CONFIG_INSTALL_DIR@ + ABSOLUTE) + if (NOT EXISTS ${CERES_EXPORTED_SOURCE_DIR}) + ceres_report_not_found( + "Ceres exported source directory: ${CERES_EXPORTED_SOURCE_DIR}, " + "determined from relative path from CeresConfig.cmake exported build " + "directory: ${CERES_EXPORTED_BUILD_DIR} does not exist.") + endif() + + # Reset CMake module path to the cmake directory in the Ceres source + # tree which was exported, thus we will use the FindPackage() scripts shipped + # with Ceres to find Ceres' dependencies, even if the user has equivalently + # named FindPackage() scripts in their project. + set(CMAKE_MODULE_PATH ${CERES_EXPORTED_SOURCE_DIR}/cmake) + + # Set the include directories for Ceres (itself). + set(CERES_INCLUDE_DIR "${CERES_EXPORTED_SOURCE_DIR}/include") + if (NOT EXISTS ${CERES_INCLUDE_DIR}/ceres/ceres.h) + ceres_report_not_found( + "Ceres exported source directory: ${CERES_EXPORTED_SOURCE_DIR}, " + "determined from relative path from CeresConfig.cmake exported build " + "directory: ${CERES_EXPORTED_BUILD_DIR}, does not contain Ceres headers.") + endif (NOT EXISTS ${CERES_INCLUDE_DIR}/ceres/ceres.h) + list(APPEND CERES_INCLUDE_DIRS ${CERES_INCLUDE_DIR}) + + # Append the path to the configured config.h in the exported build directory + # to the Ceres include directories. + set(CERES_CONFIG_FILE + ${CERES_EXPORTED_BUILD_DIR}/config/ceres/internal/config.h) + if (NOT EXISTS ${CERES_CONFIG_FILE}) + ceres_report_not_found( + "Ceres exported build directory: ${CERES_EXPORTED_BUILD_DIR}, " + "does not contain required configured Ceres config.h, it is not here: " + "${CERES_CONFIG_FILE}.") + endif (NOT EXISTS ${CERES_CONFIG_FILE}) + list(APPEND CERES_INCLUDE_DIRS ${CERES_EXPORTED_BUILD_DIR}/config) +endif(CERES_WAS_INSTALLED) + +# Set the version. +set(CERES_VERSION @CERES_VERSION@ ) + +# Eigen. +# Flag set during configuration and build of Ceres. +set(CERES_EIGEN_VERSION @EIGEN_VERSION@) +set(EIGEN_WAS_BUILT_WITH_CMAKE @FOUND_INSTALLED_EIGEN_CMAKE_CONFIGURATION@) +# Append the locations of Eigen when Ceres was built to the search path hints. +if (EIGEN_WAS_BUILT_WITH_CMAKE) + set(Eigen3_DIR @Eigen3_DIR@) + set(EIGEN_PREFER_EXPORTED_EIGEN_CMAKE_CONFIGURATION TRUE) +else() + list(APPEND EIGEN_INCLUDE_DIR_HINTS @EIGEN_INCLUDE_DIR@) +endif() +# Search quietly to control the timing of the error message if not found. The +# search should be for an exact match, but for usability reasons do a soft +# match and reject with an explanation below. +find_package(Eigen ${CERES_EIGEN_VERSION} QUIET) +if (EIGEN_FOUND) + if (NOT EIGEN_VERSION VERSION_EQUAL CERES_EIGEN_VERSION) + # CMake's VERSION check in FIND_PACKAGE() will accept any version >= the + # specified version. However, only version = is supported. Improve + # usability by explaining why we don't accept non-exact version matching. + ceres_report_not_found("Found Eigen dependency, but the version of Eigen " + "found (${EIGEN_VERSION}) does not exactly match the version of Eigen " + "Ceres was compiled with (${CERES_EIGEN_VERSION}). This can cause subtle " + "bugs by triggering violations of the One Definition Rule. See the " + "Wikipedia article http://en.wikipedia.org/wiki/One_Definition_Rule " + "for more details") + endif () + message(STATUS "Found required Ceres dependency: " + "Eigen version ${CERES_EIGEN_VERSION} in ${EIGEN_INCLUDE_DIRS}") +else (EIGEN_FOUND) + ceres_report_not_found("Missing required Ceres " + "dependency: Eigen version ${CERES_EIGEN_VERSION}, please set " + "EIGEN_INCLUDE_DIR.") +endif (EIGEN_FOUND) +list(APPEND CERES_INCLUDE_DIRS ${EIGEN_INCLUDE_DIRS}) + +# Glog. +# Flag set during configuration and build of Ceres. +set(CERES_USES_MINIGLOG @MINIGLOG@) +set(CERES_USES_GFLAGS @GFLAGS@) +if (CERES_USES_MINIGLOG) + set(MINIGLOG_INCLUDE_DIR ${CERES_INCLUDE_DIR}/ceres/internal/miniglog) + if (NOT CERES_WAS_INSTALLED) + # When Ceres was exported from the build tree, the miniglog headers + # will be in Ceres internal source directory, not in the public headers + # directory (they are copied with the public headers when installed). + set(MINIGLOG_INCLUDE_DIR + ${CERES_EXPORTED_SOURCE_DIR}/internal/ceres/miniglog) + endif() + if (NOT EXISTS ${MINIGLOG_INCLUDE_DIR}) + ceres_report_not_found( + "Failed to find miniglog headers in expected include directory: " + "${MINIGLOG_INCLUDE_DIR}, but Ceres was compiled with MINIGLOG enabled " + "(in place of glog).") + endif (NOT EXISTS ${MINIGLOG_INCLUDE_DIR}) + list(APPEND CERES_INCLUDE_DIRS ${MINIGLOG_INCLUDE_DIR}) + # Output message at standard log level (not the lower STATUS) so that + # the message is output in GUI during configuration to warn user. + message("-- Found Ceres compiled with miniglog substitute " + "for glog, beware this will likely cause problems if glog is later linked.") +else (CERES_USES_MINIGLOG) + # Append the locations of glog when Ceres was built to the search path hints. + set(GLOG_WAS_BUILT_WITH_CMAKE @FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION@) + if (GLOG_WAS_BUILT_WITH_CMAKE) + set(glog_DIR @glog_DIR@) + set(GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION TRUE) + else() + list(APPEND GLOG_INCLUDE_DIR_HINTS @GLOG_INCLUDE_DIR@) + get_filename_component(CERES_BUILD_GLOG_LIBRARY_DIR @GLOG_LIBRARY@ PATH) + list(APPEND GLOG_LIBRARY_DIR_HINTS ${CERES_BUILD_GLOG_LIBRARY_DIR}) + endif() + + # Search quietly s/t we control the timing of the error message if not found. + find_package(Glog QUIET) + if (GLOG_FOUND) + message(STATUS "Found required Ceres dependency: glog") + else (GLOG_FOUND) + ceres_report_not_found("Missing required Ceres " + "dependency: glog. Searched using GLOG_INCLUDE_DIR_HINTS: " + "${GLOG_INCLUDE_DIR_HINTS} and glog_DIR: ${glog_DIR}.") + endif (GLOG_FOUND) + list(APPEND CERES_INCLUDE_DIRS ${GLOG_INCLUDE_DIRS}) + + # gflags is only a public dependency of Ceres via glog, thus is not required + # if Ceres was built with MINIGLOG. + if (CERES_USES_GFLAGS) + # If gflags was found as an imported CMake target, we need to call + # find_packge(Gflags) again here, as imported CMake targets are not + # re-exported. Without this, the 'gflags-shared' target name which is + # present in CERES_LIBRARIES in this case would not be defined, and so + # CMake will assume it is a library name (which it is not) and fail to link. + # + # Append the locations of gflags when Ceres was built to the search path + # hints. + set(GFLAGS_WAS_BUILT_WITH_CMAKE @FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION@) + if (GFLAGS_WAS_BUILT_WITH_CMAKE) + set(gflags_DIR @gflags_DIR@) + set(GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION TRUE) + else() + list(APPEND GFLAGS_INCLUDE_DIR_HINTS @GFLAGS_INCLUDE_DIR@) + get_filename_component(CERES_BUILD_GFLAGS_LIBRARY_DIR @GFLAGS_LIBRARY@ PATH) + list(APPEND GFLAGS_LIBRARY_DIR_HINTS ${CERES_BUILD_GFLAGS_LIBRARY_DIR}) + endif() + + # Search quietly s/t we control the timing of the error message if not found. + find_package(Gflags QUIET) + if (GFLAGS_FOUND) + message(STATUS "Found required Ceres dependency: gflags") + else() + ceres_report_not_found("Missing required Ceres " + "dependency: gflags. Searched using GFLAGS_INCLUDE_DIR_HINTS: " + "${GFLAGS_INCLUDE_DIR_HINTS} and gflags_DIR: ${gflags_DIR}.") + endif() + list(APPEND CERES_INCLUDE_DIRS ${GFLAGS_INCLUDE_DIR_HINTS}) + endif() +endif (CERES_USES_MINIGLOG) + +# Import exported Ceres targets, if they have not already been imported. +if (NOT TARGET ceres AND NOT Ceres_BINARY_DIR) + include(${CERES_CURRENT_CONFIG_DIR}/CeresTargets.cmake) +endif (NOT TARGET ceres AND NOT Ceres_BINARY_DIR) +# Set the expected XX_LIBRARIES variable for FindPackage(). +set(CERES_LIBRARIES ceres) + +# Make user aware of any compile flags that will be added to their targets +# which use Ceres (i.e. flags exported in the Ceres target). Only CMake +# versions >= 2.8.12 support target_compile_options(). +if (TARGET ${CERES_LIBRARIES} AND + NOT CMAKE_VERSION VERSION_LESS "2.8.12") + get_target_property(CERES_INTERFACE_COMPILE_OPTIONS + ${CERES_LIBRARIES} INTERFACE_COMPILE_OPTIONS) + + if (CERES_WAS_INSTALLED) + set(CERES_LOCATION "${CURRENT_ROOT_INSTALL_DIR}") + else() + set(CERES_LOCATION "${CERES_EXPORTED_BUILD_DIR}") + endif() + + # Check for -std=c++11 flags. + if (CERES_INTERFACE_COMPILE_OPTIONS MATCHES ".*std=c\\+\\+11.*") + message(STATUS "Ceres version ${CERES_VERSION} detected here: " + "${CERES_LOCATION} was built with C++11. Ceres target will add " + "C++11 flags to compile options for targets using it.") + endif() +endif() + +# Set legacy include directories variable for backwards compatibility. +set(CERES_INCLUDES ${CERES_INCLUDE_DIRS}) + +# Reset CMake module path to its state when this script was called. +set(CMAKE_MODULE_PATH ${CALLERS_CMAKE_MODULE_PATH}) + +# Build the detected Ceres version string to correctly capture whether it +# was installed, or exported. +ceres_pretty_print_cmake_list(CERES_COMPILED_COMPONENTS_STRING + ${CERES_COMPILED_COMPONENTS}) +if (CERES_WAS_INSTALLED) + set(CERES_DETECTED_VERSION_STRING "Ceres version: ${CERES_VERSION} " + "installed in: ${CURRENT_ROOT_INSTALL_DIR} with components: " + "${CERES_COMPILED_COMPONENTS_STRING}") +else (CERES_WAS_INSTALLED) + set(CERES_DETECTED_VERSION_STRING "Ceres version: ${CERES_VERSION} " + "exported from build directory: ${CERES_EXPORTED_BUILD_DIR} with " + "components: ${CERES_COMPILED_COMPONENTS_STRING}") +endif() + +# If the user called this script through find_package() whilst specifying +# particular Ceres components that should be found via: +# find_package(Ceres COMPONENTS XXX YYY), check the requested components against +# those with which Ceres was compiled. In this case, we should only report +# Ceres as found if all the requested components have been found. +if (Ceres_FIND_COMPONENTS) + foreach (REQUESTED_COMPONENT ${Ceres_FIND_COMPONENTS}) + list(FIND CERES_COMPILED_COMPONENTS ${REQUESTED_COMPONENT} HAVE_REQUESTED_COMPONENT) + # list(FIND ..) returns -1 if the element was not in the list, but CMake + # interprets if (VAR) to be true if VAR is any non-zero number, even + # negative ones, hence we have to explicitly check for >= 0. + if (HAVE_REQUESTED_COMPONENT EQUAL -1) + # Check for the presence of all requested components before reporting + # not found, such that we report all of the missing components rather + # than just the first. + list(APPEND MISSING_CERES_COMPONENTS ${REQUESTED_COMPONENT}) + endif() + endforeach() + if (MISSING_CERES_COMPONENTS) + ceres_pretty_print_cmake_list(REQUESTED_CERES_COMPONENTS_STRING + ${Ceres_FIND_COMPONENTS}) + ceres_pretty_print_cmake_list(MISSING_CERES_COMPONENTS_STRING + ${MISSING_CERES_COMPONENTS}) + ceres_report_not_found("Missing requested Ceres components: " + "${MISSING_CERES_COMPONENTS_STRING} (components requested: " + "${REQUESTED_CERES_COMPONENTS_STRING}). Detected " + "${CERES_DETECTED_VERSION_STRING}.") + endif() +endif() + +# As we use CERES_REPORT_NOT_FOUND() to abort, if we reach this point we have +# found Ceres and all required dependencies. +message(STATUS "Found " ${CERES_DETECTED_VERSION_STRING}) + +# Set CERES_FOUND to be equivalent to Ceres_FOUND, which is set to +# TRUE by FindPackage() if this file is found and run, and after which +# Ceres_FOUND is not (explicitly, i.e. undefined does not count) set +# to FALSE. +set(CERES_FOUND TRUE) diff --git a/cmake/CeresConfigVersion.cmake.in b/cmake/CeresConfigVersion.cmake.in new file mode 100644 index 0000000..5ff36eb --- /dev/null +++ b/cmake/CeresConfigVersion.cmake.in @@ -0,0 +1,50 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: pablo.speciale@gmail.com (Pablo Speciale) +# +# FIND_PACKAGE() searches for a Config.cmake file and an associated +# Version.cmake file, which it loads to check the version number. +# +# This file can be used with CONFIGURE_FILE() to generate such a file for a +# project with very basic logic. +# +# It sets PACKAGE_VERSION_EXACT if the current version string and the requested +# version string are exactly the same and it sets PACKAGE_VERSION_COMPATIBLE +# if the current version is >= requested version. + +set(PACKAGE_VERSION @CERES_VERSION@) + +if ("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_COMPATIBLE FALSE) +else ("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") + set(PACKAGE_VERSION_COMPATIBLE TRUE) + if ("${PACKAGE_FIND_VERSION}" STREQUAL "${PACKAGE_VERSION}") + set(PACKAGE_VERSION_EXACT TRUE) + endif ("${PACKAGE_FIND_VERSION}" STREQUAL "${PACKAGE_VERSION}") +endif ("${PACKAGE_VERSION}" VERSION_LESS "${PACKAGE_FIND_VERSION}") diff --git a/cmake/CheckIfUnderscorePrefixedBesselFunctionsExist.cmake b/cmake/CheckIfUnderscorePrefixedBesselFunctionsExist.cmake new file mode 100644 index 0000000..a05721c --- /dev/null +++ b/cmake/CheckIfUnderscorePrefixedBesselFunctionsExist.cmake @@ -0,0 +1,54 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2017 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) + +# Microsoft deprecated the POSIX Bessel functions: j[0,1,n]() in favour +# of _j[0,1,n](), it appears since at least MSVC 2005 [1]. This function +# checks if the underscore prefixed versions of the Bessel functions are +# defined, and sets ${HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS_VAR} to +# TRUE if they do. +# +# [1] https://msdn.microsoft.com/en-us/library/ms235384(v=vs.100).aspx +function(check_if_underscore_prefixed_bessel_functions_exist + HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS_VAR) + include(CheckCXXSourceCompiles) + check_cxx_source_compiles( + "#include + int main(int argc, char * argv[]) { + double result; + result = _j0(1.2345); + result = _j1(1.2345); + result = _jn(2, 1.2345); + return 0; + }" + HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + set(${HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS_VAR} + ${HAVE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS} + PARENT_SCOPE) +endfunction() diff --git a/cmake/CreateCeresConfig.cmake b/cmake/CreateCeresConfig.cmake new file mode 100644 index 0000000..89db68c --- /dev/null +++ b/cmake/CreateCeresConfig.cmake @@ -0,0 +1,115 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) + +# This must take place outside of CONFIGURE_CERES_CONFIG() in order that +# we can determine where *this* file is, and thus the relative path to +# config.h.in. Inside of CONFIGURE_CERES_CONFIG(), CMAKE_CURRENT_LIST_DIR +# refers to the caller of CONFIGURE_CERES_CONFIG(), not this file. +set(CERES_CONFIG_IN_FILE "${CMAKE_CURRENT_LIST_DIR}/config.h.in") + +# CreateCeresConfig.cmake - Create the config.h for Ceres. +# +# This function configures the Ceres config.h file based on the current +# compile options and copies it into the specified location. It should be +# called before Ceres is built so that the correct config.h is used when +# Ceres is compiled. +# +# INPUTS: +# CURRENT_CERES_COMPILE_OPTIONS: List of currently enabled Ceres compile +# options. These are compared against the +# full list of valid options, which are read +# from config.h.in. Any options present +# which are not part of the valid set will +# invoke an error. Any valid option present +# will be enabled in the resulting config.h, +# all other options will be disabled. +# +# CERES_CONFIG_OUTPUT_DIRECTORY: Path to output directory in which to save +# the configured config.h. Typically this +# will be /include/ceres/internal. + +function(CREATE_CERES_CONFIG CURRENT_CERES_COMPILE_OPTIONS CERES_CONFIG_OUTPUT_DIRECTORY) + # Create the specified output directory if it does not exist. + if (NOT EXISTS "${CERES_CONFIG_OUTPUT_DIRECTORY}") + message(STATUS "Creating configured Ceres config.h output directory: " + "${CERES_CONFIG_OUTPUT_DIRECTORY}") + file(MAKE_DIRECTORY "${CERES_CONFIG_OUTPUT_DIRECTORY}") + endif() + if (EXISTS "${CERES_CONFIG_OUTPUT_DIRECTORY}" AND + NOT IS_DIRECTORY "${CERES_CONFIG_OUTPUT_DIRECTORY}") + message(FATAL_ERROR "Ceres Bug: Specified CERES_CONFIG_OUTPUT_DIRECTORY: " + "${CERES_CONFIG_OUTPUT_DIRECTORY} exists, but is not a directory.") + endif() + + # Read all possible configurable compile options from config.h.in, this avoids + # us having to hard-code in this file what the valid options are. + file(READ ${CERES_CONFIG_IN_FILE} CERES_CONFIG_IN_CONTENTS) + string(REGEX MATCHALL "@[^@ $]+@" + ALL_CONFIGURABLE_CERES_OPTIONS "${CERES_CONFIG_IN_CONTENTS}") + # Removing @ symbols at beginning and end of each option. + string(REPLACE "@" "" + ALL_CONFIGURABLE_CERES_OPTIONS "${ALL_CONFIGURABLE_CERES_OPTIONS}") + + # Ensure that there are no repetitions in the current compile options. + list(REMOVE_DUPLICATES CURRENT_CERES_COMPILE_OPTIONS) + + foreach (CERES_OPTION ${ALL_CONFIGURABLE_CERES_OPTIONS}) + # Try and find the option in the list of current compile options, if it + # is present, then the option is enabled, otherwise it is disabled. + list(FIND CURRENT_CERES_COMPILE_OPTIONS ${CERES_OPTION} OPTION_ENABLED) + + # list(FIND ..) returns -1 if the element was not in the list, but CMake + # interprets if (VAR) to be true if VAR is any non-zero number, even + # negative ones, hence we have to explicitly check for >= 0. + if (OPTION_ENABLED GREATER -1) + message(STATUS "Enabling ${CERES_OPTION} in Ceres config.h") + set(${CERES_OPTION} "#define ${CERES_OPTION}") + + # Remove the item from the list of current options so that we can identify + # any options that were in CURRENT_CERES_COMPILE_OPTIONS, but not in + # ALL_CONFIGURABLE_CERES_OPTIONS (which is an error). + list(REMOVE_ITEM CURRENT_CERES_COMPILE_OPTIONS ${CERES_OPTION}) + else() + set(${CERES_OPTION} "// #define ${CERES_OPTION}") + endif() + endforeach() + + # CURRENT_CERES_COMPILE_OPTIONS should now be an empty list, any elements + # remaining were not present in ALL_CONFIGURABLE_CERES_OPTIONS read from + # config.h.in. + if (CURRENT_CERES_COMPILE_OPTIONS) + message(FATAL_ERROR "Ceres Bug: CURRENT_CERES_COMPILE_OPTIONS contained " + "the following options which were not present in config.h.in: " + "${CURRENT_CERES_COMPILE_OPTIONS}") + endif() + + configure_file(${CERES_CONFIG_IN_FILE} + "${CERES_CONFIG_OUTPUT_DIRECTORY}/config.h" @ONLY) +endfunction() diff --git a/cmake/FindCXSparse.cmake b/cmake/FindCXSparse.cmake new file mode 100644 index 0000000..3f4b015 --- /dev/null +++ b/cmake/FindCXSparse.cmake @@ -0,0 +1,240 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindCXSparse.cmake - Find CXSparse libraries & dependencies. +# +# This module defines the following variables which should be referenced +# by the caller to use the library. +# +# CXSPARSE_FOUND: TRUE iff CXSparse and all dependencies have been found. +# CXSPARSE_INCLUDE_DIRS: Include directories for CXSparse. +# CXSPARSE_LIBRARIES: Libraries for CXSparse and all dependencies. +# +# CXSPARSE_VERSION: Extracted from cs.h. +# CXSPARSE_MAIN_VERSION: Equal to 3 if CXSPARSE_VERSION = 3.1.2 +# CXSPARSE_SUB_VERSION: Equal to 1 if CXSPARSE_VERSION = 3.1.2 +# CXSPARSE_SUBSUB_VERSION: Equal to 2 if CXSPARSE_VERSION = 3.1.2 +# +# The following variables control the behaviour of this module: +# +# CXSPARSE_INCLUDE_DIR_HINTS: List of additional directories in which to +# search for CXSparse includes, +# e.g: /timbuktu/include. +# CXSPARSE_LIBRARY_DIR_HINTS: List of additional directories in which to +# search for CXSparse libraries, e.g: /timbuktu/lib. +# +# The following variables are also defined by this module, but in line with +# CMake recommended FindPackage() module style should NOT be referenced directly +# by callers (use the plural variables detailed above instead). These variables +# do however affect the behaviour of the module via FIND_[PATH/LIBRARY]() which +# are NOT re-called (i.e. search for library is not repeated) if these variables +# are set with valid values _in the CMake cache_. This means that if these +# variables are set directly in the cache, either by the user in the CMake GUI, +# or by the user passing -DVAR=VALUE directives to CMake when called (which +# explicitly defines a cache variable), then they will be used verbatim, +# bypassing the HINTS variables and other hard-coded search locations. +# +# CXSPARSE_INCLUDE_DIR: Include directory for CXSparse, not including the +# include directory of any dependencies. +# CXSPARSE_LIBRARY: CXSparse library, not including the libraries of any +# dependencies. + +# Reset CALLERS_CMAKE_FIND_LIBRARY_PREFIXES to its value when +# FindCXSparse was invoked. +macro(CXSPARSE_RESET_FIND_LIBRARY_PREFIX) + if (MSVC) + set(CMAKE_FIND_LIBRARY_PREFIXES "${CALLERS_CMAKE_FIND_LIBRARY_PREFIXES}") + endif (MSVC) +endmacro(CXSPARSE_RESET_FIND_LIBRARY_PREFIX) + +# Called if we failed to find CXSparse or any of it's required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(CXSPARSE_REPORT_NOT_FOUND REASON_MSG) + unset(CXSPARSE_FOUND) + unset(CXSPARSE_INCLUDE_DIRS) + unset(CXSPARSE_LIBRARIES) + # Make results of search visible in the CMake GUI if CXSparse has not + # been found so that user does not have to toggle to advanced view. + mark_as_advanced(CLEAR CXSPARSE_INCLUDE_DIR + CXSPARSE_LIBRARY) + + cxsparse_reset_find_library_prefix() + + # Note _FIND_[REQUIRED/QUIETLY] variables defined by FindPackage() + # use the camelcase library name, not uppercase. + if (CXSparse_FIND_QUIETLY) + message(STATUS "Failed to find CXSparse - " ${REASON_MSG} ${ARGN}) + elseif (CXSparse_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find CXSparse - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use no priority which emits a message + # but continues configuration and allows generation. + message("-- Failed to find CXSparse - " ${REASON_MSG} ${ARGN}) + endif () + return() +endmacro(CXSPARSE_REPORT_NOT_FOUND) + +# Protect against any alternative find_package scripts for this library having +# been called previously (in a client project) which set CXSPARSE_FOUND, but not +# the other variables we require / set here which could cause the search logic +# here to fail. +unset(CXSPARSE_FOUND) + +# Handle possible presence of lib prefix for libraries on MSVC, see +# also CXSPARSE_RESET_FIND_LIBRARY_PREFIX(). +if (MSVC) + # Preserve the caller's original values for CMAKE_FIND_LIBRARY_PREFIXES + # s/t we can set it back before returning. + set(CALLERS_CMAKE_FIND_LIBRARY_PREFIXES "${CMAKE_FIND_LIBRARY_PREFIXES}") + # The empty string in this list is important, it represents the case when + # the libraries have no prefix (shared libraries / DLLs). + set(CMAKE_FIND_LIBRARY_PREFIXES "lib" "" "${CMAKE_FIND_LIBRARY_PREFIXES}") +endif (MSVC) + +# Search user-installed locations first, so that we prefer user installs +# to system installs where both exist. +# +# TODO: Add standard Windows search locations for CXSparse. +list(APPEND CXSPARSE_CHECK_INCLUDE_DIRS + /usr/local/include + /usr/local/homebrew/include # Mac OS X + /opt/local/var/macports/software # Mac OS X. + /opt/local/include + /usr/include) +list(APPEND CXSPARSE_CHECK_LIBRARY_DIRS + /usr/local/lib + /usr/local/homebrew/lib # Mac OS X. + /opt/local/lib + /usr/lib) +# Additional suffixes to try appending to each search path. +list(APPEND CXSPARSE_CHECK_PATH_SUFFIXES + suitesparse) # Linux/Windows + +# Search supplied hint directories first if supplied. +find_path(CXSPARSE_INCLUDE_DIR + NAMES cs.h + HINTS ${CXSPARSE_INCLUDE_DIR_HINTS} + PATHS ${CXSPARSE_CHECK_INCLUDE_DIRS} + PATH_SUFFIXES ${CXSPARSE_CHECK_PATH_SUFFIXES}) +if (NOT CXSPARSE_INCLUDE_DIR OR + NOT EXISTS ${CXSPARSE_INCLUDE_DIR}) + cxsparse_report_not_found( + "Could not find CXSparse include directory, set CXSPARSE_INCLUDE_DIR " + "to directory containing cs.h") +endif (NOT CXSPARSE_INCLUDE_DIR OR + NOT EXISTS ${CXSPARSE_INCLUDE_DIR}) + +find_library(CXSPARSE_LIBRARY NAMES cxsparse + HINTS ${CXSPARSE_LIBRARY_DIR_HINTS} + PATHS ${CXSPARSE_CHECK_LIBRARY_DIRS} + PATH_SUFFIXES ${CXSPARSE_CHECK_PATH_SUFFIXES}) +if (NOT CXSPARSE_LIBRARY OR + NOT EXISTS ${CXSPARSE_LIBRARY}) + cxsparse_report_not_found( + "Could not find CXSparse library, set CXSPARSE_LIBRARY " + "to full path to libcxsparse.") +endif (NOT CXSPARSE_LIBRARY OR + NOT EXISTS ${CXSPARSE_LIBRARY}) + +# Mark internally as found, then verify. CXSPARSE_REPORT_NOT_FOUND() unsets +# if called. +set(CXSPARSE_FOUND TRUE) + +# Extract CXSparse version from cs.h +if (CXSPARSE_INCLUDE_DIR) + set(CXSPARSE_VERSION_FILE ${CXSPARSE_INCLUDE_DIR}/cs.h) + if (NOT EXISTS ${CXSPARSE_VERSION_FILE}) + cxsparse_report_not_found( + "Could not find file: ${CXSPARSE_VERSION_FILE} " + "containing version information in CXSparse install located at: " + "${CXSPARSE_INCLUDE_DIR}.") + else (NOT EXISTS ${CXSPARSE_VERSION_FILE}) + file(READ ${CXSPARSE_INCLUDE_DIR}/cs.h CXSPARSE_VERSION_FILE_CONTENTS) + + string(REGEX MATCH "#define CS_VER [0-9]+" + CXSPARSE_MAIN_VERSION "${CXSPARSE_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CS_VER ([0-9]+)" "\\1" + CXSPARSE_MAIN_VERSION "${CXSPARSE_MAIN_VERSION}") + + string(REGEX MATCH "#define CS_SUBVER [0-9]+" + CXSPARSE_SUB_VERSION "${CXSPARSE_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CS_SUBVER ([0-9]+)" "\\1" + CXSPARSE_SUB_VERSION "${CXSPARSE_SUB_VERSION}") + + string(REGEX MATCH "#define CS_SUBSUB [0-9]+" + CXSPARSE_SUBSUB_VERSION "${CXSPARSE_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CS_SUBSUB ([0-9]+)" "\\1" + CXSPARSE_SUBSUB_VERSION "${CXSPARSE_SUBSUB_VERSION}") + + # This is on a single line s/t CMake does not interpret it as a list of + # elements and insert ';' separators which would result in 3.;1.;2 nonsense. + set(CXSPARSE_VERSION "${CXSPARSE_MAIN_VERSION}.${CXSPARSE_SUB_VERSION}.${CXSPARSE_SUBSUB_VERSION}") + endif (NOT EXISTS ${CXSPARSE_VERSION_FILE}) +endif (CXSPARSE_INCLUDE_DIR) + +# Catch the case when the caller has set CXSPARSE_LIBRARY in the cache / GUI and +# thus FIND_LIBRARY was not called, but specified library is invalid, otherwise +# we would report CXSparse as found. +# TODO: This regex for CXSparse library is pretty primitive, we use lowercase +# for comparison to handle Windows using CamelCase library names, could +# this check be better? +string(TOLOWER "${CXSPARSE_LIBRARY}" LOWERCASE_CXSPARSE_LIBRARY) +if (CXSPARSE_LIBRARY AND + EXISTS ${CXSPARSE_LIBRARY} AND + NOT "${LOWERCASE_CXSPARSE_LIBRARY}" MATCHES ".*cxsparse[^/]*") + cxsparse_report_not_found( + "Caller defined CXSPARSE_LIBRARY: " + "${CXSPARSE_LIBRARY} does not match CXSparse.") +endif (CXSPARSE_LIBRARY AND + EXISTS ${CXSPARSE_LIBRARY} AND + NOT "${LOWERCASE_CXSPARSE_LIBRARY}" MATCHES ".*cxsparse[^/]*") + +# Set standard CMake FindPackage variables if found. +if (CXSPARSE_FOUND) + set(CXSPARSE_INCLUDE_DIRS ${CXSPARSE_INCLUDE_DIR}) + set(CXSPARSE_LIBRARIES ${CXSPARSE_LIBRARY}) +endif (CXSPARSE_FOUND) + +cxsparse_reset_find_library_prefix() + +# Handle REQUIRED / QUIET optional arguments and version. +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(CXSparse + REQUIRED_VARS CXSPARSE_INCLUDE_DIRS CXSPARSE_LIBRARIES + VERSION_VAR CXSPARSE_VERSION) + +# Only mark internal variables as advanced if we found CXSparse, otherwise +# leave them visible in the standard GUI for the user to set manually. +if (CXSPARSE_FOUND) + mark_as_advanced(FORCE CXSPARSE_INCLUDE_DIR + CXSPARSE_LIBRARY) +endif (CXSPARSE_FOUND) diff --git a/cmake/FindEigen.cmake b/cmake/FindEigen.cmake new file mode 100644 index 0000000..f6d2664 --- /dev/null +++ b/cmake/FindEigen.cmake @@ -0,0 +1,263 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindEigen.cmake - Find Eigen library, version >= 3. +# +# This module defines the following variables: +# +# EIGEN_FOUND: TRUE iff Eigen is found. +# EIGEN_INCLUDE_DIRS: Include directories for Eigen. +# EIGEN_VERSION: Extracted from Eigen/src/Core/util/Macros.h +# EIGEN_WORLD_VERSION: Equal to 3 if EIGEN_VERSION = 3.2.0 +# EIGEN_MAJOR_VERSION: Equal to 2 if EIGEN_VERSION = 3.2.0 +# EIGEN_MINOR_VERSION: Equal to 0 if EIGEN_VERSION = 3.2.0 +# FOUND_INSTALLED_EIGEN_CMAKE_CONFIGURATION: True iff the version of Eigen +# found was built & installed / +# exported as a CMake package. +# +# The following variables control the behaviour of this module: +# +# EIGEN_PREFER_EXPORTED_EIGEN_CMAKE_CONFIGURATION: TRUE/FALSE, iff TRUE then +# then prefer using an exported CMake configuration +# generated by Eigen over searching for the +# Eigen components manually. Otherwise (FALSE) +# ignore any exported Eigen CMake configurations and +# always perform a manual search for the components. +# Default: TRUE iff user does not define this variable +# before we are called, and does NOT specify +# EIGEN_INCLUDE_DIR_HINTS, otherwise FALSE. +# EIGEN_INCLUDE_DIR_HINTS: List of additional directories in which to +# search for eigen includes, e.g: /timbuktu/eigen3. +# +# The following variables are also defined by this module, but in line with +# CMake recommended FindPackage() module style should NOT be referenced directly +# by callers (use the plural variables detailed above instead). These variables +# do however affect the behaviour of the module via FIND_[PATH/LIBRARY]() which +# are NOT re-called (i.e. search for library is not repeated) if these variables +# are set with valid values _in the CMake cache_. This means that if these +# variables are set directly in the cache, either by the user in the CMake GUI, +# or by the user passing -DVAR=VALUE directives to CMake when called (which +# explicitly defines a cache variable), then they will be used verbatim, +# bypassing the HINTS variables and other hard-coded search locations. +# +# EIGEN_INCLUDE_DIR: Include directory for CXSparse, not including the +# include directory of any dependencies. + +# Called if we failed to find Eigen or any of it's required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(EIGEN_REPORT_NOT_FOUND REASON_MSG) + unset(EIGEN_FOUND) + unset(EIGEN_INCLUDE_DIRS) + unset(FOUND_INSTALLED_EIGEN_CMAKE_CONFIGURATION) + # Make results of search visible in the CMake GUI if Eigen has not + # been found so that user does not have to toggle to advanced view. + mark_as_advanced(CLEAR EIGEN_INCLUDE_DIR) + # Note _FIND_[REQUIRED/QUIETLY] variables defined by FindPackage() + # use the camelcase library name, not uppercase. + if (Eigen_FIND_QUIETLY) + message(STATUS "Failed to find Eigen - " ${REASON_MSG} ${ARGN}) + elseif (Eigen_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find Eigen - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use no priority which emits a message + # but continues configuration and allows generation. + message("-- Failed to find Eigen - " ${REASON_MSG} ${ARGN}) + endif () + return() +endmacro(EIGEN_REPORT_NOT_FOUND) + +# Protect against any alternative find_package scripts for this library having +# been called previously (in a client project) which set EIGEN_FOUND, but not +# the other variables we require / set here which could cause the search logic +# here to fail. +unset(EIGEN_FOUND) + +# ----------------------------------------------------------------- +# By default, if the user has expressed no preference for using an exported +# Eigen CMake configuration over performing a search for the installed +# components, and has not specified any hints for the search locations, then +# prefer an exported configuration if available. +if (NOT DEFINED EIGEN_PREFER_EXPORTED_EIGEN_CMAKE_CONFIGURATION + AND NOT EIGEN_INCLUDE_DIR_HINTS) + message(STATUS "No preference for use of exported Eigen CMake configuration " + "set, and no hints for include directory provided. " + "Defaulting to preferring an installed/exported Eigen CMake configuration " + "if available.") + set(EIGEN_PREFER_EXPORTED_EIGEN_CMAKE_CONFIGURATION TRUE) +endif() + +if (EIGEN_PREFER_EXPORTED_EIGEN_CMAKE_CONFIGURATION) + # Try to find an exported CMake configuration for Eigen. + # + # We search twice, s/t we can invert the ordering of precedence used by + # find_package() for exported package build directories, and installed + # packages (found via CMAKE_SYSTEM_PREFIX_PATH), listed as items 6) and 7) + # respectively in [1]. + # + # By default, exported build directories are (in theory) detected first, and + # this is usually the case on Windows. However, on OS X & Linux, the install + # path (/usr/local) is typically present in the PATH environment variable + # which is checked in item 4) in [1] (i.e. before both of the above, unless + # NO_SYSTEM_ENVIRONMENT_PATH is passed). As such on those OSs installed + # packages are usually detected in preference to exported package build + # directories. + # + # To ensure a more consistent response across all OSs, and as users usually + # want to prefer an installed version of a package over a locally built one + # where both exist (esp. as the exported build directory might be removed + # after installation), we first search with NO_CMAKE_PACKAGE_REGISTRY which + # means any build directories exported by the user are ignored, and thus + # installed directories are preferred. If this fails to find the package + # we then research again, but without NO_CMAKE_PACKAGE_REGISTRY, so any + # exported build directories will now be detected. + # + # To prevent confusion on Windows, we also pass NO_CMAKE_BUILDS_PATH (which + # is item 5) in [1]), to not preferentially use projects that were built + # recently with the CMake GUI to ensure that we always prefer an installed + # version if available. + # + # [1] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:find_package + find_package(Eigen3 QUIET + NO_MODULE + NO_CMAKE_PACKAGE_REGISTRY + NO_CMAKE_BUILDS_PATH) + if (EIGEN3_FOUND) + message(STATUS "Found installed version of Eigen: ${Eigen3_DIR}") + else() + # Failed to find an installed version of Eigen, repeat search allowing + # exported build directories. + message(STATUS "Failed to find installed Eigen CMake configuration, " + "searching for Eigen build directories exported with CMake.") + # Again pass NO_CMAKE_BUILDS_PATH, as we know that Eigen is exported and + # do not want to treat projects built with the CMake GUI preferentially. + find_package(Eigen3 QUIET + NO_MODULE + NO_CMAKE_BUILDS_PATH) + if (EIGEN3_FOUND) + message(STATUS "Found exported Eigen build directory: ${Eigen3_DIR}") + endif() + endif() + if (EIGEN3_FOUND) + set(FOUND_INSTALLED_EIGEN_CMAKE_CONFIGURATION TRUE) + set(EIGEN_FOUND ${EIGEN3_FOUND}) + set(EIGEN_INCLUDE_DIR "${EIGEN3_INCLUDE_DIR}" CACHE STRING + "Eigen include directory" FORCE) + else() + message(STATUS "Failed to find an installed/exported CMake configuration " + "for Eigen, will perform search for installed Eigen components.") + endif() +endif() + +if (NOT EIGEN_FOUND) + # Search user-installed locations first, so that we prefer user installs + # to system installs where both exist. + list(APPEND EIGEN_CHECK_INCLUDE_DIRS + /usr/local/include + /usr/local/homebrew/include # Mac OS X + /opt/local/var/macports/software # Mac OS X. + /opt/local/include + /usr/include) + # Additional suffixes to try appending to each search path. + list(APPEND EIGEN_CHECK_PATH_SUFFIXES + eigen3 # Default root directory for Eigen. + Eigen/include/eigen3 # Windows (for C:/Program Files prefix) < 3.3 + Eigen3/include/eigen3 ) # Windows (for C:/Program Files prefix) >= 3.3 + + # Search supplied hint directories first if supplied. + find_path(EIGEN_INCLUDE_DIR + NAMES Eigen/Core + HINTS ${EIGEN_INCLUDE_DIR_HINTS} + PATHS ${EIGEN_CHECK_INCLUDE_DIRS} + PATH_SUFFIXES ${EIGEN_CHECK_PATH_SUFFIXES}) + + if (NOT EIGEN_INCLUDE_DIR OR + NOT EXISTS ${EIGEN_INCLUDE_DIR}) + eigen_report_not_found( + "Could not find eigen3 include directory, set EIGEN_INCLUDE_DIR to " + "path to eigen3 include directory, e.g. /usr/local/include/eigen3.") + endif (NOT EIGEN_INCLUDE_DIR OR + NOT EXISTS ${EIGEN_INCLUDE_DIR}) + + # Mark internally as found, then verify. EIGEN_REPORT_NOT_FOUND() unsets + # if called. + set(EIGEN_FOUND TRUE) +endif() + +# Extract Eigen version from Eigen/src/Core/util/Macros.h +if (EIGEN_INCLUDE_DIR) + set(EIGEN_VERSION_FILE ${EIGEN_INCLUDE_DIR}/Eigen/src/Core/util/Macros.h) + if (NOT EXISTS ${EIGEN_VERSION_FILE}) + eigen_report_not_found( + "Could not find file: ${EIGEN_VERSION_FILE} " + "containing version information in Eigen install located at: " + "${EIGEN_INCLUDE_DIR}.") + else (NOT EXISTS ${EIGEN_VERSION_FILE}) + file(READ ${EIGEN_VERSION_FILE} EIGEN_VERSION_FILE_CONTENTS) + + string(REGEX MATCH "#define EIGEN_WORLD_VERSION [0-9]+" + EIGEN_WORLD_VERSION "${EIGEN_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define EIGEN_WORLD_VERSION ([0-9]+)" "\\1" + EIGEN_WORLD_VERSION "${EIGEN_WORLD_VERSION}") + + string(REGEX MATCH "#define EIGEN_MAJOR_VERSION [0-9]+" + EIGEN_MAJOR_VERSION "${EIGEN_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define EIGEN_MAJOR_VERSION ([0-9]+)" "\\1" + EIGEN_MAJOR_VERSION "${EIGEN_MAJOR_VERSION}") + + string(REGEX MATCH "#define EIGEN_MINOR_VERSION [0-9]+" + EIGEN_MINOR_VERSION "${EIGEN_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define EIGEN_MINOR_VERSION ([0-9]+)" "\\1" + EIGEN_MINOR_VERSION "${EIGEN_MINOR_VERSION}") + + # This is on a single line s/t CMake does not interpret it as a list of + # elements and insert ';' separators which would result in 3.;2.;0 nonsense. + set(EIGEN_VERSION "${EIGEN_WORLD_VERSION}.${EIGEN_MAJOR_VERSION}.${EIGEN_MINOR_VERSION}") + endif (NOT EXISTS ${EIGEN_VERSION_FILE}) +endif (EIGEN_INCLUDE_DIR) + +# Set standard CMake FindPackage variables if found. +if (EIGEN_FOUND) + set(EIGEN_INCLUDE_DIRS ${EIGEN_INCLUDE_DIR}) +endif (EIGEN_FOUND) + +# Handle REQUIRED / QUIET optional arguments and version. +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Eigen + REQUIRED_VARS EIGEN_INCLUDE_DIRS + VERSION_VAR EIGEN_VERSION) + +# Only mark internal variables as advanced if we found Eigen, otherwise +# leave it visible in the standard GUI for the user to set manually. +if (EIGEN_FOUND) + mark_as_advanced(FORCE EIGEN_INCLUDE_DIR + Eigen3_DIR) # Autogenerated by find_package(Eigen3) +endif (EIGEN_FOUND) diff --git a/cmake/FindGflags.cmake b/cmake/FindGflags.cmake new file mode 100644 index 0000000..32c04ea --- /dev/null +++ b/cmake/FindGflags.cmake @@ -0,0 +1,591 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindGflags.cmake - Find Google gflags logging library. +# +# This module will attempt to find gflags, either via an exported CMake +# configuration (generated by gflags >= 2.1 which are built with CMake), or +# by performing a standard search for all gflags components. The order of +# precedence for these two methods of finding gflags is controlled by: +# GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION. +# +# This module defines the following variables: +# +# GFLAGS_FOUND: TRUE iff gflags is found. +# GFLAGS_INCLUDE_DIRS: Include directories for gflags. +# GFLAGS_LIBRARIES: Libraries required to link gflags. +# GFLAGS_NAMESPACE: The namespace in which gflags is defined. In versions of +# gflags < 2.1, this was google, for versions >= 2.1 it is +# by default gflags, although can be configured when building +# gflags to be something else (i.e. google for legacy +# compatibility). +# FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION: True iff the version of gflags +# found was built & installed / +# exported as a CMake package. +# +# The following variables control the behaviour of this module when an exported +# gflags CMake configuration is not found. +# +# GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION: TRUE/FALSE, iff TRUE then +# then prefer using an exported CMake configuration +# generated by gflags >= 2.1 over searching for the +# gflags components manually. Otherwise (FALSE) +# ignore any exported gflags CMake configurations and +# always perform a manual search for the components. +# Default: TRUE iff user does not define this variable +# before we are called, and does NOT specify either +# GFLAGS_INCLUDE_DIR_HINTS or GFLAGS_LIBRARY_DIR_HINTS +# otherwise FALSE. +# GFLAGS_INCLUDE_DIR_HINTS: List of additional directories in which to +# search for gflags includes, e.g: /timbuktu/include. +# GFLAGS_LIBRARY_DIR_HINTS: List of additional directories in which to +# search for gflags libraries, e.g: /timbuktu/lib. +# +# The following variables are also defined by this module, but in line with +# CMake recommended FindPackage() module style should NOT be referenced directly +# by callers (use the plural variables detailed above instead). These variables +# do however affect the behaviour of the module via FIND_[PATH/LIBRARY]() which +# are NOT re-called (i.e. search for library is not repeated) if these variables +# are set with valid values _in the CMake cache_. This means that if these +# variables are set directly in the cache, either by the user in the CMake GUI, +# or by the user passing -DVAR=VALUE directives to CMake when called (which +# explicitly defines a cache variable), then they will be used verbatim, +# bypassing the HINTS variables and other hard-coded search locations. +# +# GFLAGS_INCLUDE_DIR: Include directory for gflags, not including the +# include directory of any dependencies. +# GFLAGS_LIBRARY: gflags library, not including the libraries of any +# dependencies. + +# Reset CALLERS_CMAKE_FIND_LIBRARY_PREFIXES to its value when FindGflags was +# invoked, necessary for MSVC. +macro(GFLAGS_RESET_FIND_LIBRARY_PREFIX) + if (MSVC AND CALLERS_CMAKE_FIND_LIBRARY_PREFIXES) + set(CMAKE_FIND_LIBRARY_PREFIXES "${CALLERS_CMAKE_FIND_LIBRARY_PREFIXES}") + endif() +endmacro(GFLAGS_RESET_FIND_LIBRARY_PREFIX) + +# Called if we failed to find gflags or any of it's required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(GFLAGS_REPORT_NOT_FOUND REASON_MSG) + unset(GFLAGS_FOUND) + unset(GFLAGS_INCLUDE_DIRS) + unset(GFLAGS_LIBRARIES) + # Do not use unset, as we want to keep GFLAGS_NAMESPACE in the cache, + # but simply clear its value. + set(GFLAGS_NAMESPACE "" CACHE STRING + "gflags namespace (google or gflags)" FORCE) + + # Make results of search visible in the CMake GUI if gflags has not + # been found so that user does not have to toggle to advanced view. + mark_as_advanced(CLEAR GFLAGS_INCLUDE_DIR + GFLAGS_LIBRARY + GFLAGS_NAMESPACE) + + gflags_reset_find_library_prefix() + + # Note _FIND_[REQUIRED/QUIETLY] variables defined by FindPackage() + # use the camelcase library name, not uppercase. + if (Gflags_FIND_QUIETLY) + message(STATUS "Failed to find gflags - " ${REASON_MSG} ${ARGN}) + elseif (Gflags_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find gflags - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use no priority which emits a message + # but continues configuration and allows generation. + message("-- Failed to find gflags - " ${REASON_MSG} ${ARGN}) + endif () + return() +endmacro(GFLAGS_REPORT_NOT_FOUND) + +# Verify that all variable names passed as arguments are defined (can be empty +# but must be defined) or raise a fatal error. +macro(GFLAGS_CHECK_VARS_DEFINED) + foreach(CHECK_VAR ${ARGN}) + if (NOT DEFINED ${CHECK_VAR}) + message(FATAL_ERROR "Ceres Bug: ${CHECK_VAR} is not defined.") + endif() + endforeach() +endmacro(GFLAGS_CHECK_VARS_DEFINED) + +# Use check_cxx_source_compiles() to compile trivial test programs to determine +# the gflags namespace. This works on all OSs except Windows. If using Visual +# Studio, it fails because msbuild forces check_cxx_source_compiles() to use +# CMAKE_BUILD_TYPE=Debug for the test project, which usually breaks detection +# because MSVC requires that the test project use the same build type as gflags, +# which would normally be built in Release. +# +# Defines: GFLAGS_NAMESPACE in the caller's scope with the detected namespace, +# which is blank (empty string, will test FALSE is CMake conditionals) +# if detection failed. +function(GFLAGS_CHECK_GFLAGS_NAMESPACE_USING_TRY_COMPILE) + # Verify that all required variables are defined. + gflags_check_vars_defined( + GFLAGS_INCLUDE_DIR GFLAGS_LIBRARY) + # Ensure that GFLAGS_NAMESPACE is always unset on completion unless + # we explicitly set if after having the correct namespace. + set(GFLAGS_NAMESPACE "" PARENT_SCOPE) + + include(CheckCXXSourceCompiles) + # Setup include path & link library for gflags for CHECK_CXX_SOURCE_COMPILES. + set(CMAKE_REQUIRED_INCLUDES ${GFLAGS_INCLUDE_DIR}) + set(CMAKE_REQUIRED_LIBRARIES ${GFLAGS_LIBRARY} ${GFLAGS_LINK_LIBRARIES}) + # First try the (older) google namespace. Note that the output variable + # MUST be unique to the build type as otherwise the test is not repeated as + # it is assumed to have already been performed. + check_cxx_source_compiles( + "#include + int main(int argc, char * argv[]) { + google::ParseCommandLineFlags(&argc, &argv, true); + return 0; + }" + GFLAGS_IN_GOOGLE_NAMESPACE) + if (GFLAGS_IN_GOOGLE_NAMESPACE) + set(GFLAGS_NAMESPACE google PARENT_SCOPE) + return() + endif() + + # Try (newer) gflags namespace instead. Note that the output variable + # MUST be unique to the build type as otherwise the test is not repeated as + # it is assumed to have already been performed. + set(CMAKE_REQUIRED_INCLUDES ${GFLAGS_INCLUDE_DIR}) + set(CMAKE_REQUIRED_LIBRARIES ${GFLAGS_LIBRARY} ${GFLAGS_LINK_LIBRARIES}) + check_cxx_source_compiles( + "#include + int main(int argc, char * argv[]) { + gflags::ParseCommandLineFlags(&argc, &argv, true); + return 0; + }" + GFLAGS_IN_GFLAGS_NAMESPACE) + if (GFLAGS_IN_GFLAGS_NAMESPACE) + set(GFLAGS_NAMESPACE gflags PARENT_SCOPE) + return() + endif (GFLAGS_IN_GFLAGS_NAMESPACE) +endfunction(GFLAGS_CHECK_GFLAGS_NAMESPACE_USING_TRY_COMPILE) + +# Use regex on the gflags headers to attempt to determine the gflags namespace. +# Checks both gflags.h (contained namespace on versions < 2.1.2) and +# gflags_declare.h, which contains the namespace on versions >= 2.1.2. +# In general, this method should only be used when +# GFLAGS_CHECK_GFLAGS_NAMESPACE_USING_TRY_COMPILE() cannot be used, or has +# failed. +# +# Defines: GFLAGS_NAMESPACE in the caller's scope with the detected namespace, +# which is blank (empty string, will test FALSE is CMake conditionals) +# if detection failed. +function(GFLAGS_CHECK_GFLAGS_NAMESPACE_USING_REGEX) + # Verify that all required variables are defined. + gflags_check_vars_defined(GFLAGS_INCLUDE_DIR) + # Ensure that GFLAGS_NAMESPACE is always undefined on completion unless + # we explicitly set if after having the correct namespace. + set(GFLAGS_NAMESPACE "" PARENT_SCOPE) + + # Scan gflags.h to identify what namespace gflags was built with. On + # versions of gflags < 2.1.2, gflags.h was configured with the namespace + # directly, on >= 2.1.2, gflags.h uses the GFLAGS_NAMESPACE #define which + # is defined in gflags_declare.h, we try each location in turn. + set(GFLAGS_HEADER_FILE ${GFLAGS_INCLUDE_DIR}/gflags/gflags.h) + if (NOT EXISTS ${GFLAGS_HEADER_FILE}) + gflags_report_not_found( + "Could not find file: ${GFLAGS_HEADER_FILE} " + "containing namespace information in gflags install located at: " + "${GFLAGS_INCLUDE_DIR}.") + endif() + file(READ ${GFLAGS_HEADER_FILE} GFLAGS_HEADER_FILE_CONTENTS) + + string(REGEX MATCH "namespace [A-Za-z]+" + GFLAGS_NAMESPACE "${GFLAGS_HEADER_FILE_CONTENTS}") + string(REGEX REPLACE "namespace ([A-Za-z]+)" "\\1" + GFLAGS_NAMESPACE "${GFLAGS_NAMESPACE}") + + if (NOT GFLAGS_NAMESPACE) + gflags_report_not_found( + "Failed to extract gflags namespace from header file: " + "${GFLAGS_HEADER_FILE}.") + endif (NOT GFLAGS_NAMESPACE) + + if (GFLAGS_NAMESPACE STREQUAL "google" OR + GFLAGS_NAMESPACE STREQUAL "gflags") + # Found valid gflags namespace from gflags.h. + set(GFLAGS_NAMESPACE "${GFLAGS_NAMESPACE}" PARENT_SCOPE) + return() + endif() + + # Failed to find gflags namespace from gflags.h, gflags is likely a new + # version, check gflags_declare.h, which in newer versions (>= 2.1.2) contains + # the GFLAGS_NAMESPACE #define, which is then referenced in gflags.h. + set(GFLAGS_DECLARE_FILE ${GFLAGS_INCLUDE_DIR}/gflags/gflags_declare.h) + if (NOT EXISTS ${GFLAGS_DECLARE_FILE}) + gflags_report_not_found( + "Could not find file: ${GFLAGS_DECLARE_FILE} " + "containing namespace information in gflags install located at: " + "${GFLAGS_INCLUDE_DIR}.") + endif() + file(READ ${GFLAGS_DECLARE_FILE} GFLAGS_DECLARE_FILE_CONTENTS) + + string(REGEX MATCH "#define GFLAGS_NAMESPACE [A-Za-z]+" + GFLAGS_NAMESPACE "${GFLAGS_DECLARE_FILE_CONTENTS}") + string(REGEX REPLACE "#define GFLAGS_NAMESPACE ([A-Za-z]+)" "\\1" + GFLAGS_NAMESPACE "${GFLAGS_NAMESPACE}") + + if (NOT GFLAGS_NAMESPACE) + gflags_report_not_found( + "Failed to extract gflags namespace from declare file: " + "${GFLAGS_DECLARE_FILE}.") + endif (NOT GFLAGS_NAMESPACE) + + if (GFLAGS_NAMESPACE STREQUAL "google" OR + GFLAGS_NAMESPACE STREQUAL "gflags") + # Found valid gflags namespace from gflags.h. + set(GFLAGS_NAMESPACE "${GFLAGS_NAMESPACE}" PARENT_SCOPE) + return() + endif() +endfunction(GFLAGS_CHECK_GFLAGS_NAMESPACE_USING_REGEX) + +# Protect against any alternative find_package scripts for this library having +# been called previously (in a client project) which set GFLAGS_FOUND, but not +# the other variables we require / set here which could cause the search logic +# here to fail. +unset(GFLAGS_FOUND) + +# ----------------------------------------------------------------- +# By default, if the user has expressed no preference for using an exported +# gflags CMake configuration over performing a search for the installed +# components, and has not specified any hints for the search locations, then +# prefer a gflags exported configuration if available. +if (NOT DEFINED GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION + AND NOT GFLAGS_INCLUDE_DIR_HINTS + AND NOT GFLAGS_LIBRARY_DIR_HINTS) + message(STATUS "No preference for use of exported gflags CMake configuration " + "set, and no hints for include/library directories provided. " + "Defaulting to preferring an installed/exported gflags CMake configuration " + "if available.") + set(GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION TRUE) +endif() + +if (GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION) + # Try to find an exported CMake configuration for gflags, as generated by + # gflags versions >= 2.1. + # + # We search twice, s/t we can invert the ordering of precedence used by + # find_package() for exported package build directories, and installed + # packages (found via CMAKE_SYSTEM_PREFIX_PATH), listed as items 6) and 7) + # respectively in [1]. + # + # By default, exported build directories are (in theory) detected first, and + # this is usually the case on Windows. However, on OS X & Linux, the install + # path (/usr/local) is typically present in the PATH environment variable + # which is checked in item 4) in [1] (i.e. before both of the above, unless + # NO_SYSTEM_ENVIRONMENT_PATH is passed). As such on those OSs installed + # packages are usually detected in preference to exported package build + # directories. + # + # To ensure a more consistent response across all OSs, and as users usually + # want to prefer an installed version of a package over a locally built one + # where both exist (esp. as the exported build directory might be removed + # after installation), we first search with NO_CMAKE_PACKAGE_REGISTRY which + # means any build directories exported by the user are ignored, and thus + # installed directories are preferred. If this fails to find the package + # we then research again, but without NO_CMAKE_PACKAGE_REGISTRY, so any + # exported build directories will now be detected. + # + # To prevent confusion on Windows, we also pass NO_CMAKE_BUILDS_PATH (which + # is item 5) in [1]), to not preferentially use projects that were built + # recently with the CMake GUI to ensure that we always prefer an installed + # version if available. + # + # [1] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:find_package + find_package(gflags QUIET + NO_MODULE + NO_CMAKE_PACKAGE_REGISTRY + NO_CMAKE_BUILDS_PATH) + if (gflags_FOUND) + message(STATUS "Found installed version of gflags: ${gflags_DIR}") + else(gflags_FOUND) + # Failed to find an installed version of gflags, repeat search allowing + # exported build directories. + message(STATUS "Failed to find installed gflags CMake configuration, " + "searching for gflags build directories exported with CMake.") + # Again pass NO_CMAKE_BUILDS_PATH, as we know that gflags is exported and + # do not want to treat projects built with the CMake GUI preferentially. + find_package(gflags QUIET + NO_MODULE + NO_CMAKE_BUILDS_PATH) + if (gflags_FOUND) + message(STATUS "Found exported gflags build directory: ${gflags_DIR}") + endif(gflags_FOUND) + endif(gflags_FOUND) + + set(FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION ${gflags_FOUND}) + + # gflags v2.1 - 2.1.2 shipped with a bug in their gflags-config.cmake [1] + # whereby gflags_LIBRARIES = "gflags", but there was no imported target + # called "gflags", they were called: gflags[_nothreads]-[static/shared]. + # As this causes linker errors when gflags is not installed in a location + # on the current library paths, detect if this problem is present and + # fix it. + # + # [1] https://github.com/gflags/gflags/issues/110 + if (gflags_FOUND) + # NOTE: This is not written as additional conditions in the outer + # if (gflags_FOUND) as the NOT TARGET "${gflags_LIBRARIES}" + # condition causes problems if gflags is not found. + if (${gflags_VERSION} VERSION_LESS 2.1.3 AND + NOT TARGET "${gflags_LIBRARIES}") + message(STATUS "Detected broken gflags install in: ${gflags_DIR}, " + "version: ${gflags_VERSION} <= 2.1.2 which defines gflags_LIBRARIES = " + "${gflags_LIBRARIES} which is not an imported CMake target, see: " + "https://github.com/gflags/gflags/issues/110. Attempting to fix by " + "detecting correct gflags target.") + # Ordering here expresses preference for detection, specifically we do not + # want to use the _nothreads variants if the full library is available. + list(APPEND CHECK_GFLAGS_IMPORTED_TARGET_NAMES + gflags-shared gflags-static + gflags_nothreads-shared gflags_nothreads-static) + foreach(CHECK_GFLAGS_TARGET ${CHECK_GFLAGS_IMPORTED_TARGET_NAMES}) + if (TARGET ${CHECK_GFLAGS_TARGET}) + message(STATUS "Found valid gflags target: ${CHECK_GFLAGS_TARGET}, " + "updating gflags_LIBRARIES.") + set(gflags_LIBRARIES ${CHECK_GFLAGS_TARGET}) + break() + endif() + endforeach() + if (NOT TARGET ${gflags_LIBRARIES}) + message(STATUS "Failed to fix detected broken gflags install in: " + "${gflags_DIR}, version: ${gflags_VERSION} <= 2.1.2, none of the " + "imported targets for gflags: ${CHECK_GFLAGS_IMPORTED_TARGET_NAMES} " + "are defined. Will continue with a manual search for gflags " + "components. We recommend you build/install a version of gflags > " + "2.1.2 (or master).") + set(FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION FALSE) + endif() + endif() + endif() + + if (FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION) + message(STATUS "Detected gflags version: ${gflags_VERSION}") + set(GFLAGS_FOUND ${gflags_FOUND}) + set(GFLAGS_INCLUDE_DIR ${gflags_INCLUDE_DIR}) + set(GFLAGS_LIBRARY ${gflags_LIBRARIES}) + + # gflags does not export the namespace in their CMake configuration, so + # use our function to determine what it should be, as it can be either + # gflags or google dependent upon version & configuration. + # + # NOTE: We use the regex method to determine the namespace here, as + # check_cxx_source_compiles() will not use imported targets, which + # is what gflags will be in this case. + gflags_check_gflags_namespace_using_regex() + + if (NOT GFLAGS_NAMESPACE) + gflags_report_not_found( + "Failed to determine gflags namespace using regex for gflags " + "version: ${gflags_VERSION} exported here: ${gflags_DIR} using CMake.") + endif (NOT GFLAGS_NAMESPACE) + else (FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION) + message(STATUS "Failed to find an installed/exported CMake configuration " + "for gflags, will perform search for installed gflags components.") + endif (FOUND_INSTALLED_GFLAGS_CMAKE_CONFIGURATION) +endif(GFLAGS_PREFER_EXPORTED_GFLAGS_CMAKE_CONFIGURATION) + +if (NOT GFLAGS_FOUND) + # Either failed to find an exported gflags CMake configuration, or user + # told us not to use one. Perform a manual search for all gflags components. + + # Handle possible presence of lib prefix for libraries on MSVC, see + # also GFLAGS_RESET_FIND_LIBRARY_PREFIX(). + if (MSVC) + # Preserve the caller's original values for CMAKE_FIND_LIBRARY_PREFIXES + # s/t we can set it back before returning. + set(CALLERS_CMAKE_FIND_LIBRARY_PREFIXES "${CMAKE_FIND_LIBRARY_PREFIXES}") + # The empty string in this list is important, it represents the case when + # the libraries have no prefix (shared libraries / DLLs). + set(CMAKE_FIND_LIBRARY_PREFIXES "lib" "" "${CMAKE_FIND_LIBRARY_PREFIXES}") + endif (MSVC) + + # Search user-installed locations first, so that we prefer user installs + # to system installs where both exist. + list(APPEND GFLAGS_CHECK_INCLUDE_DIRS + /usr/local/include + /usr/local/homebrew/include # Mac OS X + /opt/local/var/macports/software # Mac OS X. + /opt/local/include + /usr/include) + list(APPEND GFLAGS_CHECK_PATH_SUFFIXES + gflags/include # Windows (for C:/Program Files prefix). + gflags/Include ) # Windows (for C:/Program Files prefix). + + list(APPEND GFLAGS_CHECK_LIBRARY_DIRS + /usr/local/lib + /usr/local/homebrew/lib # Mac OS X. + /opt/local/lib + /usr/lib) + list(APPEND GFLAGS_CHECK_LIBRARY_SUFFIXES + gflags/lib # Windows (for C:/Program Files prefix). + gflags/Lib ) # Windows (for C:/Program Files prefix). + + # Search supplied hint directories first if supplied. + find_path(GFLAGS_INCLUDE_DIR + NAMES gflags/gflags.h + HINTS ${GFLAGS_INCLUDE_DIR_HINTS} + PATHS ${GFLAGS_CHECK_INCLUDE_DIRS} + PATH_SUFFIXES ${GFLAGS_CHECK_PATH_SUFFIXES}) + if (NOT GFLAGS_INCLUDE_DIR OR + NOT EXISTS ${GFLAGS_INCLUDE_DIR}) + gflags_report_not_found( + "Could not find gflags include directory, set GFLAGS_INCLUDE_DIR " + "to directory containing gflags/gflags.h") + endif (NOT GFLAGS_INCLUDE_DIR OR + NOT EXISTS ${GFLAGS_INCLUDE_DIR}) + + find_library(GFLAGS_LIBRARY NAMES gflags + HINTS ${GFLAGS_LIBRARY_DIR_HINTS} + PATHS ${GFLAGS_CHECK_LIBRARY_DIRS} + PATH_SUFFIXES ${GFLAGS_CHECK_LIBRARY_SUFFIXES}) + if (NOT GFLAGS_LIBRARY OR + NOT EXISTS ${GFLAGS_LIBRARY}) + gflags_report_not_found( + "Could not find gflags library, set GFLAGS_LIBRARY " + "to full path to libgflags.") + endif (NOT GFLAGS_LIBRARY OR + NOT EXISTS ${GFLAGS_LIBRARY}) + + # gflags typically requires a threading library (which is OS dependent), note + # that this defines the CMAKE_THREAD_LIBS_INIT variable. If we are able to + # detect threads, we assume that gflags requires it. + find_package(Threads QUIET) + set(GFLAGS_LINK_LIBRARIES ${CMAKE_THREAD_LIBS_INIT}) + # On Windows (including MinGW), the Shlwapi library is used by gflags if + # available. + if (WIN32) + include(CheckIncludeFileCXX) + check_include_file_cxx("shlwapi.h" HAVE_SHLWAPI) + if (HAVE_SHLWAPI) + list(APPEND GFLAGS_LINK_LIBRARIES shlwapi.lib) + endif(HAVE_SHLWAPI) + endif (WIN32) + + # Mark internally as found, then verify. GFLAGS_REPORT_NOT_FOUND() unsets + # if called. + set(GFLAGS_FOUND TRUE) + + # Identify what namespace gflags was built with. + if (GFLAGS_INCLUDE_DIR AND NOT GFLAGS_NAMESPACE) + # To handle Windows peculiarities / CMake bugs on MSVC we try two approaches + # to detect the gflags namespace: + # + # 1) Try to use check_cxx_source_compiles() to compile a trivial program + # with the two choices for the gflags namespace. + # + # 2) [In the event 1) fails] Use regex on the gflags headers to try to + # determine the gflags namespace. Whilst this is less robust than 1), + # it does avoid any interaction with msbuild. + gflags_check_gflags_namespace_using_try_compile() + + if (NOT GFLAGS_NAMESPACE) + # Failed to determine gflags namespace using check_cxx_source_compiles() + # method, try and obtain it using regex on the gflags headers instead. + message(STATUS "Failed to find gflags namespace using using " + "check_cxx_source_compiles(), trying namespace regex instead, " + "this is expected on Windows.") + gflags_check_gflags_namespace_using_regex() + + if (NOT GFLAGS_NAMESPACE) + gflags_report_not_found( + "Failed to determine gflags namespace either by " + "check_cxx_source_compiles(), or namespace regex.") + endif (NOT GFLAGS_NAMESPACE) + endif (NOT GFLAGS_NAMESPACE) + endif (GFLAGS_INCLUDE_DIR AND NOT GFLAGS_NAMESPACE) + + # Make the GFLAGS_NAMESPACE a cache variable s/t the user can view it, and could + # overwrite it in the CMake GUI. + set(GFLAGS_NAMESPACE "${GFLAGS_NAMESPACE}" CACHE STRING + "gflags namespace (google or gflags)" FORCE) + + # gflags does not seem to provide any record of the version in its + # source tree, thus cannot extract version. + + # Catch case when caller has set GFLAGS_NAMESPACE in the cache / GUI + # with an invalid value. + if (GFLAGS_NAMESPACE AND + NOT GFLAGS_NAMESPACE STREQUAL "google" AND + NOT GFLAGS_NAMESPACE STREQUAL "gflags") + gflags_report_not_found( + "Caller defined GFLAGS_NAMESPACE:" + " ${GFLAGS_NAMESPACE} is not valid, not google or gflags.") + endif () + # Catch case when caller has set GFLAGS_INCLUDE_DIR in the cache / GUI and + # thus FIND_[PATH/LIBRARY] are not called, but specified locations are + # invalid, otherwise we would report the library as found. + if (GFLAGS_INCLUDE_DIR AND + NOT EXISTS ${GFLAGS_INCLUDE_DIR}/gflags/gflags.h) + gflags_report_not_found( + "Caller defined GFLAGS_INCLUDE_DIR:" + " ${GFLAGS_INCLUDE_DIR} does not contain gflags/gflags.h header.") + endif (GFLAGS_INCLUDE_DIR AND + NOT EXISTS ${GFLAGS_INCLUDE_DIR}/gflags/gflags.h) + # TODO: This regex for gflags library is pretty primitive, we use lowercase + # for comparison to handle Windows using CamelCase library names, could + # this check be better? + string(TOLOWER "${GFLAGS_LIBRARY}" LOWERCASE_GFLAGS_LIBRARY) + if (GFLAGS_LIBRARY AND + NOT "${LOWERCASE_GFLAGS_LIBRARY}" MATCHES ".*gflags[^/]*") + gflags_report_not_found( + "Caller defined GFLAGS_LIBRARY: " + "${GFLAGS_LIBRARY} does not match gflags.") + endif (GFLAGS_LIBRARY AND + NOT "${LOWERCASE_GFLAGS_LIBRARY}" MATCHES ".*gflags[^/]*") + + gflags_reset_find_library_prefix() + +endif(NOT GFLAGS_FOUND) + +# Set standard CMake FindPackage variables if found. +if (GFLAGS_FOUND) + set(GFLAGS_INCLUDE_DIRS ${GFLAGS_INCLUDE_DIR}) + set(GFLAGS_LIBRARIES ${GFLAGS_LIBRARY} ${GFLAGS_LINK_LIBRARIES}) +endif (GFLAGS_FOUND) + +# Handle REQUIRED / QUIET optional arguments. +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Gflags DEFAULT_MSG + GFLAGS_INCLUDE_DIRS GFLAGS_LIBRARIES GFLAGS_NAMESPACE) + +# Only mark internal variables as advanced if we found gflags, otherwise +# leave them visible in the standard GUI for the user to set manually. +if (GFLAGS_FOUND) + mark_as_advanced(FORCE GFLAGS_INCLUDE_DIR + GFLAGS_LIBRARY + GFLAGS_NAMESPACE + gflags_DIR) # Autogenerated by find_package(gflags) +endif (GFLAGS_FOUND) diff --git a/cmake/FindGlog.cmake b/cmake/FindGlog.cmake new file mode 100644 index 0000000..979dced --- /dev/null +++ b/cmake/FindGlog.cmake @@ -0,0 +1,346 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindGlog.cmake - Find Google glog logging library. +# +# This module defines the following variables: +# +# GLOG_FOUND: TRUE iff glog is found. +# GLOG_INCLUDE_DIRS: Include directories for glog. +# GLOG_LIBRARIES: Libraries required to link glog. +# FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION: True iff the version of glog found +# was built & installed / exported +# as a CMake package. +# +# The following variables control the behaviour of this module: +# +# GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION: TRUE/FALSE, iff TRUE then +# then prefer using an exported CMake configuration +# generated by glog > 0.3.4 over searching for the +# glog components manually. Otherwise (FALSE) +# ignore any exported glog CMake configurations and +# always perform a manual search for the components. +# Default: TRUE iff user does not define this variable +# before we are called, and does NOT specify either +# GLOG_INCLUDE_DIR_HINTS or GLOG_LIBRARY_DIR_HINTS +# otherwise FALSE. +# GLOG_INCLUDE_DIR_HINTS: List of additional directories in which to +# search for glog includes, e.g: /timbuktu/include. +# GLOG_LIBRARY_DIR_HINTS: List of additional directories in which to +# search for glog libraries, e.g: /timbuktu/lib. +# +# The following variables are also defined by this module, but in line with +# CMake recommended FindPackage() module style should NOT be referenced directly +# by callers (use the plural variables detailed above instead). These variables +# do however affect the behaviour of the module via FIND_[PATH/LIBRARY]() which +# are NOT re-called (i.e. search for library is not repeated) if these variables +# are set with valid values _in the CMake cache_. This means that if these +# variables are set directly in the cache, either by the user in the CMake GUI, +# or by the user passing -DVAR=VALUE directives to CMake when called (which +# explicitly defines a cache variable), then they will be used verbatim, +# bypassing the HINTS variables and other hard-coded search locations. +# +# GLOG_INCLUDE_DIR: Include directory for glog, not including the +# include directory of any dependencies. +# GLOG_LIBRARY: glog library, not including the libraries of any +# dependencies. + +# Reset CALLERS_CMAKE_FIND_LIBRARY_PREFIXES to its value when +# FindGlog was invoked. +macro(GLOG_RESET_FIND_LIBRARY_PREFIX) + if (MSVC AND CALLERS_CMAKE_FIND_LIBRARY_PREFIXES) + set(CMAKE_FIND_LIBRARY_PREFIXES "${CALLERS_CMAKE_FIND_LIBRARY_PREFIXES}") + endif() +endmacro(GLOG_RESET_FIND_LIBRARY_PREFIX) + +# Called if we failed to find glog or any of it's required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(GLOG_REPORT_NOT_FOUND REASON_MSG) + unset(GLOG_FOUND) + unset(GLOG_INCLUDE_DIRS) + unset(GLOG_LIBRARIES) + # Make results of search visible in the CMake GUI if glog has not + # been found so that user does not have to toggle to advanced view. + mark_as_advanced(CLEAR GLOG_INCLUDE_DIR + GLOG_LIBRARY) + + glog_reset_find_library_prefix() + + # Note _FIND_[REQUIRED/QUIETLY] variables defined by FindPackage() + # use the camelcase library name, not uppercase. + if (Glog_FIND_QUIETLY) + message(STATUS "Failed to find glog - " ${REASON_MSG} ${ARGN}) + elseif (Glog_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find glog - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use no priority which emits a message + # but continues configuration and allows generation. + message("-- Failed to find glog - " ${REASON_MSG} ${ARGN}) + endif () + return() +endmacro(GLOG_REPORT_NOT_FOUND) + +# Protect against any alternative find_package scripts for this library having +# been called previously (in a client project) which set GLOG_FOUND, but not +# the other variables we require / set here which could cause the search logic +# here to fail. +unset(GLOG_FOUND) + +# ----------------------------------------------------------------- +# By default, if the user has expressed no preference for using an exported +# glog CMake configuration over performing a search for the installed +# components, and has not specified any hints for the search locations, then +# prefer a glog exported configuration if available. +if (NOT DEFINED GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION + AND NOT GLOG_INCLUDE_DIR_HINTS + AND NOT GLOG_LIBRARY_DIR_HINTS) + message(STATUS "No preference for use of exported glog CMake configuration " + "set, and no hints for include/library directories provided. " + "Defaulting to preferring an installed/exported glog CMake configuration " + "if available.") + set(GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION TRUE) +endif() + +if (GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION) + # Try to find an exported CMake configuration for glog, as generated by + # glog versions > 0.3.4 + # + # We search twice, s/t we can invert the ordering of precedence used by + # find_package() for exported package build directories, and installed + # packages (found via CMAKE_SYSTEM_PREFIX_PATH), listed as items 6) and 7) + # respectively in [1]. + # + # By default, exported build directories are (in theory) detected first, and + # this is usually the case on Windows. However, on OS X & Linux, the install + # path (/usr/local) is typically present in the PATH environment variable + # which is checked in item 4) in [1] (i.e. before both of the above, unless + # NO_SYSTEM_ENVIRONMENT_PATH is passed). As such on those OSs installed + # packages are usually detected in preference to exported package build + # directories. + # + # To ensure a more consistent response across all OSs, and as users usually + # want to prefer an installed version of a package over a locally built one + # where both exist (esp. as the exported build directory might be removed + # after installation), we first search with NO_CMAKE_PACKAGE_REGISTRY which + # means any build directories exported by the user are ignored, and thus + # installed directories are preferred. If this fails to find the package + # we then research again, but without NO_CMAKE_PACKAGE_REGISTRY, so any + # exported build directories will now be detected. + # + # To prevent confusion on Windows, we also pass NO_CMAKE_BUILDS_PATH (which + # is item 5) in [1]), to not preferentially use projects that were built + # recently with the CMake GUI to ensure that we always prefer an installed + # version if available. + # + # NOTE: We use the NAMES option as glog erroneously uses 'google-glog' as its + # project name when built with CMake, but exports itself as just 'glog'. + # On Linux/OS X this does not break detection as the project name is + # not used as part of the install path for the CMake package files, + # e.g. /usr/local/lib/cmake/glog, where the suffix is hardcoded + # in glog's CMakeLists. However, on Windows the project name *is* + # part of the install prefix: C:/Program Files/google-glog/[include,lib]. + # However, by default CMake checks: + # C:/Program Files/ which does not + # exist and thus detection fails. Thus we use the NAMES to force the + # search to use both google-glog & glog. + # + # [1] http://www.cmake.org/cmake/help/v2.8.11/cmake.html#command:find_package + find_package(glog QUIET + NAMES google-glog glog + NO_MODULE + NO_CMAKE_PACKAGE_REGISTRY + NO_CMAKE_BUILDS_PATH) + if (glog_FOUND) + message(STATUS "Found installed version of glog: ${glog_DIR}") + else() + # Failed to find an installed version of glog, repeat search allowing + # exported build directories. + message(STATUS "Failed to find installed glog CMake configuration, " + "searching for glog build directories exported with CMake.") + # Again pass NO_CMAKE_BUILDS_PATH, as we know that glog is exported and + # do not want to treat projects built with the CMake GUI preferentially. + find_package(glog QUIET + NAMES google-glog glog + NO_MODULE + NO_CMAKE_BUILDS_PATH) + if (glog_FOUND) + message(STATUS "Found exported glog build directory: ${glog_DIR}") + endif(glog_FOUND) + endif(glog_FOUND) + + set(FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION ${glog_FOUND}) + + if (FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION) + message(STATUS "Detected glog version: ${glog_VERSION}") + set(GLOG_FOUND ${glog_FOUND}) + # glog wraps the include directories into the exported glog::glog target. + set(GLOG_INCLUDE_DIR "") + set(GLOG_LIBRARY glog::glog) + else (FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION) + message(STATUS "Failed to find an installed/exported CMake configuration " + "for glog, will perform search for installed glog components.") + endif (FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION) +endif(GLOG_PREFER_EXPORTED_GLOG_CMAKE_CONFIGURATION) + +if (NOT GLOG_FOUND) + # Either failed to find an exported glog CMake configuration, or user + # told us not to use one. Perform a manual search for all glog components. + + # Handle possible presence of lib prefix for libraries on MSVC, see + # also GLOG_RESET_FIND_LIBRARY_PREFIX(). + if (MSVC) + # Preserve the caller's original values for CMAKE_FIND_LIBRARY_PREFIXES + # s/t we can set it back before returning. + set(CALLERS_CMAKE_FIND_LIBRARY_PREFIXES "${CMAKE_FIND_LIBRARY_PREFIXES}") + # The empty string in this list is important, it represents the case when + # the libraries have no prefix (shared libraries / DLLs). + set(CMAKE_FIND_LIBRARY_PREFIXES "lib" "" "${CMAKE_FIND_LIBRARY_PREFIXES}") + endif (MSVC) + + # Search user-installed locations first, so that we prefer user installs + # to system installs where both exist. + list(APPEND GLOG_CHECK_INCLUDE_DIRS + /usr/local/include + /usr/local/homebrew/include # Mac OS X + /opt/local/var/macports/software # Mac OS X. + /opt/local/include + /usr/include) + # Windows (for C:/Program Files prefix). + list(APPEND GLOG_CHECK_PATH_SUFFIXES + glog/include + glog/Include + Glog/include + Glog/Include + google-glog/include # CMake installs with project name prefix. + google-glog/Include) + + list(APPEND GLOG_CHECK_LIBRARY_DIRS + /usr/local/lib + /usr/local/homebrew/lib # Mac OS X. + /opt/local/lib + /usr/lib) + # Windows (for C:/Program Files prefix). + list(APPEND GLOG_CHECK_LIBRARY_SUFFIXES + glog/lib + glog/Lib + Glog/lib + Glog/Lib + google-glog/lib # CMake installs with project name prefix. + google-glog/Lib) + + # Search supplied hint directories first if supplied. + find_path(GLOG_INCLUDE_DIR + NAMES glog/logging.h + HINTS ${GLOG_INCLUDE_DIR_HINTS} + PATHS ${GLOG_CHECK_INCLUDE_DIRS} + PATH_SUFFIXES ${GLOG_CHECK_PATH_SUFFIXES}) + if (NOT GLOG_INCLUDE_DIR OR + NOT EXISTS ${GLOG_INCLUDE_DIR}) + glog_report_not_found( + "Could not find glog include directory, set GLOG_INCLUDE_DIR " + "to directory containing glog/logging.h") + endif (NOT GLOG_INCLUDE_DIR OR + NOT EXISTS ${GLOG_INCLUDE_DIR}) + + find_library(GLOG_LIBRARY NAMES glog + HINTS ${GLOG_LIBRARY_DIR_HINTS} + PATHS ${GLOG_CHECK_LIBRARY_DIRS} + PATH_SUFFIXES ${GLOG_CHECK_LIBRARY_SUFFIXES}) + if (NOT GLOG_LIBRARY OR + NOT EXISTS ${GLOG_LIBRARY}) + glog_report_not_found( + "Could not find glog library, set GLOG_LIBRARY " + "to full path to libglog.") + endif (NOT GLOG_LIBRARY OR + NOT EXISTS ${GLOG_LIBRARY}) + + # Mark internally as found, then verify. GLOG_REPORT_NOT_FOUND() unsets + # if called. + set(GLOG_FOUND TRUE) + + # Glog does not seem to provide any record of the version in its + # source tree, thus cannot extract version. + + # Catch case when caller has set GLOG_INCLUDE_DIR in the cache / GUI and + # thus FIND_[PATH/LIBRARY] are not called, but specified locations are + # invalid, otherwise we would report the library as found. + if (GLOG_INCLUDE_DIR AND + NOT EXISTS ${GLOG_INCLUDE_DIR}/glog/logging.h) + glog_report_not_found( + "Caller defined GLOG_INCLUDE_DIR:" + " ${GLOG_INCLUDE_DIR} does not contain glog/logging.h header.") + endif (GLOG_INCLUDE_DIR AND + NOT EXISTS ${GLOG_INCLUDE_DIR}/glog/logging.h) + # TODO: This regex for glog library is pretty primitive, we use lowercase + # for comparison to handle Windows using CamelCase library names, could + # this check be better? + string(TOLOWER "${GLOG_LIBRARY}" LOWERCASE_GLOG_LIBRARY) + if (GLOG_LIBRARY AND + NOT "${LOWERCASE_GLOG_LIBRARY}" MATCHES ".*glog[^/]*") + glog_report_not_found( + "Caller defined GLOG_LIBRARY: " + "${GLOG_LIBRARY} does not match glog.") + endif (GLOG_LIBRARY AND + NOT "${LOWERCASE_GLOG_LIBRARY}" MATCHES ".*glog[^/]*") + + glog_reset_find_library_prefix() + +endif(NOT GLOG_FOUND) + +# Set standard CMake FindPackage variables if found. +if (GLOG_FOUND) + set(GLOG_INCLUDE_DIRS ${GLOG_INCLUDE_DIR}) + set(GLOG_LIBRARIES ${GLOG_LIBRARY}) +endif (GLOG_FOUND) + +# If we are using an exported CMake glog target, the include directories are +# wrapped into the target itself, and do not have to be (and are not) +# separately specified. In which case, we should not add GLOG_INCLUDE_DIRS +# to the list of required variables in order that glog be reported as found. +if (FOUND_INSTALLED_GLOG_CMAKE_CONFIGURATION) + set(GLOG_REQUIRED_VARIABLES GLOG_LIBRARIES) +else() + set(GLOG_REQUIRED_VARIABLES GLOG_INCLUDE_DIRS GLOG_LIBRARIES) +endif() + +# Handle REQUIRED / QUIET optional arguments. +include(FindPackageHandleStandardArgs) +find_package_handle_standard_args(Glog DEFAULT_MSG + ${GLOG_REQUIRED_VARIABLES}) + +# Only mark internal variables as advanced if we found glog, otherwise +# leave them visible in the standard GUI for the user to set manually. +if (GLOG_FOUND) + mark_as_advanced(FORCE GLOG_INCLUDE_DIR + GLOG_LIBRARY + glog_DIR) # Autogenerated by find_package(glog) +endif (GLOG_FOUND) diff --git a/cmake/FindSharedPtr.cmake b/cmake/FindSharedPtr.cmake new file mode 100644 index 0000000..e37c969 --- /dev/null +++ b/cmake/FindSharedPtr.cmake @@ -0,0 +1,108 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: sergey.vfx@gmail.com (Sergey Sharybin) +# + +# FindSharedPtr.cmake - Find shared pointer header and namespace. +# +# This module defines the following variables: +# +# SHARED_PTR_FOUND: TRUE if shared_ptr found. +# SHARED_PTR_TR1_MEMORY_HEADER: True if header is to be used +# for the shared_ptr object, otherwise use . +# SHARED_PTR_TR1_NAMESPACE: TRUE if shared_ptr is defined in std::tr1 namespace, +# otherwise it's assumed to be defined in std namespace. + +macro(FIND_SHARED_PTR) + # To support CXX11 option, clear the results of all check_xxx() functions + # s/t we always perform the checks each time, otherwise CMake fails to + # detect that the tests should be performed again after CXX11 is toggled. + unset(HAVE_STD_MEMORY_HEADER CACHE) + unset(HAVE_SHARED_PTR_IN_STD_NAMESPACE CACHE) + unset(HAVE_SHARED_PTR_IN_TR1_NAMESPACE CACHE) + unset(HAVE_TR1_MEMORY_HEADER CACHE) + unset(HAVE_SHARED_PTR_IN_TR1_NAMESPACE_FROM_TR1_MEMORY_HEADER CACHE) + + set(SHARED_PTR_FOUND FALSE) + check_include_file_cxx(memory HAVE_STD_MEMORY_HEADER) + if (HAVE_STD_MEMORY_HEADER) + # Finding the memory header doesn't mean that shared_ptr is in std + # namespace. + # + # In particular, MSVC 2008 has shared_ptr declared in std::tr1. In + # order to support this, we do an extra check to see which namespace + # should be used. + include(CheckCXXSourceCompiles) + check_cxx_source_compiles("#include + int main() { + std::shared_ptr int_ptr; + return 0; + }" + HAVE_SHARED_PTR_IN_STD_NAMESPACE) + + if (HAVE_SHARED_PTR_IN_STD_NAMESPACE) + message("-- Found shared_ptr in std namespace using header.") + set(SHARED_PTR_FOUND TRUE) + else (HAVE_SHARED_PTR_IN_STD_NAMESPACE) + check_cxx_source_compiles("#include + int main() { + std::tr1::shared_ptr int_ptr; + return 0; + }" + HAVE_SHARED_PTR_IN_TR1_NAMESPACE) + if (HAVE_SHARED_PTR_IN_TR1_NAMESPACE) + message("-- Found shared_ptr in std::tr1 namespace using header.") + set(SHARED_PTR_TR1_NAMESPACE TRUE) + set(SHARED_PTR_FOUND TRUE) + endif (HAVE_SHARED_PTR_IN_TR1_NAMESPACE) + endif (HAVE_SHARED_PTR_IN_STD_NAMESPACE) + endif (HAVE_STD_MEMORY_HEADER) + + if (NOT SHARED_PTR_FOUND) + # Further, gcc defines shared_ptr in std::tr1 namespace and + # is to be included for this. And what makes things + # even more tricky is that gcc does have header, so + # all the checks above wouldn't find shared_ptr. + check_include_file_cxx("tr1/memory" HAVE_TR1_MEMORY_HEADER) + if (HAVE_TR1_MEMORY_HEADER) + check_cxx_source_compiles("#include + int main() { + std::tr1::shared_ptr int_ptr; + return 0; + }" + HAVE_SHARED_PTR_IN_TR1_NAMESPACE_FROM_TR1_MEMORY_HEADER) + if (HAVE_SHARED_PTR_IN_TR1_NAMESPACE_FROM_TR1_MEMORY_HEADER) + message("-- Found shared_ptr in std::tr1 namespace using header.") + set(SHARED_PTR_TR1_MEMORY_HEADER TRUE) + set(SHARED_PTR_TR1_NAMESPACE TRUE) + set(SHARED_PTR_FOUND TRUE) + endif (HAVE_SHARED_PTR_IN_TR1_NAMESPACE_FROM_TR1_MEMORY_HEADER) + endif (HAVE_TR1_MEMORY_HEADER) + endif (NOT SHARED_PTR_FOUND) +endmacro(FIND_SHARED_PTR) diff --git a/cmake/FindSphinx.cmake b/cmake/FindSphinx.cmake new file mode 100644 index 0000000..220108d --- /dev/null +++ b/cmake/FindSphinx.cmake @@ -0,0 +1,66 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: pablo.speciale@gmail.com (Pablo Speciale) +# + +# Find the Sphinx documentation generator +# +# This modules defines +# SPHINX_EXECUTABLE +# SPHINX_FOUND + +find_program(SPHINX_EXECUTABLE + NAMES sphinx-build + PATHS + /usr/bin + /usr/local/bin + /opt/local/bin + DOC "Sphinx documentation generator") + +if (NOT SPHINX_EXECUTABLE) + set(_Python_VERSIONS 2.7 2.6 2.5 2.4 2.3 2.2 2.1 2.0 1.6 1.5) + + foreach (_version ${_Python_VERSIONS}) + set(_sphinx_NAMES sphinx-build-${_version}) + + find_program(SPHINX_EXECUTABLE + NAMES ${_sphinx_NAMES} + PATHS + /usr/bin + /usr/local/bin + /opt/local/bin + DOC "Sphinx documentation generator") + endforeach () +endif () + +include(FindPackageHandleStandardArgs) + +find_package_handle_standard_args(Sphinx DEFAULT_MSG SPHINX_EXECUTABLE) + +mark_as_advanced(SPHINX_EXECUTABLE) diff --git a/cmake/FindSuiteSparse.cmake b/cmake/FindSuiteSparse.cmake new file mode 100644 index 0000000..ede687a --- /dev/null +++ b/cmake/FindSuiteSparse.cmake @@ -0,0 +1,518 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindSuiteSparse.cmake - Find SuiteSparse libraries & dependencies. +# +# This module defines the following variables: +# +# SUITESPARSE_FOUND: TRUE iff SuiteSparse and all dependencies have been found. +# SUITESPARSE_INCLUDE_DIRS: Include directories for all SuiteSparse components. +# SUITESPARSE_LIBRARIES: Libraries for all SuiteSparse component libraries and +# dependencies. +# SUITESPARSE_VERSION: Extracted from UFconfig.h (<= v3) or +# SuiteSparse_config.h (>= v4). +# SUITESPARSE_MAIN_VERSION: Equal to 4 if SUITESPARSE_VERSION = 4.2.1 +# SUITESPARSE_SUB_VERSION: Equal to 2 if SUITESPARSE_VERSION = 4.2.1 +# SUITESPARSE_SUBSUB_VERSION: Equal to 1 if SUITESPARSE_VERSION = 4.2.1 +# +# SUITESPARSE_IS_BROKEN_SHARED_LINKING_UBUNTU_SYSTEM_VERSION: TRUE iff running +# on Ubuntu, SUITESPARSE_VERSION is 3.4.0 and found SuiteSparse is a system +# install, in which case found version of SuiteSparse cannot be used to link +# a shared library due to a bug (static linking is unaffected). +# +# The following variables control the behaviour of this module: +# +# SUITESPARSE_INCLUDE_DIR_HINTS: List of additional directories in which to +# search for SuiteSparse includes, +# e.g: /timbuktu/include. +# SUITESPARSE_LIBRARY_DIR_HINTS: List of additional directories in which to +# search for SuiteSparse libraries, +# e.g: /timbuktu/lib. +# +# The following variables define the presence / includes & libraries for the +# SuiteSparse components searched for, the SUITESPARSE_XX variables are the +# union of the variables for all components. +# +# == Symmetric Approximate Minimum Degree (AMD) +# AMD_FOUND +# AMD_INCLUDE_DIR +# AMD_LIBRARY +# +# == Constrained Approximate Minimum Degree (CAMD) +# CAMD_FOUND +# CAMD_INCLUDE_DIR +# CAMD_LIBRARY +# +# == Column Approximate Minimum Degree (COLAMD) +# COLAMD_FOUND +# COLAMD_INCLUDE_DIR +# COLAMD_LIBRARY +# +# Constrained Column Approximate Minimum Degree (CCOLAMD) +# CCOLAMD_FOUND +# CCOLAMD_INCLUDE_DIR +# CCOLAMD_LIBRARY +# +# == Sparse Supernodal Cholesky Factorization and Update/Downdate (CHOLMOD) +# CHOLMOD_FOUND +# CHOLMOD_INCLUDE_DIR +# CHOLMOD_LIBRARY +# +# == Multifrontal Sparse QR (SuiteSparseQR) +# SUITESPARSEQR_FOUND +# SUITESPARSEQR_INCLUDE_DIR +# SUITESPARSEQR_LIBRARY +# +# == Common configuration for all but CSparse (SuiteSparse version >= 4). +# SUITESPARSE_CONFIG_FOUND +# SUITESPARSE_CONFIG_INCLUDE_DIR +# SUITESPARSE_CONFIG_LIBRARY +# +# == Common configuration for all but CSparse (SuiteSparse version < 4). +# UFCONFIG_FOUND +# UFCONFIG_INCLUDE_DIR +# +# Optional SuiteSparse Dependencies: +# +# == Serial Graph Partitioning and Fill-reducing Matrix Ordering (METIS) +# METIS_FOUND +# METIS_LIBRARY +# +# == Intel Thread Building Blocks (TBB) +# TBB_FOUND +# TBB_LIBRARY +# TBB_MALLOC_FOUND +# TBB_MALLOC_LIBRARY + +# Reset CALLERS_CMAKE_FIND_LIBRARY_PREFIXES to its value when +# FindSuiteSparse was invoked. +macro(SUITESPARSE_RESET_FIND_LIBRARY_PREFIX) + if (MSVC) + set(CMAKE_FIND_LIBRARY_PREFIXES "${CALLERS_CMAKE_FIND_LIBRARY_PREFIXES}") + endif (MSVC) +endmacro(SUITESPARSE_RESET_FIND_LIBRARY_PREFIX) + +# Called if we failed to find SuiteSparse or any of it's required dependencies, +# unsets all public (designed to be used externally) variables and reports +# error message at priority depending upon [REQUIRED/QUIET/] argument. +macro(SUITESPARSE_REPORT_NOT_FOUND REASON_MSG) + unset(SUITESPARSE_FOUND) + unset(SUITESPARSE_INCLUDE_DIRS) + unset(SUITESPARSE_LIBRARIES) + unset(SUITESPARSE_VERSION) + unset(SUITESPARSE_MAIN_VERSION) + unset(SUITESPARSE_SUB_VERSION) + unset(SUITESPARSE_SUBSUB_VERSION) + # Do NOT unset SUITESPARSE_FOUND_REQUIRED_VARS here, as it is used by + # FindPackageHandleStandardArgs() to generate the automatic error message on + # failure which highlights which components are missing. + + suitesparse_reset_find_library_prefix() + + # Note _FIND_[REQUIRED/QUIETLY] variables defined by FindPackage() + # use the camelcase library name, not uppercase. + if (SuiteSparse_FIND_QUIETLY) + message(STATUS "Failed to find SuiteSparse - " ${REASON_MSG} ${ARGN}) + elseif (SuiteSparse_FIND_REQUIRED) + message(FATAL_ERROR "Failed to find SuiteSparse - " ${REASON_MSG} ${ARGN}) + else() + # Neither QUIETLY nor REQUIRED, use no priority which emits a message + # but continues configuration and allows generation. + message("-- Failed to find SuiteSparse - " ${REASON_MSG} ${ARGN}) + endif (SuiteSparse_FIND_QUIETLY) + + # Do not call return(), s/t we keep processing if not called with REQUIRED + # and report all missing components, rather than bailing after failing to find + # the first. +endmacro(SUITESPARSE_REPORT_NOT_FOUND) + +# Protect against any alternative find_package scripts for this library having +# been called previously (in a client project) which set SUITESPARSE_FOUND, but +# not the other variables we require / set here which could cause the search +# logic here to fail. +unset(SUITESPARSE_FOUND) + +# Handle possible presence of lib prefix for libraries on MSVC, see +# also SUITESPARSE_RESET_FIND_LIBRARY_PREFIX(). +if (MSVC) + # Preserve the caller's original values for CMAKE_FIND_LIBRARY_PREFIXES + # s/t we can set it back before returning. + set(CALLERS_CMAKE_FIND_LIBRARY_PREFIXES "${CMAKE_FIND_LIBRARY_PREFIXES}") + # The empty string in this list is important, it represents the case when + # the libraries have no prefix (shared libraries / DLLs). + set(CMAKE_FIND_LIBRARY_PREFIXES "lib" "" "${CMAKE_FIND_LIBRARY_PREFIXES}") +endif (MSVC) + +# Specify search directories for include files and libraries (this is the union +# of the search directories for all OSs). Search user-specified hint +# directories first if supplied, and search user-installed locations first +# so that we prefer user installs to system installs where both exist. +list(APPEND SUITESPARSE_CHECK_INCLUDE_DIRS + /opt/local/include + /opt/local/include/ufsparse # Mac OS X + /usr/local/homebrew/include # Mac OS X + /usr/local/include + /usr/include) +list(APPEND SUITESPARSE_CHECK_LIBRARY_DIRS + /opt/local/lib + /opt/local/lib/ufsparse # Mac OS X + /usr/local/homebrew/lib # Mac OS X + /usr/local/lib + /usr/lib) +# Additional suffixes to try appending to each search path. +list(APPEND SUITESPARSE_CHECK_PATH_SUFFIXES + suitesparse) # Windows/Ubuntu + +# Wrappers to find_path/library that pass the SuiteSparse search hints/paths. +# +# suitesparse_find_component( [FILES name1 [name2 ...]] +# [LIBRARIES name1 [name2 ...]] +# [REQUIRED]) +macro(suitesparse_find_component COMPONENT) + include(CMakeParseArguments) + set(OPTIONS REQUIRED) + set(MULTI_VALUE_ARGS FILES LIBRARIES) + cmake_parse_arguments(SUITESPARSE_FIND_${COMPONENT} + "${OPTIONS}" "" "${MULTI_VALUE_ARGS}" ${ARGN}) + + if (SUITESPARSE_FIND_${COMPONENT}_REQUIRED) + list(APPEND SUITESPARSE_FOUND_REQUIRED_VARS ${COMPONENT}_FOUND) + endif() + + set(${COMPONENT}_FOUND TRUE) + if (SUITESPARSE_FIND_${COMPONENT}_FILES) + find_path(${COMPONENT}_INCLUDE_DIR + NAMES ${SUITESPARSE_FIND_${COMPONENT}_FILES} + HINTS ${SUITESPARSE_INCLUDE_DIR_HINTS} + PATHS ${SUITESPARSE_CHECK_INCLUDE_DIRS} + PATH_SUFFIXES ${SUITESPARSE_CHECK_PATH_SUFFIXES}) + if (${COMPONENT}_INCLUDE_DIR) + message(STATUS "Found ${COMPONENT} headers in: " + "${${COMPONENT}_INCLUDE_DIR}") + mark_as_advanced(${COMPONENT}_INCLUDE_DIR) + else() + # Specified headers not found. + set(${COMPONENT}_FOUND FALSE) + if (SUITESPARSE_FIND_${COMPONENT}_REQUIRED) + suitesparse_report_not_found( + "Did not find ${COMPONENT} header (required SuiteSparse component).") + else() + message(STATUS "Did not find ${COMPONENT} header (optional " + "SuiteSparse component).") + endif() + endif() + endif() + + if (SUITESPARSE_FIND_${COMPONENT}_LIBRARIES) + find_library(${COMPONENT}_LIBRARY + NAMES ${SUITESPARSE_FIND_${COMPONENT}_LIBRARIES} + HINTS ${SUITESPARSE_LIBRARY_DIR_HINTS} + PATHS ${SUITESPARSE_CHECK_LIBRARY_DIRS} + PATH_SUFFIXES ${SUITESPARSE_CHECK_PATH_SUFFIXES}) + if (${COMPONENT}_LIBRARY) + message(STATUS "Found ${COMPONENT} library: ${${COMPONENT}_LIBRARY}") + mark_as_advanced(${COMPONENT}_LIBRARY) + else () + # Specified libraries not found. + set(${COMPONENT}_FOUND FALSE) + if (SUITESPARSE_FIND_${COMPONENT}_REQUIRED) + suitesparse_report_not_found( + "Did not find ${COMPONENT} library (required SuiteSparse component).") + else() + message(STATUS "Did not find ${COMPONENT} library (optional SuiteSparse " + "dependency)") + endif() + endif() + endif() +endmacro() + +# Given the number of components of SuiteSparse, and to ensure that the +# automatic failure message generated by FindPackageHandleStandardArgs() +# when not all required components are found is helpful, we maintain a list +# of all variables that must be defined for SuiteSparse to be considered found. +unset(SUITESPARSE_FOUND_REQUIRED_VARS) + +# BLAS. +find_package(BLAS QUIET) +if (NOT BLAS_FOUND) + suitesparse_report_not_found( + "Did not find BLAS library (required for SuiteSparse).") +endif (NOT BLAS_FOUND) +list(APPEND SUITESPARSE_FOUND_REQUIRED_VARS BLAS_FOUND) + +# LAPACK. +find_package(LAPACK QUIET) +if (NOT LAPACK_FOUND) + suitesparse_report_not_found( + "Did not find LAPACK library (required for SuiteSparse).") +endif (NOT LAPACK_FOUND) +list(APPEND SUITESPARSE_FOUND_REQUIRED_VARS LAPACK_FOUND) + +suitesparse_find_component(AMD REQUIRED FILES amd.h LIBRARIES amd) +suitesparse_find_component(CAMD REQUIRED FILES camd.h LIBRARIES camd) +suitesparse_find_component(COLAMD REQUIRED FILES colamd.h LIBRARIES colamd) +suitesparse_find_component(CCOLAMD REQUIRED FILES ccolamd.h LIBRARIES ccolamd) +suitesparse_find_component(CHOLMOD REQUIRED FILES cholmod.h LIBRARIES cholmod) +suitesparse_find_component( + SUITESPARSEQR REQUIRED FILES SuiteSparseQR.hpp LIBRARIES spqr) +if (SUITESPARSEQR_FOUND) + # SuiteSparseQR may be compiled with Intel Threading Building Blocks, + # we assume that if TBB is installed, SuiteSparseQR was compiled with + # support for it, this will do no harm if it wasn't. + suitesparse_find_component(TBB LIBRARIES tbb) + if (TBB_FOUND) + message(STATUS "Found Intel Thread Building Blocks (TBB) library: " + "${TBB_LIBRARY}, assuming SuiteSparseQR was compiled with TBB.") + suitesparse_find_component(TBB_MALLOC LIBRARIES tbbmalloc) + if (TBB_MALLOC_FOUND) + message(STATUS "Found Intel Thread Building Blocks (TBB) Malloc library: " + "${TBB_MALLOC_LIBRARY}") + # Add the TBB libraries to the SuiteSparseQR libraries (the only + # libraries to optionally depend on TBB). + list(APPEND SUITESPARSEQR_LIBRARY ${TBB_LIBRARY} ${TBB_MALLOC_LIBRARY}) + else() + message(STATUS "Did not find Intel Thread Building Blocks (TBB) Malloc " + "Library, discarding TBB as a dependency.") + endif() + else() + message(STATUS "Did not find Intel TBB library, assuming SuiteSparseQR was " + "not compiled with TBB.") + endif() +endif(SUITESPARSEQR_FOUND) + +# UFconfig / SuiteSparse_config. +# +# If SuiteSparse version is >= 4 then SuiteSparse_config is required. +# For SuiteSparse 3, UFconfig.h is required. +suitesparse_find_component( + SUITESPARSE_CONFIG FILES SuiteSparse_config.h LIBRARIES suitesparseconfig) + +if (SUITESPARSE_CONFIG_FOUND) + # SuiteSparse_config (SuiteSparse version >= 4) requires librt library for + # timing by default when compiled on Linux or Unix, but not on OSX (which + # does not have librt). + if (CMAKE_SYSTEM_NAME MATCHES "Linux" OR UNIX AND NOT APPLE) + suitesparse_find_component(LIBRT LIBRARIES rt) + if (LIBRT_FOUND) + message(STATUS "Adding librt: ${LIBRT_LIBRARY} to " + "SuiteSparse_config libraries (required on Linux & Unix [not OSX] if " + "SuiteSparse is compiled with timing).") + list(APPEND SUITESPARSE_CONFIG_LIBRARY ${LIBRT_LIBRARY}) + else() + message(STATUS "Could not find librt, but found SuiteSparse_config, " + "assuming that SuiteSparse was compiled without timing.") + endif () + endif (CMAKE_SYSTEM_NAME MATCHES "Linux" OR UNIX AND NOT APPLE) +else() + # Failed to find SuiteSparse_config (>= v4 installs), instead look for + # UFconfig header which should be present in < v4 installs. + suitesparse_find_component(UFCONFIG FILES UFconfig.h) +endif () + +if (NOT SUITESPARSE_CONFIG_FOUND AND + NOT UFCONFIG_FOUND) + suitesparse_report_not_found( + "Failed to find either: SuiteSparse_config header & library (should be " + "present in all SuiteSparse >= v4 installs), or UFconfig header (should " + "be present in all SuiteSparse < v4 installs).") +endif() + +# Extract the SuiteSparse version from the appropriate header (UFconfig.h for +# <= v3, SuiteSparse_config.h for >= v4). +list(APPEND SUITESPARSE_FOUND_REQUIRED_VARS SUITESPARSE_VERSION) + +if (UFCONFIG_FOUND) + # SuiteSparse version <= 3. + set(SUITESPARSE_VERSION_FILE ${UFCONFIG_INCLUDE_DIR}/UFconfig.h) + if (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) + suitesparse_report_not_found( + "Could not find file: ${SUITESPARSE_VERSION_FILE} containing version " + "information for <= v3 SuiteSparse installs, but UFconfig was found " + "(only present in <= v3 installs).") + else (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) + file(READ ${SUITESPARSE_VERSION_FILE} UFCONFIG_CONTENTS) + + string(REGEX MATCH "#define SUITESPARSE_MAIN_VERSION [0-9]+" + SUITESPARSE_MAIN_VERSION "${UFCONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_MAIN_VERSION ([0-9]+)" "\\1" + SUITESPARSE_MAIN_VERSION "${SUITESPARSE_MAIN_VERSION}") + + string(REGEX MATCH "#define SUITESPARSE_SUB_VERSION [0-9]+" + SUITESPARSE_SUB_VERSION "${UFCONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_SUB_VERSION ([0-9]+)" "\\1" + SUITESPARSE_SUB_VERSION "${SUITESPARSE_SUB_VERSION}") + + string(REGEX MATCH "#define SUITESPARSE_SUBSUB_VERSION [0-9]+" + SUITESPARSE_SUBSUB_VERSION "${UFCONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_SUBSUB_VERSION ([0-9]+)" "\\1" + SUITESPARSE_SUBSUB_VERSION "${SUITESPARSE_SUBSUB_VERSION}") + + # This is on a single line s/t CMake does not interpret it as a list of + # elements and insert ';' separators which would result in 4.;2.;1 nonsense. + set(SUITESPARSE_VERSION + "${SUITESPARSE_MAIN_VERSION}.${SUITESPARSE_SUB_VERSION}.${SUITESPARSE_SUBSUB_VERSION}") + endif (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) +endif (UFCONFIG_FOUND) + +if (SUITESPARSE_CONFIG_FOUND) + # SuiteSparse version >= 4. + set(SUITESPARSE_VERSION_FILE + ${SUITESPARSE_CONFIG_INCLUDE_DIR}/SuiteSparse_config.h) + if (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) + suitesparse_report_not_found( + "Could not find file: ${SUITESPARSE_VERSION_FILE} containing version " + "information for >= v4 SuiteSparse installs, but SuiteSparse_config was " + "found (only present in >= v4 installs).") + else (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) + file(READ ${SUITESPARSE_VERSION_FILE} SUITESPARSE_CONFIG_CONTENTS) + + string(REGEX MATCH "#define SUITESPARSE_MAIN_VERSION [0-9]+" + SUITESPARSE_MAIN_VERSION "${SUITESPARSE_CONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_MAIN_VERSION ([0-9]+)" "\\1" + SUITESPARSE_MAIN_VERSION "${SUITESPARSE_MAIN_VERSION}") + + string(REGEX MATCH "#define SUITESPARSE_SUB_VERSION [0-9]+" + SUITESPARSE_SUB_VERSION "${SUITESPARSE_CONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_SUB_VERSION ([0-9]+)" "\\1" + SUITESPARSE_SUB_VERSION "${SUITESPARSE_SUB_VERSION}") + + string(REGEX MATCH "#define SUITESPARSE_SUBSUB_VERSION [0-9]+" + SUITESPARSE_SUBSUB_VERSION "${SUITESPARSE_CONFIG_CONTENTS}") + string(REGEX REPLACE "#define SUITESPARSE_SUBSUB_VERSION ([0-9]+)" "\\1" + SUITESPARSE_SUBSUB_VERSION "${SUITESPARSE_SUBSUB_VERSION}") + + # This is on a single line s/t CMake does not interpret it as a list of + # elements and insert ';' separators which would result in 4.;2.;1 nonsense. + set(SUITESPARSE_VERSION + "${SUITESPARSE_MAIN_VERSION}.${SUITESPARSE_SUB_VERSION}.${SUITESPARSE_SUBSUB_VERSION}") + endif (NOT EXISTS ${SUITESPARSE_VERSION_FILE}) +endif (SUITESPARSE_CONFIG_FOUND) + +# METIS (Optional dependency). +suitesparse_find_component(METIS LIBRARIES metis) + +# Only mark SuiteSparse as found if all required components and dependencies +# have been found. +set(SUITESPARSE_FOUND TRUE) +foreach(REQUIRED_VAR ${SUITESPARSE_FOUND_REQUIRED_VARS}) + if (NOT ${REQUIRED_VAR}) + set(SUITESPARSE_FOUND FALSE) + endif (NOT ${REQUIRED_VAR}) +endforeach(REQUIRED_VAR ${SUITESPARSE_FOUND_REQUIRED_VARS}) + +if (SUITESPARSE_FOUND) + list(APPEND SUITESPARSE_INCLUDE_DIRS + ${AMD_INCLUDE_DIR} + ${CAMD_INCLUDE_DIR} + ${COLAMD_INCLUDE_DIR} + ${CCOLAMD_INCLUDE_DIR} + ${CHOLMOD_INCLUDE_DIR} + ${SUITESPARSEQR_INCLUDE_DIR}) + # Handle config separately, as otherwise at least one of them will be set + # to NOTFOUND which would cause any check on SUITESPARSE_INCLUDE_DIRS to fail. + if (SUITESPARSE_CONFIG_FOUND) + list(APPEND SUITESPARSE_INCLUDE_DIRS + ${SUITESPARSE_CONFIG_INCLUDE_DIR}) + endif (SUITESPARSE_CONFIG_FOUND) + if (UFCONFIG_FOUND) + list(APPEND SUITESPARSE_INCLUDE_DIRS + ${UFCONFIG_INCLUDE_DIR}) + endif (UFCONFIG_FOUND) + # As SuiteSparse includes are often all in the same directory, remove any + # repetitions. + list(REMOVE_DUPLICATES SUITESPARSE_INCLUDE_DIRS) + + # Important: The ordering of these libraries is *NOT* arbitrary, as these + # could potentially be static libraries their link ordering is important. + list(APPEND SUITESPARSE_LIBRARIES + ${SUITESPARSEQR_LIBRARY} + ${CHOLMOD_LIBRARY} + ${CCOLAMD_LIBRARY} + ${CAMD_LIBRARY} + ${COLAMD_LIBRARY} + ${AMD_LIBRARY} + ${LAPACK_LIBRARIES} + ${BLAS_LIBRARIES}) + if (SUITESPARSE_CONFIG_FOUND) + list(APPEND SUITESPARSE_LIBRARIES + ${SUITESPARSE_CONFIG_LIBRARY}) + endif (SUITESPARSE_CONFIG_FOUND) + if (METIS_FOUND) + list(APPEND SUITESPARSE_LIBRARIES + ${METIS_LIBRARY}) + endif (METIS_FOUND) +endif() + +# Determine if we are running on Ubuntu with the package install of SuiteSparse +# which is broken and does not support linking a shared library. +set(SUITESPARSE_IS_BROKEN_SHARED_LINKING_UBUNTU_SYSTEM_VERSION FALSE) +if (CMAKE_SYSTEM_NAME MATCHES "Linux" AND + SUITESPARSE_VERSION VERSION_EQUAL 3.4.0) + find_program(LSB_RELEASE_EXECUTABLE lsb_release) + if (LSB_RELEASE_EXECUTABLE) + # Any even moderately recent Ubuntu release (likely to be affected by + # this bug) should have lsb_release, if it isn't present we are likely + # on a different Linux distribution (should be fine). + execute_process(COMMAND ${LSB_RELEASE_EXECUTABLE} -si + OUTPUT_VARIABLE LSB_DISTRIBUTOR_ID + OUTPUT_STRIP_TRAILING_WHITESPACE) + + if (LSB_DISTRIBUTOR_ID MATCHES "Ubuntu" AND + SUITESPARSE_LIBRARIES MATCHES "/usr/lib/libamd") + # We are on Ubuntu, and the SuiteSparse version matches the broken + # system install version and is a system install. + set(SUITESPARSE_IS_BROKEN_SHARED_LINKING_UBUNTU_SYSTEM_VERSION TRUE) + message(STATUS "Found system install of SuiteSparse " + "${SUITESPARSE_VERSION} running on Ubuntu, which has a known bug " + "preventing linking of shared libraries (static linking unaffected).") + endif (LSB_DISTRIBUTOR_ID MATCHES "Ubuntu" AND + SUITESPARSE_LIBRARIES MATCHES "/usr/lib/libamd") + endif (LSB_RELEASE_EXECUTABLE) +endif (CMAKE_SYSTEM_NAME MATCHES "Linux" AND + SUITESPARSE_VERSION VERSION_EQUAL 3.4.0) + +suitesparse_reset_find_library_prefix() + +# Handle REQUIRED and QUIET arguments to FIND_PACKAGE +include(FindPackageHandleStandardArgs) +if (SUITESPARSE_FOUND) + find_package_handle_standard_args(SuiteSparse + REQUIRED_VARS ${SUITESPARSE_FOUND_REQUIRED_VARS} + VERSION_VAR SUITESPARSE_VERSION + FAIL_MESSAGE "Failed to find some/all required components of SuiteSparse.") +else (SUITESPARSE_FOUND) + # Do not pass VERSION_VAR to FindPackageHandleStandardArgs() if we failed to + # find SuiteSparse to avoid a confusing autogenerated failure message + # that states 'not found (missing: FOO) (found version: x.y.z)'. + find_package_handle_standard_args(SuiteSparse + REQUIRED_VARS ${SUITESPARSE_FOUND_REQUIRED_VARS} + FAIL_MESSAGE "Failed to find some/all required components of SuiteSparse.") +endif (SUITESPARSE_FOUND) diff --git a/cmake/FindUnorderedMap.cmake b/cmake/FindUnorderedMap.cmake new file mode 100644 index 0000000..6ba07fd --- /dev/null +++ b/cmake/FindUnorderedMap.cmake @@ -0,0 +1,94 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# FindUnorderedMap.cmake - Find unordered_map header and namespace. +# +# This module defines the following variables: +# +# UNORDERED_MAP_FOUND: TRUE if unordered_map is found. +# HAVE_UNORDERED_MAP_IN_STD_NAMESPACE: Use & std. +# HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE: Use & std::tr1. +# HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE: & std::tr1. +macro(FIND_UNORDERED_MAP) + # To support CXX11 option, clear the results of all check_xxx() functions + # s/t we always perform the checks each time, otherwise CMake fails to + # detect that the tests should be performed again after CXX11 is toggled. + unset(HAVE_STD_UNORDERED_MAP_HEADER CACHE) + unset(HAVE_UNORDERED_MAP_IN_STD_NAMESPACE CACHE) + unset(HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE CACHE) + unset(HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE CACHE) + + set(UNORDERED_MAP_FOUND FALSE) + include(CheckIncludeFileCXX) + check_include_file_cxx(unordered_map HAVE_STD_UNORDERED_MAP_HEADER) + if (HAVE_STD_UNORDERED_MAP_HEADER) + # Finding the unordered_map header doesn't mean that unordered_map + # is in std namespace. + # + # In particular, MSVC 2008 has unordered_map declared in std::tr1. + # In order to support this, we do an extra check to see which + # namespace should be used. + include(CheckCXXSourceCompiles) + check_cxx_source_compiles("#include + int main() { + std::unordered_map map; + return 0; + }" + HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + if (HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + set(UNORDERED_MAP_FOUND TRUE) + message("-- Found unordered_map/set in std namespace.") + else (HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + check_cxx_source_compiles("#include + int main() { + std::tr1::unordered_map map; + return 0; + }" + HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + if (HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + set(UNORDERED_MAP_FOUND TRUE) + message("-- Found unordered_map/set in std::tr1 namespace.") + else (HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + message("-- Found but cannot find either " + "std::unordered_map or std::tr1::unordered_map.") + endif (HAVE_UNORDERED_MAP_IN_TR1_NAMESPACE) + endif (HAVE_UNORDERED_MAP_IN_STD_NAMESPACE) + else (HAVE_STD_UNORDERED_MAP_HEADER) + check_include_file_cxx("tr1/unordered_map" + HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) + if (HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) + set(UNORDERED_MAP_FOUND TRUE) + message("-- Found tr1/unordered_map/set in std::tr1 namespace.") + else (HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) + message("-- Unable to find or .") + endif (HAVE_TR1_UNORDERED_MAP_IN_TR1_NAMESPACE) + endif (HAVE_STD_UNORDERED_MAP_HEADER) +endmacro(FIND_UNORDERED_MAP) diff --git a/cmake/ReadCeresVersionFromSource.cmake b/cmake/ReadCeresVersionFromSource.cmake new file mode 100644 index 0000000..2859744 --- /dev/null +++ b/cmake/ReadCeresVersionFromSource.cmake @@ -0,0 +1,81 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) +# + +# Extract Ceres version from /include/ceres/version.h +# so that we only have a single definition of the Ceres version, not two +# one in the source and one in the CMakeLists.txt. +macro(read_ceres_version_from_source CERES_SOURCE_ROOT) + set(CERES_VERSION_FILE ${CERES_SOURCE_ROOT}/include/ceres/version.h) + if (NOT EXISTS ${CERES_VERSION_FILE}) + message(FATAL_ERROR "Cannot find Ceres version.h file in specified " + "Ceres source directory: ${CERES_SOURCE_ROOT}, it is not here: " + "${CERES_VERSION_FILE}") + endif() + + file(READ ${CERES_VERSION_FILE} CERES_VERSION_FILE_CONTENTS) + + string(REGEX MATCH "#define CERES_VERSION_MAJOR [0-9]+" + CERES_VERSION_MAJOR "${CERES_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CERES_VERSION_MAJOR ([0-9]+)" "\\1" + CERES_VERSION_MAJOR "${CERES_VERSION_MAJOR}") + # NOTE: if (VAR) is FALSE if VAR is numeric and <= 0, as such we cannot use + # it for testing version numbers, which might well be zero, at least + # for the patch version, hence check for empty string explicitly. + if ("${CERES_VERSION_MAJOR}" STREQUAL "") + message(FATAL_ERROR "Failed to extract Ceres major version from " + "${CERES_VERSION_FILE}") + endif() + + string(REGEX MATCH "#define CERES_VERSION_MINOR [0-9]+" + CERES_VERSION_MINOR "${CERES_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CERES_VERSION_MINOR ([0-9]+)" "\\1" + CERES_VERSION_MINOR "${CERES_VERSION_MINOR}") + if ("${CERES_VERSION_MINOR}" STREQUAL "") + message(FATAL_ERROR "Failed to extract Ceres minor version from " + "${CERES_VERSION_FILE}") + endif() + + string(REGEX MATCH "#define CERES_VERSION_REVISION [0-9]+" + CERES_VERSION_PATCH "${CERES_VERSION_FILE_CONTENTS}") + string(REGEX REPLACE "#define CERES_VERSION_REVISION ([0-9]+)" "\\1" + CERES_VERSION_PATCH "${CERES_VERSION_PATCH}") + if ("${CERES_VERSION_PATCH}" STREQUAL "") + message(FATAL_ERROR "Failed to extract Ceres patch version from " + "${CERES_VERSION_FILE}") + endif() + + # This is on a single line s/t CMake does not interpret it as a list of + # elements and insert ';' separators which would result in 3.;2.;0 nonsense. + set(CERES_VERSION "${CERES_VERSION_MAJOR}.${CERES_VERSION_MINOR}.${CERES_VERSION_PATCH}") + + message(STATUS "Detected Ceres version: ${CERES_VERSION} from " + "${CERES_VERSION_FILE}") +endmacro() diff --git a/cmake/UpdateCacheVariable.cmake b/cmake/UpdateCacheVariable.cmake new file mode 100644 index 0000000..5995a87 --- /dev/null +++ b/cmake/UpdateCacheVariable.cmake @@ -0,0 +1,43 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: alexs.mac@gmail.com (Alex Stewart) + +# By default, there is no easy way in CMake to set the value of a cache +# variable without reinitialising it, which involves resetting its +# associated help string. This is particularly annoying for CMake options +# where they need to programmatically updated. +# +# This function automates this process by getting the current help string +# for the cache variable to update, then reinitialising it with the new +# value, but with the original help string. +function(UPDATE_CACHE_VARIABLE VAR_NAME VALUE) + get_property(HELP_STRING CACHE ${VAR_NAME} PROPERTY HELPSTRING) + get_property(VAR_TYPE CACHE ${VAR_NAME} PROPERTY TYPE) + set(${VAR_NAME} ${VALUE} CACHE ${VAR_TYPE} "${HELP_STRING}" FORCE) +endfunction() diff --git a/cmake/config.h.in b/cmake/config.h.in new file mode 100644 index 0000000..0bf0f8f --- /dev/null +++ b/cmake/config.h.in @@ -0,0 +1,96 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: alexs.mac@gmail.com (Alex Stewart) + +// Configuration options for Ceres. +// +// Do not edit this file, it was automatically configured by CMake when +// Ceres was compiled with the relevant configuration for the machine +// on which Ceres was compiled. +// +// Ceres Developers: All options should have the same name as their mapped +// CMake options, in the preconfigured version of this file +// all options should be enclosed in '@'. + +#ifndef CERES_PUBLIC_INTERNAL_CONFIG_H_ +#define CERES_PUBLIC_INTERNAL_CONFIG_H_ + +// If defined, use the LGPL code in Eigen. +@CERES_USE_EIGEN_SPARSE@ + +// If defined, Ceres was compiled without LAPACK. +@CERES_NO_LAPACK@ + +// If defined, Ceres was compiled without SuiteSparse. +@CERES_NO_SUITESPARSE@ + +// If defined, Ceres was compiled without CXSparse. +@CERES_NO_CXSPARSE@ + +// If defined, Ceres was compiled without Schur specializations. +@CERES_RESTRICT_SCHUR_SPECIALIZATION@ + +// If defined, Ceres was compiled to use Eigen instead of hardcoded BLAS +// routines. +@CERES_NO_CUSTOM_BLAS@ + +// If defined, Ceres was compiled with C++11. +@CERES_USE_CXX11@ + +// If defined, Ceres was compiled without multithreading support. +@CERES_NO_THREADS@ +// If defined Ceres was compiled with OpenMP multithreading support. +@CERES_USE_OPENMP@ +// Additionally defined on *nix if Ceres was compiled with OpenMP support, +// as in this case pthreads is also required. +@CERES_HAVE_PTHREAD@ +@CERES_HAVE_RWLOCK@ + +// Which version of unordered map was used when Ceres was compiled. Exactly +// one of these will be defined for any given build. +@CERES_STD_UNORDERED_MAP@ +@CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE@ +@CERES_TR1_UNORDERED_MAP@ +@CERES_NO_UNORDERED_MAP@ + +// If defined, the memory header is in , otherwise . +@CERES_TR1_MEMORY_HEADER@ + +// If defined shared_ptr is in std::tr1 namespace, otherwise std. +@CERES_TR1_SHARED_PTR@ + +// If defined, Ceres was built as a shared library. +@CERES_USING_SHARED_LIBRARY@ + +// If defined, Ceres was compiled with a version MSVC >= 2005 which +// deprecated the standard POSIX names for bessel functions, replacing them +// with underscore prefixed versions (e.g. j0() -> _j0()). +@CERES_MSVC_USE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS@ + +#endif // CERES_PUBLIC_INTERNAL_CONFIG_H_ diff --git a/cmake/iOS.cmake b/cmake/iOS.cmake new file mode 100644 index 0000000..8d34d61 --- /dev/null +++ b/cmake/iOS.cmake @@ -0,0 +1,327 @@ +# This file is part of the ios-cmake project. It was retrieved from +# https://github.com/cristeab/ios-cmake.git, which is a fork of +# https://code.google.com/p/ios-cmake/. Which in turn is based off of +# the Platform/Darwin.cmake and Platform/UnixPaths.cmake files which +# are included with CMake 2.8.4 +# +# The ios-cmake project is licensed under the new BSD license. +# +# Copyright (c) 2014, Bogdan Cristea and LTE Engineering Software, +# Kitware, Inc., Insight Software Consortium. All rights reserved. + +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: + +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# 3. Neither the name of the copyright holder nor the names of its +# contributors may be used to endorse or promote products derived from +# this software without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# This file is based off of the Platform/Darwin.cmake and +# Platform/UnixPaths.cmake files which are included with CMake 2.8.4 +# It has been altered for iOS development. +# +# Updated by Alex Stewart (alexs.mac@gmail.com). + +# The following variables control the behaviour of this toolchain: +# +# IOS_PLATFORM: OS (default) or SIMULATOR or SIMULATOR64 +# OS = Build for iPhoneOS. +# SIMULATOR = Build for x86 i386 iPhone Simulator. +# SIMULATOR64 = Build for x86 x86_64 iPhone Simulator. +# CMAKE_OSX_SYSROOT: Path to the iOS SDK to use. By default this is +# automatically determined from IOS_PLATFORM and xcodebuild, but +# can also be manually specified (although this should not be required). +# CMAKE_IOS_DEVELOPER_ROOT: Path to the Developer directory for the iOS platform +# being compiled for. By default this is automatically determined from +# CMAKE_OSX_SYSROOT, but can also be manually specified (although this should +# not be required). +# +# This toolchain defines the following variables for use externally: +# +# XCODE_VERSION: Version number (not including Build version) of Xcode detected. +# IOS_SDK_VERSION: Version of iOS SDK being used. +# CMAKE_OSX_ARCHITECTURES: Architectures being compiled for (generated from +# IOS_PLATFORM). +# +# This toolchain defines the following macros for use externally: +# +# set_xcode_property (TARGET XCODE_PROPERTY XCODE_VALUE) +# A convenience macro for setting xcode specific properties on targets +# example: set_xcode_property (myioslib IPHONEOS_DEPLOYMENT_TARGET "3.1"). +# +# find_host_package (PROGRAM ARGS) +# A macro used to find executable programs on the host system, not within the +# iOS environment. Thanks to the android-cmake project for providing the +# command. + +# Get the Xcode version being used. +execute_process(COMMAND xcodebuild -version + OUTPUT_VARIABLE XCODE_VERSION + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) +string(REGEX MATCH "Xcode [0-9\\.]+" XCODE_VERSION "${XCODE_VERSION}") +string(REGEX REPLACE "Xcode ([0-9\\.]+)" "\\1" XCODE_VERSION "${XCODE_VERSION}") +message(STATUS "Building with Xcode version: ${XCODE_VERSION}") + +# Default to building for iPhoneOS if not specified otherwise, and we cannot +# determine the platform from the CMAKE_OSX_ARCHITECTURES variable. The use +# of CMAKE_OSX_ARCHITECTURES is such that try_compile() projects can correctly +# determine the value of IOS_PLATFORM from the root project, as +# CMAKE_OSX_ARCHITECTURES is propagated to them by CMake. +if (NOT DEFINED IOS_PLATFORM) + if (CMAKE_OSX_ARCHITECTURES) + if (CMAKE_OSX_ARCHITECTURES MATCHES ".*arm.*") + set(IOS_PLATFORM "OS") + elseif (CMAKE_OSX_ARCHITECTURES MATCHES "i386") + set(IOS_PLATFORM "SIMULATOR") + elseif (CMAKE_OSX_ARCHITECTURES MATCHES "x86_64") + set(IOS_PLATFORM "SIMULATOR64") + endif() + endif() + if (NOT IOS_PLATFORM) + set(IOS_PLATFORM "OS") + endif() +endif() +set(IOS_PLATFORM ${IOS_PLATFORM} CACHE STRING + "Type of iOS platform for which to build.") + +# Determine the platform name and architectures for use in xcodebuild commands +# from the specified IOS_PLATFORM name. +if (IOS_PLATFORM STREQUAL "OS") + set(XCODE_IOS_PLATFORM iphoneos) + set(IOS_ARCH armv7 armv7s arm64) +elseif (IOS_PLATFORM STREQUAL "SIMULATOR") + set(XCODE_IOS_PLATFORM iphonesimulator) + set(IOS_ARCH i386) +elseif(IOS_PLATFORM STREQUAL "SIMULATOR64") + set(XCODE_IOS_PLATFORM iphonesimulator) + set(IOS_ARCH x86_64) +else() + message(FATAL_ERROR "Invalid IOS_PLATFORM: ${IOS_PLATFORM}") +endif() +message(STATUS "Configuring iOS build for platform: ${IOS_PLATFORM}, " + "architecture(s): ${IOS_ARCH}") + +# If user did not specify the SDK root to use, then query xcodebuild for it. +if (NOT CMAKE_OSX_SYSROOT) + execute_process(COMMAND xcodebuild -version -sdk ${XCODE_IOS_PLATFORM} Path + OUTPUT_VARIABLE CMAKE_OSX_SYSROOT + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) + message(STATUS "Using SDK: ${CMAKE_OSX_SYSROOT} for platform: ${IOS_PLATFORM}") +endif() +if (NOT EXISTS ${CMAKE_OSX_SYSROOT}) + message(FATAL_ERROR "Invalid CMAKE_OSX_SYSROOT: ${CMAKE_OSX_SYSROOT} " + "does not exist.") +endif() +# Get the SDK version information. +execute_process(COMMAND xcodebuild -sdk ${CMAKE_OSX_SYSROOT} -version SDKVersion + OUTPUT_VARIABLE IOS_SDK_VERSION + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) + +# Find the Developer root for the specific iOS platform being compiled for +# from CMAKE_OSX_SYSROOT. Should be ../../ from SDK specified in +# CMAKE_OSX_SYSROOT. There does not appear to be a direct way to obtain +# this information from xcrun or xcodebuild. +if (NOT CMAKE_IOS_DEVELOPER_ROOT) + get_filename_component(IOS_PLATFORM_SDK_DIR ${CMAKE_OSX_SYSROOT} PATH) + get_filename_component(CMAKE_IOS_DEVELOPER_ROOT ${IOS_PLATFORM_SDK_DIR} PATH) +endif() +if (NOT EXISTS ${CMAKE_IOS_DEVELOPER_ROOT}) + message(FATAL_ERROR "Invalid CMAKE_IOS_DEVELOPER_ROOT: " + "${CMAKE_IOS_DEVELOPER_ROOT} does not exist.") +endif() + +# Find the C & C++ compilers for the specified SDK. +if (NOT CMAKE_C_COMPILER) + execute_process(COMMAND xcrun -sdk ${CMAKE_OSX_SYSROOT} -find clang + OUTPUT_VARIABLE CMAKE_C_COMPILER + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) + message(STATUS "Using C compiler: ${CMAKE_C_COMPILER}") +endif() +if (NOT CMAKE_CXX_COMPILER) + execute_process(COMMAND xcrun -sdk ${CMAKE_OSX_SYSROOT} -find clang++ + OUTPUT_VARIABLE CMAKE_CXX_COMPILER + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) + message(STATUS "Using CXX compiler: ${CMAKE_CXX_COMPILER}") +endif() + +# Find (Apple's) libtool. +execute_process(COMMAND xcrun -sdk ${CMAKE_OSX_SYSROOT} -find libtool + OUTPUT_VARIABLE IOS_LIBTOOL + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) +message(STATUS "Using libtool: ${IOS_LIBTOOL}") +# Configure libtool to be used instead of ar + ranlib to build static libraries. +# This is required on Xcode 7+, but should also work on previous versions of +# Xcode. +set(CMAKE_C_CREATE_STATIC_LIBRARY + "${IOS_LIBTOOL} -static -o ") +set(CMAKE_CXX_CREATE_STATIC_LIBRARY + "${IOS_LIBTOOL} -static -o ") + +# Get the version of Darwin (OS X) of the host. +execute_process(COMMAND uname -r + OUTPUT_VARIABLE CMAKE_HOST_SYSTEM_VERSION + ERROR_QUIET + OUTPUT_STRIP_TRAILING_WHITESPACE) + +# Standard settings. +set(CMAKE_SYSTEM_NAME Darwin) +set(CMAKE_SYSTEM_VERSION ${IOS_SDK_VERSION}) +set(UNIX TRUE) +set(APPLE TRUE) +set(IOS TRUE) +# Force unset of OS X-specific deployment target (otherwise autopopulated), +# required as of cmake 2.8.10. +set(CMAKE_OSX_DEPLOYMENT_TARGET "" CACHE STRING + "Must be empty for iOS builds." FORCE) +# Set the architectures for which to build. +set(CMAKE_OSX_ARCHITECTURES ${IOS_ARCH} CACHE STRING "Build architecture for iOS") + +# Skip the platform compiler checks for cross compiling. +set(CMAKE_CXX_COMPILER_FORCED TRUE) +set(CMAKE_CXX_COMPILER_WORKS TRUE) +set(CMAKE_C_COMPILER_FORCED TRUE) +set(CMAKE_C_COMPILER_WORKS TRUE) + +# All iOS/Darwin specific settings - some may be redundant. +set(CMAKE_SHARED_LIBRARY_PREFIX "lib") +set(CMAKE_SHARED_LIBRARY_SUFFIX ".dylib") +set(CMAKE_SHARED_MODULE_PREFIX "lib") +set(CMAKE_SHARED_MODULE_SUFFIX ".so") +set(CMAKE_MODULE_EXISTS 1) +set(CMAKE_DL_LIBS "") + +set(CMAKE_C_OSX_COMPATIBILITY_VERSION_FLAG "-compatibility_version ") +set(CMAKE_C_OSX_CURRENT_VERSION_FLAG "-current_version ") +set(CMAKE_CXX_OSX_COMPATIBILITY_VERSION_FLAG "${CMAKE_C_OSX_COMPATIBILITY_VERSION_FLAG}") +set(CMAKE_CXX_OSX_CURRENT_VERSION_FLAG "${CMAKE_C_OSX_CURRENT_VERSION_FLAG}") + +# Specify minimum version of deployment target. +# Unless specified, the latest SDK version is used by default. +set(IOS_DEPLOYMENT_TARGET "${IOS_SDK_VERSION}" + CACHE STRING "Minimum iOS version to build for." ) +message(STATUS "Building for minimum iOS version: ${IOS_DEPLOYMENT_TARGET}" + " (SDK version: ${IOS_SDK_VERSION})") + +# Note that only Xcode 7+ supports the newer more specific: +# -m${XCODE_IOS_PLATFORM}-version-min flags, older versions of Xcode use: +# -m(ios/ios-simulator)-version-min instead. +if (XCODE_VERSION VERSION_LESS 7.0) + if (IOS_PLATFORM STREQUAL "OS") + set(XCODE_IOS_PLATFORM_VERSION_FLAGS + "-mios-version-min=${IOS_DEPLOYMENT_TARGET}") + else() + # SIMULATOR or SIMULATOR64 both use -mios-simulator-version-min. + set(XCODE_IOS_PLATFORM_VERSION_FLAGS + "-mios-simulator-version-min=${IOS_DEPLOYMENT_TARGET}") + endif() +else() + # Xcode 7.0+ uses flags we can build directly from XCODE_IOS_PLATFORM. + set(XCODE_IOS_PLATFORM_VERSION_FLAGS + "-m${XCODE_IOS_PLATFORM}-version-min=${IOS_DEPLOYMENT_TARGET}") +endif() + +set(CMAKE_C_FLAGS + "${XCODE_IOS_PLATFORM_VERSION_FLAGS} -fobjc-abi-version=2 -fobjc-arc ${CMAKE_C_FLAGS}") +# Hidden visibilty is required for C++ on iOS. +set(CMAKE_CXX_FLAGS + "${XCODE_IOS_PLATFORM_VERSION_FLAGS} -fvisibility=hidden -fvisibility-inlines-hidden -fobjc-abi-version=2 -fobjc-arc ${CMAKE_CXX_FLAGS}") +set(CMAKE_CXX_FLAGS_RELEASE "-DNDEBUG -O3 -fomit-frame-pointer -ffast-math ${CMAKE_CXX_FLAGS_RELEASE}") + +set(CMAKE_C_LINK_FLAGS "${XCODE_IOS_PLATFORM_VERSION_FLAGS} -Wl,-search_paths_first ${CMAKE_C_LINK_FLAGS}") +set(CMAKE_CXX_LINK_FLAGS "${XCODE_IOS_PLATFORM_VERSION_FLAGS} -Wl,-search_paths_first ${CMAKE_CXX_LINK_FLAGS}") + +# In order to ensure that the updated compiler flags are used in try_compile() +# tests, we have to forcibly set them in the CMake cache, not merely set them +# in the local scope. +list(APPEND VARS_TO_FORCE_IN_CACHE + CMAKE_C_FLAGS + CMAKE_CXX_FLAGS + CMAKE_CXX_RELEASE + CMAKE_C_LINK_FLAGS + CMAKE_CXX_LINK_FLAGS) +foreach(VAR_TO_FORCE ${VARS_TO_FORCE_IN_CACHE}) + set(${VAR_TO_FORCE} "${${VAR_TO_FORCE}}" CACHE STRING "" FORCE) +endforeach() + +set(CMAKE_PLATFORM_HAS_INSTALLNAME 1) +set(CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS "-dynamiclib -headerpad_max_install_names") +set(CMAKE_SHARED_MODULE_CREATE_C_FLAGS "-bundle -headerpad_max_install_names") +set(CMAKE_SHARED_MODULE_LOADER_C_FLAG "-Wl,-bundle_loader,") +set(CMAKE_SHARED_MODULE_LOADER_CXX_FLAG "-Wl,-bundle_loader,") +set(CMAKE_FIND_LIBRARY_SUFFIXES ".dylib" ".so" ".a") + +# Hack: if a new cmake (which uses CMAKE_INSTALL_NAME_TOOL) runs on an old +# build tree (where install_name_tool was hardcoded) and where +# CMAKE_INSTALL_NAME_TOOL isn't in the cache and still cmake didn't fail in +# CMakeFindBinUtils.cmake (because it isn't rerun) hardcode +# CMAKE_INSTALL_NAME_TOOL here to install_name_tool, so it behaves as it did +# before, Alex. +if (NOT DEFINED CMAKE_INSTALL_NAME_TOOL) + find_program(CMAKE_INSTALL_NAME_TOOL install_name_tool) +endif (NOT DEFINED CMAKE_INSTALL_NAME_TOOL) + +# Set the find root to the iOS developer roots and to user defined paths. +set(CMAKE_FIND_ROOT_PATH ${CMAKE_IOS_DEVELOPER_ROOT} ${CMAKE_OSX_SYSROOT} + ${CMAKE_PREFIX_PATH} CACHE string "iOS find search path root" FORCE) + +# Default to searching for frameworks first. +set(CMAKE_FIND_FRAMEWORK FIRST) + +# Set up the default search directories for frameworks. +set(CMAKE_SYSTEM_FRAMEWORK_PATH + ${CMAKE_OSX_SYSROOT}/System/Library/Frameworks + ${CMAKE_OSX_SYSROOT}/System/Library/PrivateFrameworks + ${CMAKE_OSX_SYSROOT}/Developer/Library/Frameworks) + +# Only search the specified iOS SDK, not the remainder of the host filesystem. +set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) +set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) + +# This little macro lets you set any XCode specific property. +macro(set_xcode_property TARGET XCODE_PROPERTY XCODE_VALUE) + set_property(TARGET ${TARGET} PROPERTY + XCODE_ATTRIBUTE_${XCODE_PROPERTY} ${XCODE_VALUE}) +endmacro(set_xcode_property) + +# This macro lets you find executable programs on the host system. +macro(find_host_package) + set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) + set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY NEVER) + set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE NEVER) + set(IOS FALSE) + + find_package(${ARGN}) + + set(IOS TRUE) + set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) + set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) +endmacro(find_host_package) diff --git a/cmake/uninstall.cmake.in b/cmake/uninstall.cmake.in new file mode 100644 index 0000000..06cac80 --- /dev/null +++ b/cmake/uninstall.cmake.in @@ -0,0 +1,97 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: arnaudgelas@gmail.com (Arnaud Gelas) +# alexs.mac@gmail.com (Alex Stewart) + +if (COMMAND cmake_policy) + # Ignore empty elements in LIST() commands. + cmake_policy(SET CMP0007 OLD) +endif (COMMAND cmake_policy) + +if (NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt") + message(FATAL_ERROR "Cannot find install manifest: " + "\"@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt\"") +endif (NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt") + +file(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" INSTALL_MANIFEST) +string(REGEX REPLACE "\n" ";" INSTALL_MANIFEST "${INSTALL_MANIFEST}") +list(REVERSE INSTALL_MANIFEST) + +foreach (INSTALLED_FILE ${INSTALL_MANIFEST}) + # Save the root ceres include install directory, e.g. /usr/local/include/ceres + # so that we can remove it at the end. + if (NOT CERES_INCLUDE_INSTALL_ROOT) + get_filename_component(FILE_NAME ${INSTALLED_FILE} NAME) + if (FILE_NAME STREQUAL ceres.h) + # Ensure that the directory is nested as we expect, as we are going to + # remove it, and we do not want to remove files pertaining to anyone else. + get_filename_component(PARENT_DIR ${INSTALLED_FILE} PATH) + get_filename_component(PARENT_DIR_NAME ${PARENT_DIR} NAME) + if (PARENT_DIR_NAME STREQUAL ceres AND IS_DIRECTORY ${PARENT_DIR}) + set(CERES_INCLUDE_INSTALL_ROOT ${PARENT_DIR}) + endif (PARENT_DIR_NAME STREQUAL ceres AND IS_DIRECTORY ${PARENT_DIR}) + endif (FILE_NAME STREQUAL ceres.h) + endif (NOT CERES_INCLUDE_INSTALL_ROOT) + + message(STATUS "Uninstalling \"$ENV{DESTDIR}${INSTALLED_FILE}\"") + if (EXISTS "$ENV{DESTDIR}${INSTALLED_FILE}") + execute_process(COMMAND @CMAKE_COMMAND@ + -E remove "$ENV{DESTDIR}${INSTALLED_FILE}" + OUTPUT_VARIABLE RM_OUT + RESULT_VARIABLE RM_RETVAL) + if (NOT ${RM_RETVAL} EQUAL 0) + message(FATAL_ERROR + "Problem when removing \"$ENV{DESTDIR}${INSTALLED_FILE}\"") + endif (NOT ${RM_RETVAL} EQUAL 0) + else (EXISTS "$ENV{DESTDIR}${INSTALLED_FILE}") + message(STATUS "File \"$ENV{DESTDIR}${INSTALLED_FILE}\" does not exist.") + endif (EXISTS "$ENV{DESTDIR}${INSTALLED_FILE}") +endforeach(INSTALLED_FILE) + +# Removing Ceres include install directory. +if (CERES_INCLUDE_INSTALL_ROOT AND + EXISTS ${CERES_INCLUDE_INSTALL_ROOT}) + message(STATUS "Removing Ceres include install directory: " + "\"$ENV{DESTDIR}${CERES_INCLUDE_INSTALL_ROOT}\"") + execute_process(COMMAND @CMAKE_COMMAND@ + -E remove_directory + "$ENV{DESTDIR}${CERES_INCLUDE_INSTALL_ROOT}" + OUTPUT_VARIABLE RM_OUT + RESULT_VARIABLE RM_RETVAL) + if (NOT ${RM_RETVAL} EQUAL 0) + message(FATAL_ERROR + "Failed to remove: \"$ENV{DESTDIR}${CERES_INCLUDE_INSTALL_ROOT\"") + endif (NOT ${RM_RETVAL} EQUAL 0) +else (CERES_INCLUDE_INSTALL_ROOT AND + EXISTS ${CERES_INCLUDE_INSTALL_ROOT}) + message(FATAL_ERROR "Failed to find Ceres installed include directory " + "(e.g. /usr/local/include/ceres), candidate: " + "\"$ENV{DESTDIR}${CERES_INCLUDE_INSTALL_ROOT}\"") +endif (CERES_INCLUDE_INSTALL_ROOT AND + EXISTS ${CERES_INCLUDE_INSTALL_ROOT}) diff --git a/config/ceres/internal/config.h b/config/ceres/internal/config.h new file mode 100644 index 0000000..1cf034d --- /dev/null +++ b/config/ceres/internal/config.h @@ -0,0 +1,48 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: alexs.mac@gmail.com (Alex Stewart) + +// Default (empty) configuration options for Ceres. +// +// IMPORTANT: Most users of Ceres will not use this file, when +// compiling Ceres with CMake, CMake will configure a new +// config.h with the currently selected Ceres compile +// options in /config, which will be added to +// the include path for compilation, and installed with the +// public Ceres headers. However, for some users of Ceres +// who compile without CMake (Android), this file ensures +// that Ceres will compile, with the user either specifying +// manually the Ceres compile options, or passing them +// directly through the compiler. + +#ifndef CERES_PUBLIC_INTERNAL_CONFIG_H_ +#define CERES_PUBLIC_INTERNAL_CONFIG_H_ + + +#endif // CERES_PUBLIC_INTERNAL_CONFIG_H_ diff --git a/data/2x2.foe b/data/2x2.foe new file mode 100644 index 0000000..67b1384 --- /dev/null +++ b/data/2x2.foe @@ -0,0 +1,8 @@ +2 3 +0 1 0 1 +0 0 1 1 +0.586612685392731 1.157638405566669 0.846059486257292 +-0.0582774013402734 0.0339010363051084 -0.0501593018104054 0.0745568557931712 +0.0492112815304123 -0.0307820846538285 -0.123247230948424 0.104812330861557 +0.0562633568728865 0.0152832583489560 -0.0576215592718086 -0.0139673758425540 + diff --git a/data/3x3.foe b/data/3x3.foe new file mode 100644 index 0000000..e0d6104 --- /dev/null +++ b/data/3x3.foe @@ -0,0 +1,13 @@ +3 8 +0 1 2 0 1 2 0 1 2 +0 0 0 1 1 1 2 2 2 +1.201143e-01 7.520515e-02 9.078330e-02 1.280545e-01 6.276734e-02 1.201840e-01 1.092460e-01 1.217102e-01 +-1.06290 1.81622 -0.80592 0.27489 0.13790 -0.49836 0.76669 -1.95329 1.32468 +-1.39695 1.62887 -0.27482 1.46226 -2.21903 0.82016 -0.12290 0.67906 -0.57683 +0.89899 0.27696 0.04805 -0.07191 0.00777 -0.00488 -0.80267 -0.31249 -0.03957 +-0.86612 1.66525 -1.03168 1.87671 -3.28802 1.92990 -1.22515 2.01814 -1.08079 +-0.37343 -0.23977 0.56955 -0.41741 0.05711 0.42774 -0.14881 0.02528 0.10072 +0.62783 0.27746 0.44180 -1.22190 -0.27753 -1.23532 0.54919 0.15855 0.68658 +0.46483 -1.12896 0.57926 0.22646 -0.25658 0.18881 0.57866 -1.13277 0.48707 +0.86662 0.19780 -1.06759 -1.92170 -0.10882 2.02231 1.14262 -0.09817 -1.03353 + diff --git a/data/5x5.foe b/data/5x5.foe new file mode 100644 index 0000000..0106827 --- /dev/null +++ b/data/5x5.foe @@ -0,0 +1,32 @@ +5 24 +0 1 2 3 4 0 1 2 3 4 0 1 2 3 4 0 1 2 3 4 0 1 2 3 4 +0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 + +5.472286e-02 6.425581e-02 5.031088e-02 5.989018e-02 4.424956e-02 5.119065e-02 6.743059e-02 2.339211e-02 5.973362e-02 6.281576e-02 1.495131e-02 5.693016e-02 3.189429e-02 7.672358e-02 4.524088e-02 3.681065e-02 6.383650e-02 4.347603e-02 2.264134e-02 2.561474e-02 5.886950e-02 4.114462e-02 4.893348e-02 5.834900e-02 + + -0.31071 1.04120 -0.78749 -0.47895 0.56812 -0.02713 0.12199 -0.19871 0.01017 0.08976 -0.05437 0.19638 -0.11093 -0.02853 0.00427 -0.19578 0.29112 -0.05108 -0.08012 0.02944 -0.87865 1.54098 -0.60090 -0.14424 0.05388 + 0.59362 0.07378 0.01163 0.11076 0.38838 -1.56819 -0.12448 -0.26775 -0.14495 -1.26480 1.69550 0.23647 0.50640 0.20682 1.71141 -0.93659 -0.27274 -0.40550 -0.30937 -1.27168 0.21164 0.09704 0.14615 0.14513 0.43322 + 0.84855 -1.15931 -0.04677 1.55189 -1.20232 -0.84787 0.88787 0.05491 -0.59425 0.44273 0.10771 0.15608 -0.20982 -0.40088 0.46844 0.00920 -0.34651 0.07722 1.10449 -1.00405 -0.00980 0.27614 0.32393 -1.83075 1.34408 + -1.03323 1.88111 -1.43100 0.78609 -0.25928 -0.03655 0.21945 -0.13154 -0.10918 0.11203 0.09740 -0.02567 -0.23481 0.18294 -0.07056 0.20877 -0.12025 -0.27859 0.34269 -0.10385 0.70720 -1.63594 1.39715 -0.56761 0.10165 + 0.53443 -0.08024 -0.11745 -0.03402 0.25033 -0.96043 0.15798 0.15981 0.10961 -0.24634 0.77044 -0.18866 -0.27562 0.18315 0.07681 -0.74267 0.51002 0.40930 -0.00294 -1.63639 0.40120 -0.42511 -0.15842 -0.28824 1.59764 + -0.88573 -0.33458 -0.01419 -0.01103 0.00077 0.47044 0.43260 0.04198 -0.00840 0.00150 0.57390 0.08128 0.04955 -0.00643 0.01470 0.50375 0.07196 0.02376 0.03349 0.03517 -0.67904 -0.28139 -0.05936 -0.03884 -0.02249 + -0.01311 -0.01988 0.10721 -0.08376 0.01636 -0.32442 0.98192 -1.44473 1.21759 -0.47859 0.89529 -2.36566 3.17358 -2.70415 1.10629 -0.96782 2.47203 -3.22965 2.76881 -1.14343 0.42498 -1.09401 1.42223 -1.22142 0.50653 + 0.21862 -0.20464 0.03462 -0.03753 0.01527 0.13402 -0.07069 -0.00552 -0.04434 -0.02653 0.15630 0.02185 0.04572 -0.11760 -0.06958 0.15633 -0.00898 0.00952 -0.06227 -0.12147 0.37032 0.05372 0.10450 -0.22764 -0.32445 + -0.02092 -0.35567 0.54827 0.50360 -0.95729 0.42842 0.61450 -1.06896 -0.96641 1.79327 -1.49830 -0.13333 0.96113 0.66182 -1.14234 2.35571 -0.68686 -0.72675 -0.09191 0.23092 -1.29917 0.56449 0.33405 -0.11554 0.06663 + -0.15212 -0.31661 -0.10629 -0.68078 1.64419 0.60883 0.48936 0.35629 0.85845 -2.71321 -1.02463 -0.40494 -0.33908 -0.03011 1.32162 0.87303 0.38931 0.15034 -0.46469 -0.16997 -0.30057 -0.21769 -0.03504 0.29551 -0.03051 + -0.63745 1.09815 0.07905 -1.29684 0.78552 0.31671 -0.60369 -0.31422 1.37878 -0.84617 -0.08181 0.25602 0.09426 -0.69533 0.50771 -0.26215 0.08620 0.18111 0.24247 -0.35641 0.18171 0.29815 -0.90155 0.49852 -0.00995 + -0.24394 0.32079 -0.18885 -0.43086 0.61484 0.95412 -1.08795 0.41381 1.25966 -1.62800 -1.63362 1.77016 -0.41047 -1.74982 2.02167 1.69856 -1.82451 0.27727 1.56121 -1.66173 -0.80206 0.85485 -0.10948 -0.64836 0.67266 + 0.60487 -0.01646 0.13186 0.13391 0.66691 -0.16619 0.00981 0.02774 -0.14688 -0.23655 -0.03876 0.01428 -0.05848 0.00855 0.01915 0.28643 0.01215 0.00615 0.02837 -0.27025 -0.67548 -0.06341 -0.09492 -0.01467 -0.16753 + 0.77534 -1.90839 2.47496 -2.26067 1.01011 -0.36223 0.89421 -1.24538 1.23108 -0.59609 -0.44538 1.04742 -1.25543 1.08209 -0.44929 -0.10218 0.51811 -0.92194 0.90930 -0.42024 0.18932 -0.73810 1.25011 -1.24150 0.56562 + 0.93435 -0.03480 0.04710 -0.40291 -0.92490 -0.66962 0.13901 0.00497 0.31148 0.63533 0.30957 -0.23678 -0.07453 -0.24971 0.25021 0.68393 0.03453 -0.00104 -0.20619 -0.21134 -1.23377 0.08326 0.02804 0.53578 0.24696 + -0.31333 -0.06452 -0.14492 0.32917 0.18505 0.37680 -0.05739 -0.20598 -0.39758 0.33795 0.15776 -0.10590 -0.08163 -0.26879 0.26603 0.13942 0.14388 0.15602 -0.85931 0.46755 -0.37693 0.14924 0.18844 1.29502 -1.31627 + -0.57261 -0.15101 -0.03142 0.04828 -0.09470 1.30126 0.29676 0.02642 -0.10865 0.12241 -1.04666 -0.17702 0.10930 0.48806 0.79384 0.35790 0.00519 -0.09722 -0.76968 -1.93132 -0.05982 0.03488 -0.03692 0.34823 1.14489 + 0.02861 -0.04563 -0.39979 -0.34141 0.84996 -0.11996 0.09395 0.10138 0.81867 -0.96541 0.17159 -0.18584 0.25071 -0.22578 -0.06749 1.50317 -1.28229 -0.16426 -0.02308 0.15558 -1.66312 1.45438 0.22480 -0.25807 0.09117 + -0.55490 0.19579 0.22691 0.60510 -0.46819 0.06905 -0.09310 -0.00511 -0.26410 0.29786 -0.15810 0.19022 0.02614 -0.00490 -0.06838 0.11087 -0.14454 -0.04154 -0.16050 0.23955 -0.60009 0.80946 0.13003 0.34930 -0.69227 + 0.02280 0.50837 0.09286 -0.70868 0.16414 -0.80301 0.17835 0.36944 0.75854 -0.61169 0.44842 -0.99949 0.04847 0.08457 0.35292 0.60861 -0.02401 -0.48740 0.41152 -0.41065 -0.34356 0.41056 -0.01730 -0.58536 0.53149 + 1.54887 -0.44899 -0.27397 -0.36683 -0.36138 -1.38762 0.36466 0.10235 0.35630 0.40105 -0.17410 -0.05898 0.13052 -0.04032 0.38137 -0.82904 0.31802 -0.02420 -0.20938 0.57263 0.95569 -0.26814 0.08144 0.25318 -1.02387 + 0.26344 -0.49099 0.61113 -1.33142 0.89974 0.05990 -0.07519 0.14265 -0.33453 0.30248 0.08324 -0.12872 0.07988 -0.24786 0.14599 0.17826 -0.18072 0.08816 -0.10930 0.12304 0.45104 -0.70917 0.41756 -0.41199 0.18098 + -0.46895 0.79795 -0.38564 0.04986 -0.04034 0.11811 -0.23006 0.26011 -0.13551 0.03185 -0.01839 -0.09632 0.18000 -0.13208 0.03061 0.11165 -0.25590 0.42916 -0.49657 0.24341 0.51922 -1.52509 2.17579 -1.86952 0.70906 + -1.59203 1.37214 -0.36807 0.42638 -0.00689 2.86095 -2.02733 0.40858 -0.61961 -0.28165 -1.77476 0.55742 -0.12732 0.31007 0.76569 0.19805 0.83530 -0.18053 0.29590 -1.07493 0.27739 -0.69004 0.21195 -0.37112 0.59251 + + diff --git a/data/README.foe b/data/README.foe new file mode 100644 index 0000000..9d5077c --- /dev/null +++ b/data/README.foe @@ -0,0 +1,14 @@ +The *.foe files contain coefficients provided by Stefan Roth, who agreed to +release them under a BSD license. See his home page: + + http://www.gris.informatik.tu-darmstadt.de/~sroth/research/foe/index.html + +The coefficients in the *.foe files have been obtained by extracting the +matrices from the MATLAB files and performing matrix multiplication. + +The format of the files is ASCII: + + ... + ... + ... + ... diff --git a/data/ceres_noisy.pgm b/data/ceres_noisy.pgm new file mode 100644 index 0000000..1669988 --- /dev/null +++ b/data/ceres_noisy.pgm @@ -0,0 +1,6 @@ +P2 +# PGM format + # + # ... +177 213 255 +86 74 90 29 80 63 76 62 83 97 64 102 86 67 103 61 27 57 63 58 60 97 84 73 110 81 85 71 52 17 106 71 95 104 103 62 88 84 91 82 70 89 109 32 70 54 88 68 81 62 95 76 92 97 91 42 86 35 50 50 37 89 36 43 48 77 50 63 66 72 47 27 54 8 48 43 102 43 0 40 0 61 31 54 50 34 58 4 44 24 35 33 34 47 46 20 40 24 0 47 16 21 55 26 54 25 22 22 35 0 37 64 35 48 40 1 27 3 43 45 32 74 34 44 17 13 33 45 10 52 32 76 79 70 47 27 74 44 30 86 7 49 66 87 51 71 81 59 72 60 49 62 45 41 53 101 58 54 49 84 58 62 69 98 84 63 102 123 72 101 90 106 80 86 73 78 74 90 61 89 47 109 63 82 53 102 68 56 40 62 51 85 71 41 47 59 91 43 85 60 75 67 59 96 45 66 58 85 71 78 77 65 104 51 66 59 112 62 66 47 78 74 121 65 141 30 70 44 127 72 86 49 48 61 83 84 43 86 47 79 75 68 65 35 10 33 60 15 67 87 45 27 57 40 51 57 44 16 30 60 16 53 42 21 54 33 50 14 39 50 25 39 17 37 70 70 32 32 17 57 21 43 49 28 63 54 81 34 47 106 16 29 26 38 77 49 41 51 35 1 31 41 40 47 71 40 32 59 37 57 44 53 57 14 33 47 56 80 0 44 73 37 40 61 72 109 38 34 92 53 39 48 88 91 48 69 112 48 25 83 39 75 88 58 59 31 79 79 104 83 96 69 84 58 46 85 50 94 70 65 82 62 65 62 80 49 17 66 73 40 53 81 96 68 99 60 79 95 116 99 40 67 121 91 65 80 73 50 53 53 71 95 77 77 64 82 47 63 76 75 34 69 84 115 63 61 21 48 51 95 85 82 62 64 64 62 77 100 70 48 75 59 56 44 55 68 70 87 52 72 46 65 52 56 88 52 71 42 66 50 18 35 61 23 21 0 74 47 37 22 33 37 42 27 63 74 35 37 4 0 23 62 37 45 45 48 47 35 59 46 54 81 50 41 47 34 66 82 112 37 33 49 68 32 69 78 37 49 28 89 61 29 30 0 55 48 79 37 31 71 68 61 38 99 87 68 75 50 33 36 99 48 71 55 74 53 73 46 76 69 58 78 79 106 100 105 90 95 81 82 70 101 70 84 83 54 55 59 97 70 77 69 65 106 83 80 66 66 75 102 67 41 33 88 65 88 71 75 49 29 59 58 34 84 95 61 48 67 97 101 82 72 81 100 80 59 70 35 70 99 51 70 79 71 69 88 95 53 48 85 51 100 56 78 82 85 60 54 20 80 54 74 51 76 31 40 72 48 85 75 15 60 55 53 45 14 35 53 32 76 45 36 41 58 75 52 59 38 64 35 60 35 45 30 58 57 66 15 43 68 40 26 66 37 35 36 69 59 32 33 33 36 46 40 27 63 65 44 75 64 68 69 66 55 51 78 62 61 43 46 42 70 13 35 15 66 62 47 52 41 58 66 6 93 86 80 84 73 72 82 97 101 83 100 100 76 63 80 100 95 61 53 107 93 83 103 94 70 50 113 95 99 77 98 69 56 75 48 125 82 30 66 51 74 50 113 69 79 76 62 75 124 54 73 68 74 51 80 51 56 51 60 65 88 83 83 90 76 66 82 71 86 45 92 83 64 97 53 99 80 75 89 88 87 54 57 68 59 62 63 57 67 39 92 50 45 55 55 22 93 54 52 50 0 62 48 36 44 34 19 49 26 39 72 39 48 76 85 35 53 27 52 66 42 93 30 83 69 92 57 50 73 44 46 44 43 60 59 14 32 17 13 55 26 38 14 18 64 44 27 54 46 58 82 29 61 53 79 62 58 38 87 28 64 60 62 54 44 54 53 66 53 73 74 80 84 73 82 81 83 88 95 90 85 80 52 112 103 103 94 97 101 57 63 97 94 73 133 85 111 105 35 127 85 101 83 66 82 56 53 88 46 57 88 79 76 133 63 59 64 49 91 57 53 68 93 100 87 65 78 97 91 101 73 38 93 84 50 59 52 75 51 116 77 57 61 99 73 72 83 92 81 107 106 63 69 37 56 114 71 69 86 60 97 31 50 33 83 75 69 88 64 69 75 28 56 56 36 78 41 52 49 58 59 83 66 69 68 49 58 66 51 54 79 34 72 44 74 86 61 53 23 44 24 27 38 84 28 77 55 76 42 33 77 44 44 46 39 76 33 48 41 52 84 29 52 84 66 59 22 47 52 55 43 73 62 74 45 62 80 74 60 74 28 14 47 43 48 71 91 73 84 53 99 95 73 61 92 83 88 62 99 48 59 84 70 79 106 62 46 75 77 78 46 44 51 51 88 96 81 84 99 83 84 81 104 68 79 71 59 89 93 85 82 80 111 63 77 89 63 85 80 102 83 112 64 63 72 55 117 104 98 71 119 73 97 128 73 113 86 100 67 121 92 93 77 58 63 96 87 58 81 65 33 84 77 86 73 55 75 50 72 108 103 51 38 59 55 20 51 68 74 48 32 35 72 60 64 49 57 90 52 76 84 82 15 90 53 89 70 70 92 88 62 77 30 59 63 89 95 62 90 59 95 41 65 81 79 83 81 30 59 89 31 62 37 56 53 79 35 92 55 72 71 53 70 22 67 36 53 57 13 64 64 93 42 31 41 106 64 48 113 64 41 54 69 63 46 62 73 60 67 90 99 96 91 57 35 38 94 103 79 66 61 104 63 87 89 104 74 87 103 88 80 88 118 76 114 103 115 58 89 61 66 18 94 101 83 50 77 58 59 135 94 39 99 119 138 94 96 56 89 84 76 97 77 73 87 87 42 83 71 119 44 45 55 82 78 86 105 72 96 75 84 82 62 105 58 46 79 80 77 67 68 46 56 24 48 65 71 70 56 37 62 104 66 41 83 92 62 72 43 107 46 44 58 62 3 39 73 69 48 24 67 102 102 45 31 75 46 102 94 45 10 92 81 58 61 61 79 66 64 59 83 82 97 79 60 47 64 76 64 72 70 100 41 56 67 38 31 81 84 84 74 69 61 95 49 85 37 42 65 84 82 29 81 90 60 74 86 65 66 30 48 46 108 74 67 48 75 97 92 105 87 80 79 134 117 119 62 45 90 132 66 125 90 87 91 95 62 110 67 98 74 114 86 99 89 96 84 95 64 94 66 120 84 64 74 115 93 74 68 54 95 60 81 86 113 46 92 89 92 101 67 66 60 51 99 93 51 69 60 78 78 93 89 56 41 68 74 47 123 62 102 81 37 51 72 90 83 56 60 54 93 78 94 66 92 89 78 37 41 25 50 45 53 56 50 65 36 81 71 61 77 71 62 45 42 92 77 64 69 44 34 62 32 4 38 91 73 74 53 74 81 32 50 81 50 36 45 22 52 69 56 57 60 100 70 59 61 63 75 52 71 84 78 72 107 79 26 68 105 26 76 86 76 70 92 83 47 80 32 47 63 46 69 61 26 87 28 51 44 54 44 47 60 58 51 114 79 64 95 87 63 100 90 90 66 72 87 78 50 90 93 114 92 105 80 91 95 66 84 68 81 101 81 53 70 80 139 91 118 140 54 75 68 78 88 66 84 84 80 63 36 91 90 43 67 84 34 94 103 69 85 89 81 55 53 74 103 64 75 66 49 80 77 78 66 95 87 78 87 78 72 86 104 41 78 60 55 116 52 63 80 26 113 92 49 61 68 108 74 59 63 41 25 51 57 75 90 20 89 39 72 20 61 74 57 95 32 31 97 93 76 54 101 57 61 73 62 61 80 35 75 53 41 59 87 68 21 80 95 53 69 53 86 48 52 32 46 73 69 44 72 36 38 76 54 45 78 87 102 77 67 50 110 68 85 79 73 73 45 68 62 64 61 87 61 53 65 46 96 110 68 70 97 85 100 130 49 88 72 53 105 83 86 109 78 109 70 94 108 108 105 86 70 105 64 65 93 74 98 69 58 71 78 47 62 81 94 77 43 71 70 98 83 54 33 75 93 64 52 74 69 50 80 110 97 79 85 104 88 75 100 73 71 50 74 84 83 101 64 79 66 68 75 45 107 82 95 91 72 96 88 71 93 68 86 77 91 66 42 89 80 44 53 82 115 58 70 78 106 81 73 67 74 54 62 30 77 87 60 62 69 44 50 32 70 34 47 101 72 85 50 84 79 64 82 29 69 107 59 50 41 90 68 78 113 87 69 102 72 82 60 71 87 51 83 117 88 46 75 42 91 67 42 38 75 55 63 81 100 72 56 61 87 50 64 29 55 102 88 102 69 57 79 104 65 91 79 52 92 74 99 116 82 81 103 88 72 84 72 100 90 147 83 83 83 72 141 111 82 67 96 66 83 109 78 70 125 100 103 89 86 75 83 98 50 95 115 84 81 64 87 60 89 104 43 61 64 63 79 80 86 87 134 76 76 73 92 122 87 58 84 68 96 63 124 69 91 87 45 56 83 82 90 62 71 106 126 65 100 79 75 76 61 69 46 81 67 59 75 84 74 110 80 69 53 73 81 54 52 46 76 51 40 89 84 77 62 51 63 66 60 81 64 67 74 95 80 28 69 50 54 74 66 98 86 82 55 86 39 25 93 67 78 76 96 57 76 98 50 67 20 53 61 57 70 80 35 95 68 51 64 82 43 52 66 51 79 63 79 91 59 59 86 70 76 82 107 66 58 115 110 66 67 82 63 83 97 90 64 97 84 55 78 72 88 89 65 107 101 94 83 25 38 131 50 107 113 114 122 47 87 69 100 101 65 44 88 78 106 85 46 53 33 34 93 71 60 84 109 75 66 89 73 42 34 56 63 98 69 96 90 77 82 84 74 82 93 86 49 83 67 78 70 124 50 37 51 66 51 84 64 68 31 56 69 105 91 27 57 81 58 48 31 61 116 48 68 81 103 61 65 87 76 79 61 44 115 72 67 80 129 53 80 83 77 91 94 72 74 69 46 86 80 55 77 85 50 67 71 110 53 73 29 65 44 71 71 22 40 62 63 47 30 75 61 52 68 61 38 85 39 49 84 80 31 61 64 94 47 76 63 4 64 47 52 88 81 98 74 74 79 56 88 47 81 37 88 90 71 104 54 10 98 67 89 95 118 99 70 95 107 100 92 82 88 64 67 83 69 130 86 78 96 67 79 105 103 79 110 64 117 88 118 82 96 64 92 47 81 57 76 65 67 115 70 83 107 117 77 106 91 81 68 87 92 85 62 55 103 78 80 62 92 89 88 82 64 71 96 76 34 72 69 86 81 60 74 59 102 83 63 42 66 68 87 16 91 75 58 75 90 65 58 72 36 62 80 73 46 78 53 89 68 90 63 61 41 37 42 65 80 68 37 64 61 49 83 58 62 57 80 70 53 79 77 53 101 49 71 89 50 53 83 59 94 26 51 66 79 3 82 69 71 87 109 95 126 61 90 72 69 76 77 58 94 30 45 77 75 57 82 88 69 88 63 79 49 68 85 68 35 63 93 61 111 74 90 58 86 74 72 31 80 69 65 42 88 131 140 65 79 52 82 80 88 98 109 98 95 90 70 104 92 95 85 107 89 82 110 65 114 100 39 66 118 73 95 103 117 109 78 66 63 84 39 96 69 123 95 73 99 98 99 71 96 97 94 96 106 115 54 107 95 104 67 115 69 66 93 95 35 108 89 117 84 75 130 46 62 23 99 75 76 77 89 70 36 84 70 73 85 44 63 82 67 55 54 122 84 44 66 70 52 78 44 55 43 84 103 66 87 28 110 86 59 85 33 55 66 90 89 67 52 84 49 59 42 106 83 100 66 58 41 63 73 86 45 101 85 47 78 57 83 82 44 87 57 63 83 75 100 97 66 73 43 85 61 57 44 65 65 64 63 85 48 35 97 86 93 58 91 41 78 57 93 84 82 97 43 103 91 93 65 92 106 84 84 92 82 79 65 61 102 88 115 72 96 132 95 117 87 73 85 76 104 91 103 92 70 65 66 73 94 84 87 84 78 67 62 102 90 76 66 82 134 110 62 114 80 54 54 97 103 76 57 86 78 77 87 70 112 61 79 57 67 45 83 59 79 49 61 45 84 103 68 72 87 76 78 66 73 57 82 76 64 70 87 81 106 60 49 50 56 98 60 107 58 90 60 50 42 77 84 37 49 91 55 36 82 73 75 110 35 94 75 24 70 57 68 52 50 98 70 48 122 86 73 52 59 47 94 64 76 36 92 103 101 21 92 35 69 80 77 49 85 95 16 90 40 65 78 79 75 71 45 61 73 49 85 77 55 57 51 112 63 96 91 70 84 86 37 91 77 56 47 85 90 105 97 93 107 71 88 56 111 65 82 99 110 72 121 73 115 95 87 99 102 90 72 47 88 75 75 83 74 108 88 55 60 85 59 98 77 78 132 80 74 49 96 126 110 97 96 132 100 105 86 65 73 59 78 86 90 76 77 78 109 68 54 74 58 84 77 82 105 30 92 109 76 98 77 92 40 83 27 115 84 59 97 44 53 77 95 83 76 32 66 83 92 31 77 43 58 43 57 68 63 65 77 59 72 53 79 51 82 50 32 39 64 57 61 87 37 64 46 77 32 91 61 48 90 55 71 67 43 36 74 71 61 49 55 56 67 54 82 77 75 98 72 87 85 93 46 75 42 72 75 77 72 82 73 80 74 81 89 82 65 39 64 73 61 86 106 64 77 98 76 87 80 114 59 121 88 75 99 84 83 91 69 85 93 84 73 118 91 100 87 81 94 75 90 136 61 74 100 106 92 102 80 90 77 123 107 100 121 97 69 95 75 114 71 65 108 79 76 63 67 97 96 109 99 94 90 107 99 115 82 93 114 76 73 73 70 87 35 79 90 96 86 80 80 79 83 77 91 44 55 76 75 127 98 118 130 97 109 118 73 73 84 33 53 78 84 32 45 73 112 51 37 105 52 75 66 59 71 38 75 71 55 68 89 98 58 83 41 68 49 78 57 58 54 93 70 34 64 42 72 79 100 76 69 108 63 73 54 67 71 36 51 50 78 36 68 23 58 128 64 66 97 65 74 89 63 47 80 73 52 76 80 97 75 104 50 76 84 80 79 36 59 74 94 107 67 60 62 91 63 72 86 71 92 94 86 91 78 60 90 129 116 92 102 67 134 64 90 100 63 105 104 91 128 104 70 87 89 99 97 51 79 66 105 80 59 67 71 66 118 90 60 59 88 91 62 71 83 103 58 78 72 64 93 88 95 47 85 91 50 90 73 89 112 63 80 76 75 79 114 68 126 119 95 122 54 52 135 192 190 185 172 155 147 160 152 168 170 156 135 99 79 58 15 32 60 62 35 45 84 70 76 70 57 65 55 62 69 11 61 16 84 91 60 57 77 64 42 68 38 37 87 33 57 55 67 54 52 58 62 69 42 69 50 84 64 66 83 35 64 55 56 60 73 70 84 63 102 81 84 75 97 63 82 67 70 102 99 73 81 72 60 87 50 4 87 67 74 60 59 92 58 87 137 98 84 62 101 96 60 99 97 96 127 63 57 97 92 78 82 99 83 87 64 80 70 133 98 63 33 60 80 96 84 50 89 122 83 62 91 116 134 87 110 98 97 114 65 130 90 87 63 72 47 98 75 74 72 107 49 96 85 113 90 69 103 97 101 52 94 115 117 89 106 91 89 82 81 108 75 96 182 181 180 244 220 193 150 183 129 147 108 169 135 164 105 121 171 124 72 33 38 46 82 65 57 58 56 65 42 45 72 55 81 67 62 36 69 79 61 39 45 95 86 46 80 91 76 43 59 52 71 51 64 25 16 78 80 69 40 73 75 59 49 38 116 91 51 60 80 52 37 55 54 81 77 71 83 83 81 55 85 82 86 71 113 49 56 100 49 47 83 84 64 101 73 76 84 61 56 124 95 69 70 63 105 69 72 103 111 74 95 79 130 95 88 89 130 102 86 92 66 99 81 76 72 103 65 56 75 64 36 76 47 51 54 79 60 92 101 78 88 48 113 98 95 59 78 88 56 104 104 83 104 80 61 79 27 101 64 58 43 82 8 104 76 93 76 120 111 116 84 95 99 136 194 166 170 150 151 208 187 188 162 149 111 186 166 121 213 191 165 146 142 99 154 104 31 46 62 33 80 52 37 74 38 77 56 45 9 75 66 48 55 54 62 57 81 29 46 52 62 99 88 72 52 36 73 97 53 16 55 63 71 81 47 64 42 83 68 44 69 69 69 53 62 41 88 65 80 37 101 132 56 80 51 73 91 50 102 75 101 50 71 58 87 54 43 102 94 102 97 103 74 110 90 93 141 67 82 65 71 68 103 75 71 86 105 95 59 81 95 75 119 112 53 112 64 60 87 103 83 97 94 106 89 106 48 99 78 82 78 116 109 120 81 74 76 92 58 46 119 92 123 77 76 96 114 123 74 86 105 78 59 52 91 83 69 69 61 55 124 111 142 100 93 109 45 94 92 166 191 159 181 173 203 174 162 194 186 174 125 196 165 183 186 172 205 192 191 156 96 124 143 54 31 62 33 5 82 46 92 66 54 60 52 87 95 32 70 54 90 61 39 55 64 35 58 61 80 95 60 92 89 99 61 49 63 81 89 87 102 55 81 56 68 79 88 115 91 28 82 69 59 57 56 93 127 82 84 104 80 93 82 101 49 77 72 91 89 65 79 63 38 85 80 47 73 84 75 82 64 109 101 53 96 99 77 123 94 94 63 115 75 99 65 121 75 66 70 84 86 95 101 33 98 104 80 91 88 63 58 128 107 81 104 81 103 30 71 105 121 79 106 104 92 67 63 74 126 118 111 77 113 72 83 64 61 75 79 91 108 83 115 65 76 101 112 97 158 93 119 154 114 73 171 174 163 189 189 212 213 183 168 187 177 197 203 163 146 135 132 156 167 153 174 187 149 156 63 46 57 79 30 60 37 48 50 42 60 9 52 77 95 54 60 85 90 71 47 46 69 51 60 59 69 74 62 98 63 58 70 79 54 37 101 34 53 65 60 88 81 71 47 52 48 44 97 34 47 122 39 119 122 35 73 68 69 39 116 75 41 104 122 103 72 62 117 92 78 66 55 55 54 72 108 93 52 95 69 105 111 83 63 89 92 61 100 93 81 100 59 111 67 82 93 79 101 68 74 89 76 87 99 67 114 92 130 96 62 83 120 70 87 77 80 128 116 84 98 121 64 47 63 72 102 107 84 60 66 82 107 94 62 86 70 56 97 60 69 37 92 107 155 138 116 99 130 142 79 107 189 180 162 167 204 222 217 191 185 154 199 190 172 166 160 144 146 136 177 173 173 110 207 173 130 132 75 35 39 104 45 53 68 88 99 81 56 56 44 79 88 52 80 50 48 86 54 68 58 58 42 86 86 45 67 95 41 70 49 102 56 91 58 80 79 72 78 94 80 76 64 112 74 84 62 108 55 73 97 106 93 82 65 124 36 60 55 68 36 106 97 53 58 41 45 106 71 59 70 89 86 84 76 124 22 45 52 103 45 68 69 88 85 54 108 79 108 94 85 57 88 57 75 96 125 91 91 91 108 85 95 79 60 90 89 61 87 128 67 89 70 62 28 98 90 82 127 76 118 114 80 87 91 52 110 88 85 42 84 60 69 75 57 110 73 98 60 104 128 126 136 95 91 37 58 179 170 202 223 167 184 210 185 208 184 221 245 182 207 189 195 167 166 184 164 204 128 171 191 137 148 185 124 86 22 4 48 64 78 74 104 34 59 87 58 56 71 98 61 85 50 84 0 67 58 22 54 57 69 75 66 102 47 107 63 39 47 70 78 88 72 104 100 135 47 128 38 72 58 63 56 77 103 94 109 62 95 61 95 46 63 89 51 65 71 38 82 75 120 82 93 38 87 50 52 97 76 65 93 74 55 84 121 57 111 90 55 77 72 89 93 85 83 87 84 84 95 84 63 125 130 68 78 72 98 111 108 76 87 90 110 107 81 103 64 102 70 89 97 109 82 130 85 82 96 101 80 66 77 105 64 50 92 151 77 111 65 48 104 82 74 92 121 108 132 116 76 67 49 47 118 199 213 195 177 168 197 197 213 151 206 184 203 175 203 169 227 164 194 200 166 169 169 140 176 180 135 142 98 58 66 71 76 46 17 78 81 26 66 71 47 68 58 98 66 93 69 57 40 55 54 47 65 60 83 90 38 37 123 80 115 51 72 92 74 93 80 110 88 64 57 85 61 103 98 77 87 78 61 120 85 109 85 102 70 72 37 99 59 57 59 81 55 27 55 64 105 47 35 82 69 60 56 86 69 58 73 110 96 108 68 81 91 104 95 91 94 127 109 113 67 82 79 63 87 62 99 70 95 92 112 92 65 114 73 49 128 88 75 89 97 68 99 65 140 54 86 86 113 98 114 55 79 69 76 93 52 58 82 96 77 98 58 35 99 54 58 134 100 67 107 68 78 18 53 134 199 192 225 214 208 219 190 169 212 167 206 179 211 207 219 161 166 193 149 210 174 186 192 173 143 114 186 174 123 89 24 26 12 23 11 66 58 79 59 80 101 84 26 79 110 60 48 52 96 70 96 63 90 76 85 66 38 61 93 75 101 84 87 90 106 69 66 49 59 80 96 77 80 96 134 48 85 91 105 115 95 98 62 44 78 61 63 28 45 95 72 36 105 97 84 34 60 99 98 63 112 60 79 53 138 66 86 105 112 80 110 63 62 109 75 86 90 94 72 94 136 76 94 115 100 122 98 86 81 101 59 65 73 105 100 100 49 101 140 125 111 120 88 77 77 76 105 98 124 75 83 86 118 72 60 46 77 83 98 68 77 87 62 99 70 59 90 95 73 88 62 47 77 42 58 131 166 186 234 203 185 206 223 185 165 144 169 186 156 149 161 210 165 172 173 128 172 165 171 170 149 145 98 137 151 156 55 47 0 69 65 11 62 26 78 79 32 111 97 61 70 84 41 46 37 79 84 94 61 29 91 66 72 82 54 50 55 66 61 57 57 74 52 52 67 66 92 40 60 131 47 95 29 63 68 133 74 90 102 52 43 56 94 94 88 37 89 42 55 71 90 97 81 35 66 40 94 36 40 73 69 110 71 110 76 85 132 102 74 87 81 30 93 82 75 90 114 79 110 127 78 71 89 87 95 99 94 82 99 91 72 95 107 84 81 106 96 86 84 84 99 77 108 87 93 65 74 74 86 119 64 59 63 128 111 80 102 118 102 95 78 67 63 99 102 73 40 69 19 62 37 149 185 216 175 196 206 179 193 182 190 188 180 136 160 203 180 129 159 105 147 98 50 91 117 140 144 127 138 175 88 80 132 135 91 36 28 64 12 27 58 75 83 71 67 59 49 52 73 58 111 85 75 56 58 64 67 72 44 114 45 133 91 36 66 64 76 84 64 76 66 121 108 126 90 92 74 75 60 26 111 79 45 85 131 42 111 131 103 74 79 71 35 72 30 66 66 59 59 122 72 86 32 57 70 45 25 39 51 37 79 76 44 73 123 56 80 94 62 75 102 95 48 58 81 77 73 88 110 62 79 61 98 107 81 140 108 93 85 139 107 90 66 86 81 72 113 55 111 116 70 117 128 72 105 73 92 73 89 96 38 99 105 56 72 38 90 63 108 98 48 41 55 8 0 54 9 155 178 224 162 199 202 209 171 185 209 156 158 160 140 163 175 140 132 163 144 98 62 49 0 14 95 69 148 156 121 113 38 93 116 110 30 21 88 13 48 0 3 37 43 102 57 50 75 74 32 44 91 79 108 84 67 66 68 66 56 51 48 82 63 67 68 67 63 51 80 87 106 91 54 126 138 77 81 60 121 107 46 47 111 96 91 78 63 14 32 0 4 92 56 58 134 45 75 58 77 51 36 38 23 19 45 31 42 72 42 82 85 101 70 86 92 90 59 73 106 84 79 107 88 83 78 59 77 55 100 102 107 99 63 96 96 113 90 128 99 137 72 83 79 66 58 69 108 94 66 68 80 90 89 70 97 58 88 110 76 57 80 95 51 115 66 87 86 48 73 56 82 22 56 32 27 115 199 187 206 215 207 182 142 167 183 166 163 167 125 123 123 113 131 86 97 70 27 3 47 56 40 27 16 86 149 105 107 65 85 94 64 116 45 62 22 25 7 23 23 27 34 95 73 73 68 74 56 83 62 116 67 74 20 40 87 66 58 92 99 61 34 92 51 84 52 74 44 129 52 108 26 102 81 125 31 106 75 85 28 86 58 54 32 25 13 32 30 0 26 46 57 74 30 56 72 56 81 76 8 43 37 36 13 9 64 61 71 70 23 60 60 101 89 89 87 77 63 71 68 60 129 102 125 69 74 91 106 76 99 91 61 107 59 95 121 81 98 89 62 101 93 86 93 67 51 37 81 149 126 113 53 74 87 83 79 91 107 33 88 49 100 96 118 25 47 44 42 59 19 54 38 118 195 173 186 204 181 203 192 148 157 193 165 148 138 160 107 84 75 82 81 84 88 33 21 75 44 50 28 33 0 128 171 126 60 20 71 127 127 31 90 63 11 21 20 0 34 0 32 83 47 29 49 66 89 99 78 58 49 36 59 90 98 64 66 105 76 92 55 51 54 74 75 77 65 127 50 103 84 32 13 72 47 0 85 79 39 44 47 48 36 26 35 25 15 0 22 32 0 18 51 61 63 72 55 11 47 26 29 65 60 15 65 43 99 69 103 57 67 89 82 71 37 85 106 87 102 70 79 86 113 68 119 60 70 91 93 87 110 123 90 64 32 120 89 92 79 97 131 74 96 76 131 96 90 109 101 60 81 75 85 101 35 29 118 67 53 60 92 36 19 44 35 43 21 55 45 59 175 195 212 181 164 144 175 170 167 142 137 143 182 137 125 79 53 95 97 3 19 1 63 52 68 49 45 30 23 1 15 163 166 92 0 43 57 91 91 56 78 32 0 13 50 64 40 28 26 91 71 75 72 54 95 56 88 78 70 81 54 32 72 77 63 63 66 93 79 90 82 119 93 73 68 107 57 63 28 83 28 45 79 0 55 59 68 29 58 0 43 29 9 54 31 109 27 60 61 43 40 30 57 35 34 28 9 0 54 54 62 5 44 55 82 77 81 53 85 53 96 89 31 50 111 96 96 76 114 128 129 61 128 104 111 89 105 96 108 72 70 75 109 75 148 79 88 88 110 83 85 71 104 85 101 102 73 101 93 62 67 88 82 135 96 102 61 39 50 37 27 53 60 64 25 40 178 199 212 192 217 191 198 181 173 163 104 88 134 75 85 83 88 57 87 99 4 54 38 50 33 53 34 56 21 0 35 11 82 154 81 32 4 103 91 68 42 78 26 66 3 12 0 25 15 23 27 66 48 89 62 54 99 67 59 30 118 52 56 53 67 19 63 100 106 70 57 60 125 97 145 46 94 38 59 46 17 62 41 32 25 74 107 85 50 43 63 0 43 29 37 29 42 69 85 84 74 88 54 20 51 47 77 12 8 30 40 0 19 61 94 97 80 62 87 84 107 112 94 80 65 93 123 94 97 67 119 106 65 36 102 96 94 112 101 76 87 91 110 89 61 102 86 54 112 101 94 81 98 119 52 100 96 80 94 73 71 101 45 101 64 86 105 44 18 49 34 32 45 61 59 88 131 218 200 199 230 217 209 164 159 126 124 115 72 60 68 73 102 81 56 77 38 36 38 42 43 35 17 23 19 34 15 48 72 55 58 97 107 18 58 90 81 18 0 60 22 20 2 54 53 65 47 27 0 63 58 59 78 55 66 83 55 78 32 82 62 44 89 96 67 58 91 52 81 73 72 83 64 79 51 0 31 44 58 58 71 84 51 87 69 35 53 74 77 16 33 17 48 25 29 17 36 40 41 41 76 49 61 26 20 53 12 57 64 63 60 99 72 99 42 107 108 111 78 58 84 77 104 81 92 90 67 61 68 61 68 63 106 98 118 104 75 85 89 109 134 53 69 117 126 121 108 86 121 98 78 72 76 81 62 103 74 93 48 90 92 99 70 69 49 59 35 78 35 81 51 25 31 165 195 255 177 176 185 160 157 156 113 117 88 100 73 53 62 37 39 80 29 28 32 39 26 32 25 40 3 52 12 39 38 37 34 22 33 0 28 44 80 17 80 38 45 30 40 30 9 0 0 31 11 54 29 53 73 65 61 72 58 70 69 36 55 76 74 109 77 102 82 105 74 118 91 79 49 11 59 44 41 51 90 126 63 145 85 68 88 21 60 39 60 35 35 29 42 34 66 29 67 15 11 32 17 20 67 97 41 30 37 15 23 27 56 48 37 58 39 45 57 116 85 90 103 77 88 72 62 78 80 84 66 101 65 96 112 83 122 107 129 81 67 116 71 126 96 57 94 75 109 85 87 60 96 66 101 128 79 89 110 68 103 95 87 101 46 65 22 55 54 46 38 59 47 4 22 160 196 212 187 176 189 149 189 169 145 130 69 65 40 51 35 2 9 24 0 6 34 15 32 40 37 47 44 0 17 27 54 10 24 37 61 43 0 41 0 8 55 44 21 36 22 47 7 37 16 57 42 35 52 16 37 79 57 60 29 94 110 83 79 53 99 77 66 119 94 107 37 87 109 44 87 68 61 33 51 68 50 126 117 48 62 108 75 87 92 86 87 29 41 48 106 61 62 34 42 43 48 30 39 46 46 129 0 22 45 0 35 28 38 60 0 52 56 23 67 67 79 89 90 87 85 87 56 50 95 71 97 35 105 100 84 81 87 100 79 65 102 123 117 104 97 120 87 85 60 116 122 81 94 109 96 75 97 70 42 55 104 104 135 102 93 113 112 25 47 23 31 57 28 0 7 42 192 198 234 204 191 179 147 127 163 118 144 71 51 65 0 24 22 36 14 6 0 38 16 53 37 15 20 18 23 18 80 23 25 32 37 27 34 16 67 5 21 0 41 35 24 23 35 16 20 11 48 20 31 66 0 77 48 85 90 72 61 59 77 101 56 81 67 25 125 80 108 71 90 117 32 71 22 9 62 11 33 77 68 92 111 94 84 96 87 96 49 78 53 73 68 84 84 66 29 2 39 65 57 49 30 54 5 40 16 19 25 13 0 0 23 87 0 76 49 38 74 72 74 103 104 90 64 66 71 50 69 97 99 103 102 69 62 102 105 98 90 53 110 157 91 82 89 72 92 72 98 83 90 103 107 95 109 123 66 78 114 92 73 85 89 72 68 109 53 62 72 59 42 43 39 61 183 220 174 201 204 189 167 170 137 115 151 118 68 53 44 51 41 20 31 39 0 16 40 32 60 18 5 27 40 29 79 3 32 68 34 26 53 24 44 11 40 41 40 55 41 54 28 64 22 0 0 46 64 35 36 54 63 56 22 76 48 70 101 82 70 87 50 59 86 98 90 107 65 86 97 61 25 44 0 44 64 109 121 107 40 92 92 87 113 53 59 58 51 40 71 67 46 66 88 110 82 24 52 51 39 14 31 0 13 24 21 12 0 14 33 5 23 40 29 16 68 56 74 54 74 61 113 66 91 49 67 120 105 94 129 67 93 60 105 71 99 92 76 78 96 87 82 91 82 82 86 119 66 71 110 41 104 107 68 86 86 58 88 60 86 100 95 77 69 38 59 41 53 44 66 0 124 217 186 198 243 202 181 199 149 159 159 66 76 115 50 48 56 26 0 2 27 52 53 26 32 22 37 5 25 55 25 84 2 26 48 11 39 27 41 56 42 5 25 25 47 12 10 31 32 45 25 37 16 25 14 42 31 24 40 70 61 35 115 75 96 74 71 73 85 57 89 68 121 109 36 5 59 28 0 35 48 60 107 86 75 89 104 77 74 76 75 74 118 60 74 66 79 67 97 90 98 83 97 45 42 46 13 20 37 38 43 0 5 29 0 35 14 30 31 52 45 2 53 63 35 80 80 89 82 76 70 92 71 79 72 78 59 99 77 92 124 34 53 98 76 121 101 126 88 102 84 65 108 110 75 84 74 106 98 128 87 97 67 103 102 87 97 90 73 45 60 86 20 63 47 27 76 173 175 192 210 211 193 156 182 152 157 134 124 74 38 55 34 18 20 34 14 4 7 10 40 35 43 10 26 0 25 34 11 48 0 25 84 34 5 30 59 25 0 16 50 38 14 0 38 50 71 13 31 84 21 66 53 46 48 46 51 28 59 58 99 84 94 81 72 60 118 60 88 104 66 68 51 16 0 50 60 62 86 77 62 57 34 87 89 80 113 119 101 117 117 65 131 82 99 73 101 116 85 93 73 41 48 7 59 24 19 36 11 9 30 0 8 25 1 0 20 0 19 67 15 103 104 130 83 91 52 117 98 77 60 82 83 89 93 94 77 63 79 85 122 84 120 112 91 95 116 92 71 42 102 64 92 117 101 115 89 131 67 118 111 86 58 132 85 78 56 86 27 49 50 57 65 169 209 208 209 192 160 219 178 172 172 159 164 82 85 0 58 10 41 11 17 72 35 51 9 20 26 6 11 29 37 46 49 55 46 39 22 12 16 9 10 8 27 0 24 26 0 63 38 55 26 24 16 0 42 49 33 50 33 32 31 11 49 41 90 55 29 79 105 46 81 107 117 45 82 0 68 44 35 18 33 69 64 43 60 63 32 143 106 128 128 159 95 146 118 143 164 99 146 117 104 132 101 43 99 88 31 23 56 0 39 55 18 0 1 6 0 14 0 56 11 6 46 44 23 84 59 42 43 61 104 78 78 90 111 73 120 100 68 96 149 69 99 105 91 97 83 102 63 83 107 112 109 120 98 47 117 85 93 125 72 119 115 84 116 88 112 77 102 94 142 87 34 73 39 57 10 172 200 179 189 215 201 197 180 165 134 163 164 145 83 93 43 59 0 27 56 58 44 37 35 9 4 19 7 45 38 23 0 56 32 6 66 0 49 31 16 17 21 56 0 0 0 13 14 18 16 18 20 45 4 13 48 35 56 49 34 25 31 59 55 70 52 53 78 49 96 84 91 107 42 68 35 41 27 0 15 74 104 43 65 47 69 115 131 191 224 158 239 175 158 182 137 135 111 156 130 110 122 63 91 105 67 93 68 45 7 30 19 2 34 0 0 39 13 1 24 0 0 64 1 50 39 39 87 39 96 58 46 57 82 79 82 65 112 117 106 95 51 109 86 60 90 94 138 86 83 70 119 48 83 85 89 98 116 110 128 73 106 81 67 121 94 52 92 90 113 107 64 76 37 41 40 145 179 225 156 203 143 201 191 201 173 143 120 125 75 89 68 22 34 7 34 56 35 26 35 4 30 35 30 22 9 39 6 56 0 51 44 29 39 3 15 44 47 38 22 8 31 72 19 13 42 21 55 46 43 35 43 18 47 42 66 28 36 22 44 61 45 52 8 71 80 59 84 72 82 51 6 20 55 19 43 12 97 92 73 63 93 140 160 197 198 175 182 184 211 176 171 179 221 175 158 194 181 113 101 110 89 77 80 63 75 69 37 54 32 20 25 44 0 21 0 44 0 14 0 59 40 37 104 46 126 107 75 74 116 69 53 106 56 27 78 101 77 122 97 60 51 99 75 72 107 118 86 96 71 74 110 80 94 83 103 122 82 112 82 104 105 87 115 55 81 136 110 27 35 73 16 115 200 187 196 201 158 196 184 158 151 187 137 114 139 84 65 81 37 17 19 5 51 19 74 17 67 37 34 43 0 32 10 37 25 51 63 39 23 38 21 4 36 31 55 15 14 44 25 24 13 16 22 19 0 44 49 23 26 41 19 0 84 7 53 32 51 52 49 50 32 63 89 94 103 71 75 48 21 31 10 26 66 77 41 62 55 155 160 149 210 200 203 194 198 195 190 177 191 187 184 209 185 137 156 88 128 86 66 80 67 48 35 43 61 94 75 41 0 9 32 26 37 2 4 20 41 9 36 66 66 72 62 92 91 69 106 95 120 81 94 84 107 120 49 60 113 92 106 69 89 78 107 64 92 123 97 101 80 75 79 92 93 86 102 115 98 75 92 38 69 89 127 10 70 99 59 29 180 183 185 197 182 188 204 172 201 172 131 179 133 94 82 75 41 59 0 41 38 0 31 53 20 51 48 64 23 16 4 19 24 45 47 21 1 31 47 4 19 0 6 17 38 7 26 5 17 39 0 36 21 54 77 26 2 37 62 35 46 38 46 46 22 29 39 68 30 72 80 77 71 71 106 80 69 60 4 68 39 28 45 42 66 140 146 201 160 188 209 221 169 214 201 230 219 158 222 158 183 145 128 122 132 136 120 47 65 41 39 43 13 32 23 46 4 12 17 33 26 8 8 0 24 0 5 40 66 29 91 43 70 79 82 70 81 81 83 84 105 88 110 24 92 46 95 60 87 98 96 129 71 66 89 111 60 70 95 88 138 91 132 98 114 42 104 89 89 79 115 114 79 38 91 17 139 171 183 174 234 199 175 155 195 174 168 176 173 152 94 45 76 67 57 39 23 34 23 57 15 20 62 34 28 16 11 24 50 13 34 47 80 14 70 55 8 68 26 7 5 14 37 10 14 42 29 52 49 24 34 31 35 47 12 37 38 14 14 14 35 51 20 76 27 91 90 83 51 47 59 112 76 40 74 15 88 110 16 76 32 105 116 152 168 169 181 230 219 185 197 191 239 181 176 208 145 140 131 164 131 130 111 89 118 36 97 116 59 0 20 37 12 20 21 12 8 33 1 0 12 13 0 29 51 101 66 45 94 50 103 85 104 88 70 78 64 66 67 109 85 67 60 78 61 109 125 83 107 91 113 130 114 101 92 137 99 105 82 60 119 99 76 80 82 80 90 114 132 64 81 76 107 175 164 212 217 215 210 234 178 161 169 175 146 111 110 94 95 70 58 33 54 91 26 57 45 37 52 27 33 24 41 20 39 10 23 0 22 32 8 22 33 41 25 51 30 8 20 67 4 16 29 0 30 14 26 28 40 42 58 43 32 18 49 17 55 11 34 26 48 27 62 33 80 64 70 92 97 87 63 46 42 74 85 63 38 30 162 142 160 213 175 206 203 203 190 241 202 218 198 188 209 195 196 193 188 137 217 82 81 122 96 77 117 97 16 38 33 44 25 0 20 0 0 0 0 0 0 10 46 23 59 55 82 107 65 74 55 43 65 103 66 104 75 84 57 88 90 121 87 76 120 88 86 79 101 83 81 87 87 72 106 140 100 105 106 117 63 89 85 102 99 109 135 96 34 65 95 175 153 187 193 240 206 227 190 205 151 202 149 149 126 102 73 69 80 58 46 42 19 48 50 24 53 69 33 15 54 79 20 22 48 16 3 24 31 0 1 36 47 41 5 8 20 0 39 0 38 51 8 3 41 31 3 3 40 65 51 19 30 29 20 57 23 34 51 50 49 55 71 79 103 62 63 110 70 75 89 0 11 52 91 35 80 150 164 184 176 201 171 172 227 197 170 209 161 224 211 203 214 189 183 166 208 183 135 106 87 74 84 117 112 71 39 63 0 39 18 21 0 21 33 0 16 11 0 15 0 11 20 74 41 80 75 56 89 99 112 41 66 92 93 120 103 54 108 72 88 97 65 100 79 93 120 100 102 128 121 89 113 119 124 72 88 84 104 55 77 115 109 136 97 48 29 147 151 180 217 181 207 252 180 171 166 186 193 189 146 159 68 63 68 47 26 8 49 36 17 14 33 6 77 23 45 49 8 15 0 15 53 56 38 37 23 30 55 41 37 8 41 24 3 44 19 31 0 32 38 10 61 24 27 55 57 54 83 5 39 35 25 30 0 37 18 26 43 57 60 45 92 57 76 76 43 65 12 51 30 12 24 117 140 221 215 167 208 164 236 212 221 178 185 203 203 201 215 209 201 173 156 155 177 158 112 103 58 74 97 109 82 49 34 52 51 24 18 45 30 8 12 26 18 36 0 46 50 66 29 47 82 69 54 57 109 59 63 83 103 108 88 65 95 56 78 63 97 121 107 129 98 76 75 101 63 126 47 105 97 120 101 79 69 64 103 108 78 148 119 112 35 107 136 194 145 177 211 194 185 180 229 205 150 181 177 116 128 83 55 73 39 33 47 42 0 6 46 32 51 35 22 22 32 35 26 59 26 33 22 55 12 4 29 28 13 52 26 17 8 31 8 28 18 24 3 42 40 16 39 50 54 18 18 19 36 21 13 53 43 1 31 56 15 68 29 53 20 41 78 99 85 79 48 0 15 27 23 87 144 159 200 184 235 238 233 182 194 213 180 173 189 213 225 177 218 198 207 182 168 156 141 156 97 104 70 21 59 28 40 1 21 0 9 8 23 39 35 0 52 51 13 9 31 24 27 55 89 103 72 105 85 43 87 71 45 112 54 80 72 94 114 23 84 69 103 135 108 89 85 84 112 52 78 83 102 99 100 80 74 99 95 74 91 91 110 153 99 100 177 155 183 233 189 179 164 175 188 174 150 180 179 130 137 134 89 95 47 68 35 19 10 29 20 58 42 4 36 52 35 63 56 19 55 0 36 33 0 60 29 35 9 14 3 14 59 0 23 0 43 66 6 24 48 64 34 50 37 40 24 13 45 16 62 12 52 54 39 40 39 0 24 40 0 40 43 77 104 116 62 42 0 30 1 25 93 203 178 166 171 170 226 182 187 192 182 201 164 225 208 190 178 208 177 187 198 187 178 144 129 134 125 78 56 20 5 6 45 27 73 0 0 25 7 0 41 24 30 41 0 0 35 82 81 23 50 60 105 85 57 70 117 103 116 91 105 61 64 103 120 93 61 97 121 111 81 111 102 69 51 75 112 108 81 98 105 79 82 95 138 148 113 132 135 104 104 145 211 187 225 255 170 168 197 191 207 176 173 188 141 110 154 101 109 75 28 27 36 63 8 45 59 34 49 27 53 21 41 40 29 45 15 25 57 43 3 42 38 44 58 37 0 2 39 39 11 0 42 23 0 5 45 44 26 17 43 32 26 41 27 28 37 29 57 73 36 21 36 63 30 0 23 12 38 111 72 34 52 0 22 52 23 143 206 162 102 91 101 71 134 197 198 193 193 207 194 208 202 186 188 199 202 185 179 201 135 156 109 102 63 69 41 24 16 46 40 8 33 56 0 0 44 11 27 12 23 38 26 26 70 55 70 82 95 78 83 85 82 80 109 76 94 113 94 106 92 92 78 88 116 98 84 100 83 98 102 62 105 77 125 98 63 78 142 111 82 117 133 158 121 116 129 200 193 208 222 206 229 232 203 194 187 181 160 145 137 141 154 64 88 58 45 0 66 55 39 40 9 22 73 37 39 56 48 0 50 3 40 40 30 65 0 44 34 27 1 49 68 8 54 50 11 34 4 0 7 66 39 3 44 45 46 39 17 4 11 42 40 18 0 33 41 26 34 53 24 52 4 36 46 67 90 65 59 53 56 84 11 9 180 190 129 185 138 96 113 91 146 181 181 165 204 200 196 199 174 194 196 194 221 182 190 91 139 127 97 69 99 31 32 70 68 4 37 30 2 0 30 10 0 14 0 33 0 38 33 47 72 52 72 103 41 59 69 78 97 77 103 99 120 54 123 83 77 84 99 102 66 67 103 88 90 91 79 95 107 77 84 117 105 88 136 115 111 97 111 125 121 169 208 227 148 146 194 243 171 154 158 193 163 181 173 158 134 121 106 77 89 34 32 34 31 12 7 16 51 30 36 27 7 3 23 29 33 48 32 48 50 24 44 5 10 33 61 47 1 0 64 31 0 43 33 49 46 44 22 28 34 0 13 25 0 45 96 41 57 57 31 40 22 31 90 69 19 34 49 30 23 70 60 50 7 53 28 0 63 161 117 144 181 195 123 70 107 77 124 183 167 169 216 223 168 232 195 206 182 169 178 202 136 97 110 58 107 80 45 36 49 23 40 13 33 42 33 51 37 15 10 0 20 52 25 35 30 64 91 62 55 77 67 96 93 114 120 112 109 127 82 78 79 80 77 94 139 93 61 121 76 79 126 77 107 106 84 107 122 76 112 88 118 134 81 147 126 111 177 167 197 214 175 231 216 227 208 214 164 187 157 155 162 134 133 103 48 47 45 45 19 71 67 24 45 25 33 46 0 25 46 52 1 49 44 13 32 21 21 56 59 51 17 13 10 25 13 40 14 3 19 27 46 27 55 25 52 31 22 12 28 64 20 58 61 69 34 58 38 23 31 50 27 61 35 27 34 26 77 94 60 52 7 32 5 88 128 135 109 30 6 66 64 57 77 111 153 152 168 183 196 187 219 176 234 168 180 215 200 146 104 133 97 113 59 54 31 41 8 41 22 19 14 6 32 56 54 64 18 43 41 46 11 63 92 96 120 88 72 33 80 22 88 96 71 97 70 109 57 86 91 71 114 106 89 88 84 79 98 87 143 131 89 116 106 95 100 118 140 96 115 110 96 139 163 189 200 173 170 210 202 215 202 189 149 191 175 183 146 107 172 154 90 76 48 19 55 48 74 58 39 0 41 42 27 30 53 0 72 10 49 31 41 2 35 46 8 4 8 40 1 0 7 10 26 10 8 13 33 24 7 16 41 53 17 4 56 56 34 26 12 21 26 21 18 27 39 71 43 73 41 24 43 54 8 35 101 71 84 75 20 32 100 134 96 147 46 0 3 30 55 44 124 161 133 164 185 177 196 145 162 116 136 132 124 175 160 141 125 79 101 91 25 45 0 8 9 30 0 3 0 31 34 30 20 0 20 0 24 41 31 88 51 46 75 32 52 43 114 82 59 116 97 88 83 99 107 92 64 72 84 112 73 117 78 117 113 60 93 99 147 101 93 111 96 131 167 98 109 153 150 189 177 176 163 208 204 207 159 199 241 212 143 186 148 140 147 112 93 69 97 12 48 30 37 9 33 29 31 37 54 50 20 0 20 44 18 33 67 25 42 17 19 0 23 56 12 39 32 50 64 32 42 30 11 9 0 26 41 0 54 43 20 41 36 17 11 23 14 53 53 44 25 21 40 33 61 35 47 8 42 30 53 89 61 24 53 19 40 164 173 136 159 28 43 49 85 18 67 116 181 193 189 147 156 139 85 53 74 41 52 50 91 139 141 102 113 84 39 56 40 28 26 41 11 0 0 23 56 0 0 21 12 24 36 43 26 48 37 41 31 82 55 62 84 96 71 108 81 87 96 126 95 105 49 86 93 73 91 113 103 102 88 78 85 116 82 93 129 128 84 109 132 133 118 187 127 141 159 171 193 148 199 203 207 213 202 210 173 168 197 156 164 149 131 128 100 65 48 35 55 35 45 6 72 75 52 18 41 0 61 24 51 40 37 41 44 55 38 30 40 6 35 38 0 78 31 24 28 42 44 20 40 10 21 44 7 69 18 13 34 64 13 71 64 0 38 53 11 21 46 52 64 12 25 39 0 21 61 84 36 43 25 32 31 34 167 221 183 199 176 91 93 46 33 100 191 200 191 180 172 102 76 66 11 25 54 46 99 78 89 107 87 19 72 70 24 61 17 7 24 8 21 0 5 12 0 1 27 2 24 52 26 5 61 33 43 66 33 92 61 107 65 120 63 106 70 119 67 91 76 73 75 65 108 116 101 106 113 83 114 87 102 152 113 112 105 123 113 114 134 126 131 144 135 218 180 182 194 212 193 220 214 220 206 185 155 189 154 164 152 85 99 116 57 58 43 80 19 26 5 18 72 58 9 45 22 15 46 6 43 21 43 18 17 12 27 48 23 9 28 17 21 1 17 11 17 29 0 21 47 24 48 11 35 42 31 45 89 26 21 15 47 24 75 17 26 75 75 30 42 56 59 20 23 33 59 29 10 23 0 47 69 205 173 135 167 129 161 80 82 91 181 160 213 224 187 104 60 78 34 76 152 165 79 46 78 96 46 60 77 105 38 29 41 90 22 23 25 43 29 42 23 38 43 52 16 0 7 0 36 69 25 53 38 52 98 72 62 78 104 104 97 82 79 81 72 80 62 104 107 127 87 82 92 51 73 110 113 100 99 98 95 120 106 130 103 149 128 162 140 176 223 215 241 193 239 221 178 197 222 219 203 201 148 142 179 116 112 100 70 82 91 26 43 29 65 62 66 42 69 15 51 23 50 45 42 70 60 48 0 29 12 52 24 0 34 56 57 22 36 30 33 41 24 22 30 46 0 33 31 47 5 38 0 27 0 0 2 40 21 52 25 54 7 12 33 30 14 33 23 15 10 98 65 6 29 21 52 122 175 215 216 145 178 183 148 169 180 205 190 209 237 201 71 65 44 62 20 2 6 75 42 31 66 58 32 68 21 100 74 52 45 98 28 27 4 4 33 31 19 45 0 0 36 3 25 36 36 79 63 38 71 74 65 99 73 65 108 79 101 65 107 96 87 125 90 102 137 115 92 126 119 109 75 81 74 90 89 89 121 123 143 176 146 120 116 92 215 175 197 179 202 255 195 228 204 188 206 182 156 109 156 160 138 137 56 104 58 82 66 50 29 32 76 36 46 49 39 42 82 67 43 23 33 48 49 40 47 6 31 16 8 57 2 56 16 55 19 4 37 16 14 10 7 19 43 17 39 21 20 26 23 4 11 11 56 47 19 20 24 14 20 22 59 18 43 23 6 55 16 24 60 46 57 9 144 171 173 173 200 238 204 171 202 171 201 171 208 170 130 80 56 71 76 33 0 0 35 12 12 41 46 32 36 75 44 66 39 0 25 44 1 8 19 11 10 9 18 19 0 14 35 0 54 41 67 72 78 82 102 72 84 91 79 97 84 98 112 65 118 55 87 107 109 122 95 80 107 103 76 76 78 77 105 121 76 29 109 132 137 118 113 134 154 163 176 207 241 197 172 199 184 235 167 198 165 179 174 171 127 134 134 128 92 64 60 35 57 9 40 57 14 13 39 13 100 20 29 19 48 32 38 39 16 40 34 15 53 33 33 40 47 8 25 48 5 0 31 24 42 38 53 55 6 0 40 29 5 45 34 31 5 41 56 0 17 4 54 16 35 84 50 0 48 8 55 33 11 85 19 34 7 204 170 191 211 166 168 190 200 207 205 217 214 139 146 48 92 63 72 99 58 15 21 44 50 24 0 50 65 50 32 59 43 32 9 0 17 53 16 15 6 0 33 40 34 48 2 45 0 21 64 101 74 53 83 112 126 86 108 95 52 72 78 72 79 39 111 71 61 113 106 95 133 95 69 102 103 97 81 83 99 104 144 122 134 131 143 139 153 192 218 182 235 210 237 197 229 166 228 182 198 187 179 176 120 112 119 107 93 138 99 40 50 36 81 39 27 7 33 39 0 9 18 26 26 36 31 11 3 56 42 28 22 28 22 0 43 1 38 29 62 31 37 40 21 45 39 14 27 78 58 21 16 12 41 27 38 36 7 10 35 43 58 71 36 47 36 53 10 11 59 46 31 16 51 62 14 48 195 199 174 196 190 191 183 193 176 144 188 153 183 144 131 111 96 129 114 72 74 104 69 27 42 0 29 60 47 41 36 45 25 51 36 55 2 12 27 35 7 53 32 2 7 0 4 55 38 66 49 100 80 111 87 117 102 95 106 81 119 72 91 57 82 106 82 75 91 85 106 122 104 92 114 98 100 76 127 122 134 121 147 111 161 145 139 146 159 205 193 213 210 223 169 170 194 207 202 187 157 141 153 154 114 145 129 91 65 69 56 51 69 69 21 50 75 54 48 60 29 44 38 27 0 42 0 14 4 9 63 22 36 19 37 45 83 42 0 12 38 23 71 60 25 34 61 2 33 43 48 69 43 21 29 42 54 37 29 16 26 60 26 63 29 49 30 38 66 28 26 60 23 35 40 44 35 192 179 170 183 246 203 167 193 161 199 143 176 170 119 70 127 119 151 150 94 96 61 87 47 51 52 50 62 54 50 39 29 0 55 16 0 17 11 26 19 35 0 31 0 7 25 34 65 76 70 70 99 79 90 94 97 75 77 133 103 109 76 92 97 90 92 85 84 128 127 84 81 114 108 118 95 80 99 141 76 129 175 109 128 234 127 159 122 165 176 174 212 210 202 207 198 165 225 195 187 162 170 151 142 88 152 93 111 84 74 90 91 51 25 50 25 3 87 2 38 33 49 60 37 50 29 30 42 41 24 31 27 67 34 32 45 57 4 28 46 51 20 16 7 7 52 43 38 6 33 1 42 36 9 28 12 25 24 55 31 43 28 91 53 0 63 36 36 0 33 51 27 47 41 64 9 59 151 179 197 168 206 135 192 149 182 156 168 149 168 60 90 100 164 188 169 198 174 147 122 141 84 35 104 17 78 23 52 27 8 44 14 47 10 41 37 5 13 33 57 36 41 0 0 34 61 72 103 79 115 96 118 127 114 59 103 85 80 99 130 89 111 92 94 92 95 105 80 108 117 137 99 116 122 132 105 111 133 91 152 148 139 150 163 132 194 192 252 220 163 229 186 198 152 163 194 194 130 171 150 133 133 150 128 134 68 66 27 59 48 50 6 46 0 44 20 46 21 59 58 17 47 47 16 29 31 34 54 79 46 64 0 12 8 30 38 17 19 28 24 22 37 3 64 10 0 46 0 5 34 34 47 26 30 6 3 46 33 10 27 41 30 27 38 32 15 34 26 3 35 46 4 6 55 157 153 125 176 179 167 131 181 168 178 197 203 129 91 171 167 221 202 162 174 157 160 164 104 97 90 35 14 28 13 38 26 18 25 47 16 19 29 51 0 29 0 26 26 12 9 0 34 60 106 94 106 74 47 125 104 115 118 96 102 99 91 93 67 98 87 131 105 66 113 103 92 123 101 79 127 116 77 127 76 111 130 112 125 171 160 181 99 165 211 202 240 182 187 193 160 193 173 203 176 155 108 122 157 111 103 89 112 70 63 99 59 25 68 48 37 31 43 64 44 27 21 46 32 29 30 44 28 39 42 22 58 60 19 30 59 37 41 19 59 43 49 41 5 30 11 30 37 19 54 15 43 71 23 45 50 35 58 22 59 42 48 31 53 6 0 65 8 53 46 39 8 2 56 2 82 112 128 141 134 159 175 159 158 154 165 186 169 179 93 57 112 143 214 157 164 186 142 158 145 151 104 63 65 58 51 57 18 35 10 28 20 19 0 25 20 7 6 24 0 45 27 11 25 15 50 37 94 110 110 106 83 77 91 103 124 152 70 97 104 84 97 109 74 98 88 104 123 130 99 93 105 110 112 92 73 98 157 125 110 152 127 164 128 135 185 194 204 223 187 225 195 203 172 217 192 191 154 159 112 159 119 93 103 93 87 103 95 69 33 59 54 28 50 29 24 39 26 51 52 34 52 73 11 34 39 36 66 37 79 34 28 45 32 52 57 41 87 115 69 30 35 47 14 10 69 47 39 22 49 11 44 95 41 17 33 42 29 53 28 18 29 22 80 53 27 54 13 20 26 22 33 2 120 165 190 155 175 185 140 104 88 131 173 134 188 116 95 64 185 179 189 148 172 157 185 148 125 137 86 70 44 40 51 32 0 17 0 17 0 5 51 7 18 70 37 16 0 45 20 10 0 30 46 82 100 79 120 135 103 77 101 109 87 116 117 97 108 97 68 109 56 98 94 82 111 132 152 91 116 132 83 105 99 152 144 116 180 155 146 120 107 203 182 217 224 186 150 221 184 182 176 170 169 169 170 119 130 127 151 109 84 134 79 58 45 25 16 31 48 19 25 9 31 59 32 23 34 49 10 0 32 34 0 31 37 41 21 34 78 60 47 93 56 98 100 92 140 49 28 19 53 45 38 27 70 23 55 43 17 50 0 48 26 51 48 0 43 83 75 91 98 31 47 31 16 22 18 11 28 106 175 194 181 172 133 131 181 84 33 115 115 104 21 60 108 174 183 190 178 139 151 156 144 106 97 88 79 27 49 43 54 26 22 2 15 8 16 0 31 6 27 10 26 48 23 21 30 12 104 74 91 77 87 98 103 118 101 127 95 99 97 104 96 97 96 91 125 100 83 134 116 136 116 101 133 129 131 91 133 98 143 117 185 158 172 107 153 127 136 198 187 216 226 196 193 203 212 168 179 181 132 150 159 132 145 108 98 59 100 62 103 73 23 25 30 25 43 4 35 43 0 31 44 23 65 41 8 28 57 49 33 52 49 73 20 89 46 52 76 121 105 108 84 84 109 92 87 89 28 24 20 38 48 62 20 69 15 40 4 51 55 62 10 46 23 59 82 58 35 64 83 72 23 21 7 0 89 178 174 148 159 174 140 157 168 139 104 74 66 87 96 48 126 181 117 147 135 138 140 87 116 76 52 88 22 31 14 27 9 15 1 27 6 0 8 18 13 33 20 9 32 38 0 39 10 80 128 39 95 101 72 87 91 132 97 134 98 66 112 128 102 114 107 134 123 52 112 126 148 76 96 160 118 96 124 120 121 154 113 120 173 152 156 168 92 141 189 207 164 207 175 198 154 202 167 222 179 134 151 128 149 125 76 76 80 64 71 52 42 20 30 34 13 23 42 27 45 47 75 34 14 53 22 51 46 82 66 71 66 53 31 79 69 42 106 123 103 114 103 113 99 108 123 116 76 49 64 13 22 32 46 44 40 17 13 43 93 43 41 0 29 57 63 0 11 22 53 16 52 26 0 28 66 66 159 147 172 153 157 160 202 199 185 142 100 51 22 62 56 134 144 104 135 117 128 140 110 116 90 37 15 21 22 42 26 7 62 20 0 21 25 24 0 0 18 0 0 43 9 21 35 30 52 111 42 85 121 87 79 117 106 123 116 105 71 77 108 103 129 55 92 58 111 150 127 90 108 91 146 114 122 101 85 133 105 148 147 190 126 165 122 116 103 163 230 196 183 187 189 172 195 140 188 183 167 123 133 114 75 125 106 125 104 81 82 54 47 9 58 39 23 14 80 36 52 74 74 67 67 85 19 84 66 62 58 75 66 28 33 84 79 100 140 71 152 144 99 143 135 97 109 155 108 156 136 29 33 62 20 11 28 13 13 13 50 33 44 17 15 66 25 61 115 32 56 26 27 63 12 57 106 175 147 146 135 117 161 158 215 206 157 142 60 10 36 46 104 137 149 145 137 82 138 109 85 100 76 73 22 26 65 10 23 33 42 45 3 0 36 9 0 39 16 55 55 13 6 50 45 62 119 96 112 125 99 107 86 126 98 104 120 82 119 102 99 102 102 136 102 103 114 130 145 140 112 123 122 126 101 107 183 137 161 134 170 150 118 167 91 96 172 237 148 200 192 166 170 171 187 163 158 107 143 132 152 113 118 60 98 104 81 57 38 39 77 0 43 59 82 21 63 82 85 69 42 58 40 60 90 84 82 118 110 60 106 174 75 80 84 129 137 113 127 130 147 104 98 103 139 155 173 154 168 140 137 99 79 59 39 71 13 14 38 0 33 50 58 26 93 103 120 49 51 49 50 43 109 137 167 149 132 134 83 83 88 106 144 165 113 86 0 39 65 85 104 146 137 80 121 94 64 105 38 64 44 63 38 0 40 27 18 33 22 20 0 58 23 21 33 5 0 28 44 35 48 39 83 70 99 125 135 144 128 125 128 123 138 101 110 115 144 63 73 68 128 94 86 122 133 93 105 127 163 107 134 99 106 116 114 165 140 169 162 153 142 95 123 178 160 189 181 187 181 194 201 176 184 154 147 157 131 91 115 102 99 68 118 128 76 18 69 38 98 57 66 43 78 50 76 50 68 62 76 29 131 74 142 109 87 119 77 97 101 64 100 145 92 91 145 115 104 102 114 122 137 153 186 167 170 190 154 143 125 116 66 80 11 25 84 35 14 43 54 68 42 44 112 114 42 106 20 81 134 159 166 142 153 151 128 168 39 14 16 93 56 120 64 73 70 74 68 116 104 73 126 105 43 73 64 52 72 98 48 15 35 22 0 0 23 20 13 8 14 42 24 9 5 0 24 58 23 56 102 63 113 89 142 149 75 101 131 93 135 110 125 108 90 123 119 135 78 141 123 128 128 134 111 145 129 128 144 144 114 103 129 149 145 125 155 130 152 140 96 94 114 197 204 155 158 154 204 136 183 130 143 138 113 163 113 104 127 96 100 31 68 35 31 63 51 1 3 0 71 32 89 69 68 64 81 73 71 109 97 66 106 107 120 97 90 103 109 71 81 137 132 114 115 84 100 143 103 126 158 200 144 201 174 149 180 162 170 108 119 90 26 24 47 70 53 90 53 17 29 109 38 47 68 68 74 168 196 175 145 185 154 173 177 144 187 45 42 0 50 32 46 75 42 78 61 99 57 68 118 57 51 64 55 92 23 49 57 27 43 16 12 29 7 4 19 14 33 52 37 36 0 70 9 34 25 90 76 84 141 77 119 104 123 103 91 152 130 134 125 159 122 96 74 138 104 100 108 128 107 104 125 136 113 105 76 134 98 150 150 196 127 146 131 137 130 124 121 125 113 137 171 207 197 152 171 187 151 132 112 99 159 108 97 114 92 108 104 94 101 32 26 55 14 15 59 94 89 114 71 121 70 31 71 37 72 71 93 100 93 129 90 120 59 122 102 157 137 127 121 28 139 134 132 157 117 134 173 196 192 190 174 164 206 209 119 172 177 164 139 136 129 157 133 92 82 56 132 20 56 55 47 138 195 198 196 210 150 174 151 208 176 163 146 112 72 10 13 26 65 54 71 65 52 49 55 50 68 68 73 49 62 51 47 44 34 46 20 33 9 18 25 0 15 39 2 16 72 22 84 40 76 80 75 113 105 98 80 102 125 101 82 125 114 113 125 108 97 122 78 116 123 95 107 83 113 123 117 90 130 100 148 94 119 146 171 151 136 113 172 122 140 131 95 86 111 120 182 194 144 151 175 180 107 144 174 138 81 106 111 86 119 98 114 90 50 49 31 62 4 67 71 97 33 74 43 68 73 73 95 74 86 125 110 121 157 120 68 98 96 113 97 112 105 114 114 54 149 124 118 105 81 119 167 188 173 171 192 174 197 173 204 237 169 190 180 184 210 162 152 188 187 181 148 83 109 118 130 135 199 201 217 204 176 147 149 181 187 194 127 62 61 61 64 50 21 46 79 59 36 45 30 19 48 37 74 43 87 75 48 60 59 49 47 0 19 0 39 0 47 34 19 58 11 9 64 72 92 68 77 113 120 70 101 138 131 62 104 146 80 92 120 112 93 109 121 90 138 134 104 102 81 132 146 132 91 124 120 118 130 105 125 151 151 190 172 141 153 133 94 91 70 81 108 152 146 181 179 167 162 146 124 162 77 75 99 89 82 81 64 48 85 76 65 56 26 60 71 95 80 51 78 98 87 31 47 76 65 101 51 99 117 117 106 99 157 78 106 94 177 166 111 93 69 100 110 142 141 107 158 152 192 199 188 170 204 222 182 199 155 189 196 231 203 157 203 199 173 207 185 175 114 159 140 127 166 184 193 222 209 180 166 177 191 223 220 119 107 40 60 30 71 79 95 84 29 51 62 96 37 58 65 84 25 33 77 45 46 26 55 70 17 19 12 0 19 41 40 32 0 21 9 23 87 103 119 116 89 93 106 95 77 106 104 135 114 101 92 126 154 117 114 78 90 80 96 129 97 94 135 97 132 108 129 134 114 124 88 116 171 165 160 169 166 145 148 122 87 82 115 99 108 122 154 133 138 167 129 150 125 137 83 86 118 103 100 100 87 108 80 48 113 41 75 82 71 61 50 61 91 109 126 89 97 84 114 124 94 111 157 122 113 111 90 107 107 165 104 139 108 124 60 86 105 145 116 99 127 190 198 190 175 178 212 209 178 169 211 213 161 184 204 204 168 197 194 169 234 180 180 175 181 155 174 175 206 223 217 180 156 159 118 185 220 139 41 14 77 77 56 70 54 52 41 28 31 44 53 62 50 96 33 59 73 59 32 32 42 16 10 0 35 14 1 0 5 0 4 37 22 77 101 112 121 113 100 94 83 157 116 95 119 127 89 119 91 89 131 92 96 105 77 123 104 119 127 147 141 150 140 144 98 137 133 121 130 159 134 150 185 154 158 138 134 102 85 72 120 140 85 140 111 125 123 123 110 137 145 138 62 73 49 124 72 106 87 87 95 60 84 79 66 77 59 91 91 112 57 74 114 103 95 115 100 76 96 89 131 167 145 111 116 157 130 99 135 109 71 110 96 122 139 110 126 127 209 187 224 198 212 213 205 208 173 198 216 196 251 176 242 192 215 187 203 172 175 209 190 194 197 146 227 198 218 231 204 200 156 199 211 243 214 145 35 63 74 54 58 42 44 100 41 53 30 52 40 30 42 78 33 18 36 55 46 16 24 0 13 8 24 32 0 28 0 18 34 47 135 102 77 125 115 122 84 99 109 105 106 85 130 130 56 113 116 86 84 146 126 113 116 112 117 116 135 128 111 153 114 138 139 122 161 123 170 118 178 112 145 131 138 84 61 77 109 58 91 128 123 138 125 151 129 103 91 111 123 147 110 86 143 61 99 104 80 76 76 86 66 101 80 77 85 71 63 54 71 98 94 102 113 138 137 119 134 126 169 111 125 136 122 100 147 147 110 52 81 121 144 161 121 105 139 164 193 194 204 193 178 186 205 224 195 177 195 243 219 217 151 205 216 235 167 145 218 212 197 203 188 241 242 199 188 195 159 189 161 190 161 160 140 123 73 50 78 113 40 79 72 46 47 75 71 36 76 28 29 22 15 6 25 37 15 8 0 28 1 0 33 8 0 4 13 30 71 79 99 88 112 133 103 111 162 107 70 91 115 98 122 124 108 116 127 153 110 118 130 136 160 117 104 119 92 135 146 124 130 126 119 125 71 140 134 147 155 128 148 167 83 74 70 79 113 89 83 113 115 123 128 147 141 116 111 132 102 104 71 137 79 68 104 84 96 101 72 74 93 93 54 71 94 94 97 84 148 122 118 84 153 133 96 144 99 166 85 132 130 78 122 157 119 47 79 130 96 120 131 115 138 146 172 198 215 201 208 195 221 173 165 204 210 223 202 188 180 237 217 224 216 203 172 188 216 209 179 219 242 179 201 181 202 162 142 190 165 215 183 146 121 81 91 60 74 60 18 45 64 84 74 53 68 74 0 55 0 1 4 6 5 33 12 0 0 0 13 42 32 60 44 43 69 94 83 123 90 97 104 91 74 128 97 81 75 127 120 121 126 138 115 128 109 97 136 114 105 114 124 120 128 94 149 103 119 86 136 152 129 106 129 141 136 103 199 182 128 87 55 51 108 50 108 162 79 134 114 96 153 122 121 137 97 116 138 77 83 57 94 74 112 94 92 73 99 92 107 73 70 46 77 108 108 74 114 134 106 98 88 77 110 100 114 130 139 113 121 141 126 136 91 81 119 108 122 84 113 139 161 165 230 191 172 156 213 177 219 225 169 203 215 212 199 204 225 206 185 215 219 206 191 181 185 199 221 222 197 191 172 161 203 194 110 155 161 134 136 74 101 90 77 87 73 62 70 59 27 73 66 57 28 33 29 4 67 4 26 28 0 0 30 22 0 22 48 37 41 25 54 77 87 80 87 101 118 124 78 87 125 110 119 123 106 120 125 141 121 102 106 126 113 139 118 133 119 126 138 143 123 114 112 103 138 108 126 140 100 127 118 146 132 168 162 140 56 63 92 120 55 98 79 92 106 100 124 103 104 134 108 118 100 98 96 53 74 99 77 91 61 65 105 71 103 115 65 119 88 73 66 121 119 74 69 127 130 114 119 120 181 142 115 150 155 131 132 164 94 111 95 120 128 117 129 92 150 132 127 181 185 224 202 178 219 171 190 193 201 239 183 213 200 202 208 189 169 200 174 222 185 214 175 178 236 231 190 211 218 159 189 146 112 129 108 73 84 91 99 60 56 62 90 83 54 68 29 59 57 35 10 32 27 31 0 16 39 24 0 14 16 31 28 43 101 109 27 63 101 79 81 129 76 94 105 112 107 95 136 102 131 64 105 99 90 130 127 92 100 110 119 141 125 109 95 140 108 137 147 144 96 150 153 108 116 144 126 124 110 144 145 124 140 50 54 102 89 95 64 110 91 122 83 74 80 114 87 146 108 81 91 78 110 117 76 99 79 65 96 43 92 87 60 122 115 83 54 76 118 97 120 82 100 108 110 99 121 148 113 160 127 135 147 115 136 124 106 120 112 152 89 144 95 111 141 161 143 197 235 224 149 180 206 229 198 220 177 244 175 201 198 229 202 188 202 206 195 192 202 223 214 223 204 180 178 202 161 215 196 198 88 106 63 77 82 94 130 90 71 114 48 42 90 34 21 42 31 0 5 3 9 19 24 0 26 53 17 30 41 38 50 64 66 71 120 107 141 93 118 117 121 72 127 115 94 101 104 101 105 79 97 94 92 92 145 137 121 145 111 134 157 143 126 149 141 113 144 107 117 112 138 148 135 113 138 134 133 170 140 158 65 59 72 85 68 81 95 132 56 87 57 81 117 91 104 89 74 89 117 75 108 89 84 113 52 64 126 143 69 11 68 113 74 76 94 91 159 99 96 75 112 91 136 145 116 116 101 123 121 111 146 138 94 88 102 88 112 105 127 100 127 141 131 131 219 209 192 171 230 201 211 202 200 233 251 240 204 227 178 227 204 202 226 160 210 189 212 167 185 187 206 255 193 193 197 198 190 200 123 61 166 87 86 110 76 61 76 39 28 33 63 22 61 45 24 28 0 12 20 7 7 7 54 9 49 62 10 37 120 113 111 85 100 72 141 118 104 89 114 118 93 109 127 80 83 114 97 134 119 81 118 158 110 96 81 118 132 143 120 103 109 132 105 126 96 91 111 110 124 115 112 109 117 105 153 163 100 64 69 120 39 110 71 88 86 116 89 110 105 41 54 84 100 101 82 80 63 73 96 70 101 91 71 57 58 94 90 37 60 103 98 132 78 88 102 112 108 93 131 138 117 82 115 121 134 137 154 102 127 101 79 95 95 102 83 87 91 131 117 133 143 207 216 186 170 217 219 199 164 179 224 201 184 235 179 211 224 230 167 233 203 208 213 198 188 193 219 217 165 188 189 221 211 190 202 205 192 110 33 27 59 28 59 8 14 26 23 45 25 17 42 25 3 12 9 19 43 25 12 48 0 0 35 25 30 95 94 99 112 95 118 126 115 76 101 121 95 105 86 113 129 97 108 86 116 156 93 105 101 95 64 131 125 144 118 79 95 152 115 83 106 163 108 172 128 105 140 120 134 133 102 137 171 102 53 87 65 126 49 76 113 114 97 99 133 105 109 90 78 86 126 72 52 66 71 66 65 55 98 44 106 61 85 108 111 47 90 112 128 109 123 101 86 125 89 77 151 154 80 134 150 131 155 133 96 106 99 90 141 140 144 95 109 104 121 100 137 162 178 208 190 199 185 221 199 200 222 197 190 177 174 224 255 243 197 242 218 198 186 199 201 201 211 204 242 248 163 218 180 218 166 218 209 138 169 124 81 43 45 68 50 83 29 47 49 24 22 19 3 0 0 0 21 41 11 13 0 18 16 0 24 80 101 115 116 119 109 112 77 99 60 78 132 50 85 93 81 135 75 106 114 92 126 107 100 99 67 153 112 112 114 133 94 103 168 135 149 118 107 103 96 107 102 134 129 112 121 123 120 121 65 78 70 83 69 105 84 90 101 108 153 133 80 111 71 75 87 75 85 108 55 67 69 96 65 70 54 134 93 52 81 62 60 91 87 80 105 98 95 101 73 91 127 135 103 104 133 128 109 109 79 112 72 119 82 82 90 125 150 118 146 84 118 111 102 151 143 184 192 226 166 215 236 227 207 196 178 181 195 227 241 239 224 214 208 204 216 192 202 179 218 228 182 216 200 172 189 185 199 177 157 147 176 141 61 76 57 82 56 45 46 48 12 41 0 20 45 13 49 0 37 2 19 0 0 22 49 16 37 82 73 104 123 84 108 26 52 87 95 62 101 70 89 110 92 87 83 106 124 90 91 133 100 110 86 104 118 106 119 100 136 116 145 139 123 123 106 130 103 101 74 130 140 113 120 160 131 120 29 49 74 94 56 74 113 80 104 83 92 121 133 101 109 113 109 58 109 113 88 116 89 69 69 67 109 81 80 70 82 84 101 89 64 115 96 101 125 95 104 133 133 100 117 102 126 128 147 130 104 66 126 134 130 126 127 140 122 98 114 134 176 148 150 193 201 201 206 214 198 220 211 180 187 209 242 190 206 232 198 241 202 180 198 244 193 201 207 182 190 212 217 218 214 196 196 229 212 198 130 142 107 106 105 41 99 36 35 24 39 15 22 1 14 9 7 29 21 17 0 2 39 13 16 37 62 118 50 63 127 123 108 78 92 90 130 94 137 93 73 95 82 85 88 98 96 66 105 100 128 122 67 150 128 98 121 89 97 127 127 112 131 109 140 125 103 105 131 140 86 107 156 119 108 150 96 105 44 96 69 67 65 62 96 45 117 68 101 82 93 81 120 83 102 84 62 94 64 77 76 63 80 100 76 88 87 82 76 80 79 82 127 97 109 140 155 123 117 115 101 135 114 95 135 176 118 135 121 108 113 109 102 106 137 103 115 101 69 90 129 127 142 195 162 202 185 212 223 192 211 255 196 206 196 162 207 210 172 202 198 198 181 211 184 182 232 194 210 212 235 168 204 176 170 162 161 154 116 117 126 82 82 86 38 55 37 42 9 30 43 28 30 0 15 0 2 35 41 41 67 99 136 87 60 89 80 78 145 78 76 73 96 78 95 81 117 99 107 65 114 138 98 82 107 84 77 102 125 98 78 73 104 120 111 100 93 144 101 123 113 122 120 154 94 122 114 124 147 140 92 91 113 91 46 77 62 41 73 45 68 77 67 101 92 72 79 76 66 96 76 105 107 91 87 104 78 99 93 71 75 88 47 106 63 60 85 104 110 91 86 79 104 100 146 130 96 112 147 140 134 112 116 79 127 96 111 114 120 126 85 121 123 111 98 80 142 129 126 130 159 178 183 247 184 185 192 204 176 223 220 195 218 188 188 214 194 228 208 219 176 208 182 192 199 200 198 194 196 200 175 184 166 161 139 115 78 67 80 83 68 36 74 37 0 22 26 45 17 9 0 39 7 54 21 58 46 55 61 81 103 119 80 76 106 123 75 46 82 59 85 142 93 83 103 73 70 66 98 86 105 88 102 97 113 105 101 100 115 113 102 108 86 113 148 102 126 167 110 141 137 93 117 131 129 91 147 93 129 142 78 55 76 53 39 56 67 48 64 76 93 83 70 70 28 96 64 89 60 65 48 89 72 71 95 89 100 80 106 56 48 105 81 39 92 110 73 49 73 90 100 136 96 68 98 121 87 120 98 116 96 106 101 99 119 120 122 125 143 103 92 129 69 136 137 149 126 152 208 212 206 191 230 198 208 243 181 192 210 208 181 222 235 188 194 203 209 177 175 214 218 212 185 186 187 203 184 184 158 188 157 127 125 71 75 116 57 78 38 33 0 11 25 2 0 30 40 19 28 25 67 46 36 75 28 69 93 94 81 74 105 141 102 129 119 105 104 121 108 87 106 116 124 81 86 65 81 117 78 87 102 82 111 110 96 103 102 99 113 105 122 118 131 117 159 108 114 139 101 150 118 138 133 102 164 154 163 26 95 65 83 64 100 44 61 43 21 62 62 91 68 94 92 49 97 81 61 74 67 68 81 82 63 113 36 76 100 84 111 76 90 88 82 91 99 112 100 120 99 110 99 135 110 92 107 70 103 94 91 100 102 69 105 113 167 106 128 114 145 109 128 133 156 123 181 159 201 202 189 189 214 234 179 222 211 211 212 200 179 204 216 202 181 200 200 187 236 229 229 183 208 208 184 207 177 167 168 134 114 122 124 102 77 56 83 29 62 52 0 27 23 50 4 19 10 51 44 44 73 78 83 58 62 92 98 150 103 95 89 85 110 90 126 115 116 87 129 115 113 98 128 144 106 112 98 113 105 112 118 124 81 125 130 124 120 134 127 124 115 174 119 107 134 136 124 126 95 107 73 117 131 130 141 118 54 87 88 48 90 77 26 62 40 56 12 69 72 70 66 25 83 70 82 66 84 67 79 53 80 91 100 71 99 83 93 73 63 62 89 105 58 93 113 126 85 72 105 117 89 135 116 165 75 114 119 132 118 113 113 62 112 168 128 88 111 120 125 85 149 104 148 150 124 179 191 222 214 244 253 234 179 188 232 186 196 189 193 192 155 203 172 192 196 141 227 174 210 200 214 170 195 168 160 143 165 137 127 89 82 132 65 37 58 40 7 21 18 11 13 21 0 51 41 47 54 124 55 48 80 11 86 79 113 121 115 96 83 124 120 117 155 144 109 105 106 130 154 131 108 110 137 132 85 116 138 123 100 128 79 84 114 124 125 133 123 133 142 142 145 108 77 112 138 100 119 82 135 140 111 143 104 60 56 85 50 74 57 53 52 44 33 68 71 65 59 49 49 36 45 74 58 97 90 120 67 62 72 57 84 96 95 52 96 116 84 91 104 103 81 81 133 98 87 71 106 115 132 89 111 89 137 81 157 114 143 101 116 113 156 107 136 108 92 153 118 144 131 177 164 124 167 185 192 196 244 206 216 194 198 245 169 203 161 228 240 243 188 193 188 188 211 198 177 143 175 177 202 183 198 163 161 119 133 87 106 86 67 86 38 27 57 5 27 10 31 26 30 18 41 68 37 34 45 16 80 47 36 47 81 97 137 108 118 94 99 114 134 148 102 111 118 141 68 117 133 145 79 107 85 168 126 115 108 121 89 90 128 120 134 87 110 96 137 127 108 138 102 124 118 139 143 123 109 81 122 116 130 71 24 56 103 52 65 91 81 62 56 63 68 46 50 64 33 30 49 12 25 74 39 38 67 35 89 71 105 100 68 102 97 72 53 61 77 80 95 73 119 90 104 93 100 121 120 115 91 130 128 81 114 102 119 59 25 92 116 129 126 155 83 106 128 123 141 114 145 120 138 138 135 162 204 190 195 206 205 193 179 169 177 204 229 188 205 194 196 192 186 182 220 179 161 173 179 177 162 136 188 169 118 124 97 98 70 110 68 96 66 24 41 1 7 27 20 9 0 21 34 29 58 17 71 46 33 60 13 73 67 94 126 105 108 122 128 100 101 137 137 122 125 99 177 127 103 136 125 116 112 92 69 96 80 85 110 111 128 140 119 106 80 144 120 125 120 133 113 123 106 106 133 100 132 109 111 102 75 61 67 40 51 34 20 59 69 103 53 59 70 10 73 63 56 59 35 45 69 23 35 24 39 64 73 30 22 62 86 99 47 96 114 72 76 82 108 76 129 99 63 102 101 114 142 137 87 125 126 88 119 75 90 91 89 96 118 94 154 113 125 96 123 151 167 123 138 164 158 190 185 155 148 179 184 196 190 203 184 201 164 232 215 160 177 186 205 197 197 181 179 133 140 137 166 195 159 175 146 138 128 113 71 109 99 130 46 17 0 14 24 32 8 1 57 13 11 43 51 21 52 47 23 65 26 2 15 60 104 93 112 91 108 100 136 108 136 112 113 140 116 130 118 100 129 49 99 149 94 103 132 118 81 116 132 141 88 137 117 125 103 157 125 142 109 127 88 135 137 107 111 119 108 152 105 74 40 65 34 43 32 73 58 45 69 72 53 69 32 48 76 105 16 48 39 40 63 80 17 38 69 59 22 67 33 43 29 61 72 28 36 98 76 78 74 65 129 83 91 105 112 138 105 123 109 131 121 106 98 76 86 166 124 122 128 138 152 109 148 167 152 139 125 143 139 162 152 152 191 185 174 218 204 222 221 206 158 219 149 194 184 193 166 192 227 149 171 172 153 168 113 142 167 119 148 136 147 84 128 96 153 99 85 29 45 17 36 29 6 21 0 39 37 46 22 13 51 0 46 45 47 27 9 26 33 59 115 122 99 90 134 105 161 124 97 168 136 144 146 132 132 100 98 95 82 91 137 86 125 104 102 176 142 144 165 128 121 106 115 142 78 143 115 91 144 92 135 129 134 102 147 104 103 33 45 32 92 54 31 24 60 67 44 46 85 58 68 59 52 46 16 54 29 78 40 34 40 55 60 77 68 39 14 52 36 2 23 54 62 98 100 82 91 90 67 87 120 98 123 102 90 95 115 149 124 89 70 90 123 120 134 146 110 105 131 107 111 148 167 129 130 163 130 158 146 136 152 177 193 197 187 214 198 191 181 208 181 178 186 208 174 185 237 194 155 150 154 131 182 133 149 127 105 123 100 117 83 129 64 70 73 33 65 4 0 19 16 34 39 68 54 46 34 66 41 71 54 39 16 51 11 37 36 116 115 97 123 128 148 163 115 123 115 142 112 134 143 102 114 108 128 113 122 122 170 107 132 134 136 124 105 119 105 150 152 141 140 144 148 106 120 109 101 104 143 138 83 86 142 109 33 21 75 83 56 36 46 67 31 46 64 47 52 49 89 37 35 62 54 51 40 32 69 21 61 17 25 32 35 34 76 17 5 36 14 45 75 94 63 63 61 101 76 109 124 79 67 101 102 93 122 72 101 33 79 106 138 121 185 149 153 107 138 146 122 98 160 131 140 128 146 144 143 195 190 194 203 181 200 194 225 201 193 202 234 155 193 173 214 222 167 160 157 186 193 130 133 129 128 94 109 98 102 93 74 65 78 55 35 41 19 73 26 59 10 46 0 69 37 35 20 22 29 53 29 18 42 66 48 34 38 43 155 123 116 123 131 149 133 184 125 160 95 96 125 128 130 103 82 106 152 126 119 85 123 81 108 93 112 85 116 103 105 110 167 85 154 113 164 135 103 108 108 126 141 114 89 21 74 60 59 58 64 52 79 47 52 81 37 77 56 65 89 22 36 49 71 81 58 80 41 72 34 66 24 48 21 18 42 24 1 32 17 26 64 62 78 88 56 111 120 84 112 115 72 50 87 56 60 56 66 108 96 140 140 140 138 128 113 141 120 110 123 150 114 129 128 167 165 133 141 135 174 205 190 173 205 244 199 202 203 192 181 203 205 201 198 202 184 137 183 128 175 154 165 141 138 101 130 74 79 72 66 83 27 89 22 36 0 11 11 87 5 0 0 25 53 35 64 23 69 55 52 42 0 63 24 50 93 152 169 142 105 179 153 158 123 133 142 118 113 129 96 129 89 102 137 108 110 85 121 120 134 111 124 124 89 110 119 134 87 119 128 139 100 161 176 95 100 119 114 128 105 120 59 69 39 73 98 37 76 77 46 47 43 45 71 76 80 53 81 33 36 27 38 37 59 61 34 82 48 48 46 41 26 48 0 42 0 6 0 59 0 1 94 86 108 71 95 50 72 70 77 88 52 94 90 61 161 129 154 130 145 161 158 130 102 138 152 129 121 135 131 140 112 143 148 160 171 135 177 162 193 162 190 175 198 183 206 176 176 203 201 213 194 204 176 173 174 196 196 161 97 104 123 90 107 58 109 89 108 107 73 97 35 80 65 32 0 0 17 32 0 33 59 28 61 34 43 38 50 31 0 19 75 39 45 100 109 121 134 141 120 146 174 130 105 138 138 158 116 91 140 100 104 135 147 135 152 120 108 89 90 108 81 159 111 111 167 134 173 120 152 91 80 148 128 111 112 151 121 89 62 95 46 34 67 85 79 73 45 55 35 47 44 81 69 72 47 38 73 19 38 37 48 65 48 32 63 42 44 46 8 0 0 18 8 20 71 65 35 67 65 99 90 66 65 72 81 76 53 44 61 109 152 132 149 131 152 143 161 152 140 148 119 118 158 153 155 129 147 135 173 135 191 131 122 133 182 198 183 171 180 245 196 218 205 199 247 208 185 165 167 195 179 204 174 187 146 157 169 106 131 125 74 60 106 99 88 103 92 50 76 30 44 22 38 34 49 0 14 13 51 0 42 15 39 23 49 10 37 69 127 46 80 114 121 131 70 133 129 117 129 124 100 111 108 84 129 130 140 105 122 140 145 110 142 135 120 104 101 98 120 113 114 199 94 84 107 126 110 135 120 90 116 90 135 102 43 75 58 43 47 81 113 65 41 79 32 57 20 17 71 44 55 62 102 77 58 68 46 18 15 50 67 47 68 83 53 31 0 0 1 9 0 71 39 23 66 57 101 126 77 70 47 70 59 27 83 128 116 82 130 126 98 131 92 178 140 119 160 124 139 111 136 161 148 128 169 149 152 159 129 152 187 208 169 177 180 231 188 216 229 182 207 205 159 178 208 167 221 187 203 226 197 204 169 152 181 175 109 126 115 78 92 91 51 65 94 39 54 39 35 36 1 53 0 11 49 6 47 48 84 48 73 79 60 32 46 79 73 69 75 102 122 117 161 127 127 101 136 131 132 114 149 130 108 79 106 112 117 98 137 130 149 108 170 126 134 136 84 129 129 99 146 113 130 135 125 127 90 128 127 125 111 90 104 69 93 68 89 39 84 63 45 75 28 63 56 94 51 71 40 67 63 37 58 105 67 24 62 39 27 67 48 80 17 0 30 33 21 6 86 22 44 69 46 78 76 36 59 21 57 34 38 74 91 122 116 97 141 129 128 136 154 132 107 88 124 121 118 147 179 141 112 146 149 145 178 162 151 134 132 184 166 173 155 168 179 173 190 189 182 189 200 194 235 208 241 227 199 237 191 183 156 139 175 174 126 113 100 97 100 87 78 113 75 68 72 18 33 32 8 34 35 42 35 47 59 42 64 59 57 47 59 62 95 73 31 18 62 61 162 126 164 125 157 101 152 90 112 98 121 87 134 85 121 127 136 126 142 119 183 109 113 105 143 126 121 157 127 117 118 144 133 123 100 119 131 122 122 105 117 67 55 19 100 78 73 96 80 91 53 55 59 82 72 62 80 86 75 75 80 66 64 41 62 55 30 74 50 37 36 33 18 47 34 43 34 40 24 33 51 59 111 64 24 72 12 44 5 66 71 73 55 120 136 146 145 121 120 142 120 147 139 116 136 120 127 132 142 157 153 143 178 102 162 138 137 144 180 154 223 196 216 227 199 187 212 195 195 208 194 244 197 223 216 220 198 189 169 177 182 193 134 172 86 88 115 96 80 76 73 51 76 80 61 52 76 35 30 40 40 19 45 28 55 66 52 30 68 63 91 54 49 38 59 25 51 49 120 114 91 84 145 90 81 100 105 76 99 117 139 110 117 113 90 128 131 116 118 115 141 161 158 136 138 133 111 137 135 120 79 128 138 113 110 119 98 74 97 70 81 81 38 71 51 88 103 80 61 77 93 82 83 40 35 59 48 92 102 72 94 58 40 32 73 58 35 42 34 45 2 8 33 0 51 41 42 82 53 86 35 15 21 55 59 75 95 90 96 128 131 149 208 132 194 142 108 106 133 133 138 131 155 137 130 155 150 139 141 163 126 178 185 136 175 141 143 173 178 200 208 147 219 183 194 199 203 188 208 255 190 200 234 230 191 185 169 172 187 141 147 138 72 121 68 102 110 108 80 91 84 73 129 58 20 58 29 34 29 74 32 54 54 43 33 69 45 83 62 76 91 73 33 40 73 59 81 135 90 67 125 106 111 169 133 93 131 153 131 116 126 149 67 118 114 165 120 98 115 128 145 130 137 138 120 104 107 114 97 103 166 89 121 100 97 77 86 78 72 23 58 93 49 71 72 94 91 85 90 39 70 49 66 80 45 78 78 35 45 86 36 85 56 23 42 0 0 23 19 28 31 82 0 59 0 55 68 54 0 14 39 108 86 67 125 88 115 143 149 151 113 141 118 127 125 129 154 166 118 134 107 123 130 143 137 155 152 155 151 158 133 187 173 151 184 208 219 230 229 248 238 164 178 222 225 223 192 206 194 213 163 238 159 180 201 190 147 181 139 105 143 91 121 117 94 96 96 73 78 66 51 33 74 29 18 104 81 52 53 61 17 65 67 51 111 78 69 33 33 20 79 74 26 86 104 55 94 100 94 102 97 122 109 120 145 144 89 93 158 128 76 109 136 122 137 124 123 88 133 149 160 127 173 87 112 125 103 81 103 98 116 104 97 98 81 91 72 69 70 84 54 60 59 69 87 79 77 86 43 66 62 66 33 51 67 36 90 44 54 22 76 27 3 63 27 70 16 24 52 27 66 1 40 42 26 21 35 54 104 97 99 102 94 130 120 160 158 152 171 152 112 109 166 157 117 161 108 137 146 110 168 166 151 129 162 142 116 181 118 141 185 133 196 165 162 176 199 186 194 252 252 191 191 208 197 223 222 165 204 193 141 182 138 198 164 156 147 130 112 109 96 110 110 45 99 78 118 82 63 15 14 85 40 64 22 17 27 3 16 10 5 112 77 43 48 75 36 56 46 46 36 102 87 133 147 94 97 93 111 81 94 102 140 124 124 128 163 151 117 132 143 104 156 154 104 135 138 160 97 93 126 136 121 117 141 136 115 96 109 136 66 90 106 75 79 62 37 82 62 77 41 85 75 60 78 68 65 71 85 82 65 56 101 44 47 32 78 19 28 66 52 3 21 6 0 31 27 0 23 0 72 18 0 27 63 99 95 100 104 104 114 142 132 153 154 112 144 120 117 126 109 144 126 118 142 171 160 142 144 144 179 146 145 144 142 145 195 148 183 168 183 175 220 216 209 199 198 242 206 176 215 226 227 170 209 169 206 140 185 210 192 182 154 114 150 154 154 93 76 70 82 81 71 113 99 44 91 91 73 84 55 79 50 16 63 23 10 60 72 77 0 67 45 51 51 85 57 91 47 80 120 89 84 104 106 90 83 118 112 85 106 117 114 144 111 124 111 117 132 166 142 139 102 173 133 105 107 96 132 136 115 97 135 125 135 119 138 90 109 98 114 51 104 68 47 96 61 63 69 70 72 100 90 74 86 55 59 67 58 94 57 54 67 58 48 35 77 52 38 42 19 10 0 0 27 0 11 27 63 43 125 65 78 145 148 131 157 139 126 161 177 179 165 220 128 172 124 130 130 130 147 134 156 143 164 164 130 139 150 145 148 117 124 136 133 130 174 139 205 163 217 197 167 198 242 202 201 216 204 201 210 206 200 196 181 173 168 183 136 160 144 136 172 143 102 114 128 90 98 87 92 65 114 83 140 114 99 105 79 81 38 44 55 79 26 109 126 37 75 61 58 33 33 68 69 55 84 32 113 130 80 125 91 98 128 94 123 100 79 126 99 95 81 104 94 121 122 116 98 130 145 103 159 128 129 132 101 179 165 150 169 115 116 135 125 99 129 83 103 94 44 48 86 59 66 33 116 67 69 64 61 17 96 78 77 75 77 46 58 45 42 36 55 60 39 57 52 27 17 39 26 26 17 40 12 0 97 91 109 123 120 109 96 168 113 161 154 179 159 169 178 162 133 146 118 155 145 166 149 132 156 156 158 120 134 159 164 150 155 148 152 149 137 173 166 159 152 174 195 197 182 221 196 197 215 175 191 192 193 166 190 189 184 153 172 148 127 120 144 135 135 113 124 91 104 116 115 68 68 83 117 106 104 104 114 96 96 47 56 33 39 46 63 129 69 75 52 101 32 47 74 34 83 90 80 97 107 141 119 95 111 138 121 102 115 142 107 91 135 121 74 95 92 122 177 157 182 148 158 143 117 145 149 129 156 114 166 140 114 114 112 81 109 149 58 102 85 120 95 85 79 47 82 97 61 58 62 92 57 103 46 36 70 72 69 50 83 35 54 22 44 85 4 9 27 0 33 18 39 28 24 32 69 118 77 105 95 151 108 67 112 145 141 156 142 155 195 192 152 165 146 155 137 162 143 162 142 132 149 164 127 140 148 140 126 128 153 109 167 163 179 139 190 146 117 158 202 168 202 177 247 199 163 197 212 186 199 183 183 152 179 192 166 161 160 121 135 110 124 104 115 107 105 88 70 67 68 99 136 102 101 59 75 67 69 35 40 81 19 31 150 94 105 52 41 54 63 79 55 72 88 60 50 104 120 71 94 95 120 110 97 141 102 96 145 141 112 107 115 126 140 127 143 133 131 159 150 118 100 124 180 178 138 138 192 163 113 84 153 100 79 98 111 111 83 117 46 104 102 87 115 97 56 67 71 48 71 81 103 68 36 41 56 65 17 24 51 9 60 38 12 0 14 25 30 9 24 24 59 105 103 105 122 117 124 127 148 95 135 169 149 152 141 142 167 175 183 143 133 152 161 137 143 126 166 139 161 136 142 131 137 155 108 150 120 138 136 190 161 146 187 146 157 163 143 224 168 176 202 178 158 182 203 188 143 142 190 131 173 162 186 155 143 132 132 145 110 96 103 83 91 58 131 96 111 66 76 69 87 14 42 50 22 51 46 68 51 92 118 75 33 50 52 85 79 63 36 102 94 77 39 88 114 115 103 103 115 91 120 78 85 162 132 133 136 106 116 168 165 123 165 142 143 134 100 155 146 142 155 158 125 123 120 111 110 110 117 100 120 160 59 109 81 99 104 86 97 125 54 73 83 86 81 92 120 49 49 71 44 72 26 45 64 87 49 59 44 0 0 38 26 26 0 0 0 38 119 81 91 104 106 170 99 128 153 122 153 130 172 147 158 166 196 157 142 166 145 144 144 181 119 135 151 141 146 155 99 143 150 155 146 124 137 132 165 138 168 139 150 172 175 172 140 181 181 175 190 191 184 177 156 175 176 147 163 174 183 152 169 94 119 150 116 96 103 85 92 104 72 110 109 49 114 0 110 66 55 30 48 73 39 62 62 64 71 82 130 42 57 66 42 52 67 31 59 73 79 76 91 78 79 120 124 135 110 149 133 104 107 106 111 130 87 128 109 133 134 146 128 155 107 148 162 130 126 153 152 142 145 145 126 102 107 118 95 87 118 102 82 122 90 61 82 81 86 83 61 96 62 73 72 89 51 81 67 37 69 30 49 71 45 14 56 46 55 51 9 23 19 26 59 0 87 67 89 81 105 124 114 115 143 137 169 176 210 180 159 177 195 210 163 146 194 134 92 180 142 132 97 148 148 159 157 150 114 144 107 139 120 120 157 109 155 126 151 176 207 168 120 150 186 184 180 192 183 201 194 186 207 145 202 173 155 138 131 128 146 129 140 142 111 84 96 87 63 104 132 52 107 95 53 61 67 61 77 31 75 52 80 54 60 45 132 102 99 40 45 33 92 80 74 82 75 42 78 77 94 104 160 115 86 110 126 121 85 114 102 140 117 96 123 129 126 161 176 130 137 128 134 181 123 131 174 150 124 130 175 117 113 100 118 85 144 44 133 92 110 106 118 68 76 79 79 88 76 63 53 61 33 57 67 81 67 51 49 44 97 87 39 45 46 53 47 68 24 0 0 21 43 49 65 94 111 128 121 99 145 128 132 178 146 172 147 106 123 165 179 179 121 143 134 187 156 127 144 155 166 139 153 140 149 166 99 141 134 143 131 126 114 147 140 139 161 166 141 164 149 161 193 139 119 152 181 158 143 165 171 150 147 129 143 143 158 146 118 116 128 150 87 76 102 101 105 55 95 75 68 94 90 140 75 43 52 65 68 61 45 0 77 37 108 125 81 89 79 50 60 36 95 66 57 66 75 52 89 110 106 89 121 77 70 144 104 95 71 110 112 142 156 165 140 140 137 145 129 156 145 134 138 143 134 130 135 144 108 124 88 113 118 140 97 111 105 119 104 113 105 90 70 104 77 51 59 95 111 83 92 52 56 64 62 38 55 55 52 68 50 50 69 41 62 23 30 32 3 2 40 78 77 52 65 114 145 126 126 160 160 151 177 182 138 138 193 149 176 164 145 136 163 134 100 119 148 147 118 143 115 152 121 149 94 112 120 102 147 124 126 163 174 120 140 127 140 147 147 139 124 137 155 130 151 148 173 155 164 151 137 150 120 163 143 102 140 161 153 116 98 94 66 94 100 92 79 55 71 80 123 67 59 40 38 57 13 46 3 1 61 107 141 113 39 27 54 59 86 109 71 61 70 37 88 70 91 111 94 87 91 122 72 103 77 131 107 151 129 115 108 111 124 161 105 150 128 152 122 153 174 121 166 153 187 93 114 136 178 118 133 99 120 100 89 110 99 106 131 46 77 58 65 62 77 76 59 62 106 98 63 78 49 55 56 50 35 47 37 75 7 34 41 23 0 25 71 70 97 62 75 101 112 148 147 107 125 139 147 165 150 138 168 137 175 164 137 139 118 152 111 172 136 108 150 139 156 105 164 154 107 103 116 136 153 132 121 128 120 156 130 125 121 143 147 152 136 161 182 171 152 148 145 167 177 141 194 142 169 120 118 165 125 138 120 78 91 66 79 85 71 80 85 50 127 57 118 70 88 76 26 17 64 27 48 19 35 26 91 145 96 95 58 58 72 74 64 55 74 85 106 40 48 108 127 107 111 116 51 126 86 79 121 152 132 85 149 131 103 159 106 121 148 100 161 178 157 168 123 163 159 98 128 114 153 112 168 111 92 108 102 131 120 104 127 36 67 120 57 88 68 57 85 82 102 53 62 66 77 56 30 85 60 46 83 49 7 52 52 25 46 2 21 47 75 48 50 108 92 148 119 139 139 143 158 136 133 170 178 169 143 171 195 112 142 94 136 181 150 147 139 103 128 123 112 159 150 115 184 125 163 116 119 126 121 126 100 117 101 169 125 169 118 144 136 129 150 159 151 131 153 191 139 128 150 110 128 133 150 159 120 101 118 127 109 117 88 104 78 107 105 114 136 128 128 106 76 80 86 67 17 0 16 3 49 22 101 96 106 20 51 62 84 77 45 90 61 54 59 77 92 84 73 103 114 103 106 167 115 90 88 126 123 116 120 98 114 121 98 127 96 187 155 123 184 141 170 155 135 149 147 141 111 103 123 118 171 121 86 156 102 136 82 117 75 102 81 111 85 63 100 56 66 114 29 26 105 46 71 67 34 61 49 51 30 48 11 21 8 52 81 95 70 101 76 105 115 142 136 137 124 120 165 166 168 130 132 152 131 167 173 149 134 141 134 151 118 159 146 136 153 122 123 103 120 99 132 143 95 123 113 93 62 129 141 160 121 130 174 155 161 161 150 147 156 170 178 156 120 161 123 127 101 134 124 129 131 124 116 112 108 102 108 97 140 130 129 88 91 113 123 126 59 20 47 94 14 69 16 20 56 38 31 140 154 108 48 69 43 31 66 72 61 97 31 101 60 62 81 139 82 114 133 83 114 82 118 91 139 167 112 145 131 155 107 126 143 120 153 167 172 101 146 123 191 168 110 85 130 133 153 138 111 141 102 107 162 132 123 102 108 45 90 95 95 77 94 74 109 97 59 103 55 69 83 70 92 84 65 32 47 42 54 22 17 59 82 80 94 79 79 106 103 122 80 113 152 124 149 139 154 130 142 134 167 110 171 163 194 157 142 143 79 169 131 103 121 118 175 115 177 128 95 132 165 141 136 103 88 104 120 157 137 140 104 153 141 118 123 135 135 151 169 159 151 143 119 148 143 155 89 127 115 128 133 130 111 135 97 137 136 82 118 91 178 149 140 107 112 56 92 76 61 40 44 58 33 31 69 74 97 89 74 98 41 64 69 11 80 69 66 46 62 50 63 107 82 141 123 98 120 114 121 125 95 140 129 121 98 105 130 131 69 120 118 159 162 137 128 128 100 154 153 141 107 145 135 122 106 80 77 102 94 94 130 102 105 129 101 112 123 81 74 83 68 67 81 72 79 100 108 84 113 62 81 122 66 41 47 20 73 57 97 82 92 76 75 60 86 70 95 119 141 137 153 127 121 118 188 177 158 91 111 181 174 214 132 144 148 138 141 174 115 154 131 131 108 97 132 100 128 113 84 97 96 117 113 155 123 125 123 166 144 159 164 146 134 154 128 132 151 164 131 115 163 137 166 126 154 176 130 149 100 139 83 59 96 99 46 122 95 79 113 119 102 67 77 44 66 64 45 48 23 41 25 79 69 18 95 118 112 54 16 42 54 34 38 56 21 46 83 112 85 74 106 84 109 143 116 101 93 127 101 101 158 106 118 140 139 91 133 92 151 169 157 168 134 116 151 159 122 137 104 141 107 124 133 128 99 119 133 125 162 138 132 140 90 120 125 62 89 96 49 124 78 78 72 110 69 113 102 91 98 101 79 80 51 61 60 47 52 54 87 83 70 105 65 67 80 97 85 79 102 120 155 111 181 158 113 140 142 197 192 134 139 116 137 175 150 131 151 144 166 158 93 117 153 142 88 83 96 124 122 115 87 121 126 153 109 125 139 133 160 145 126 116 144 160 189 137 173 142 170 148 111 166 150 134 120 137 79 114 111 118 96 125 124 140 87 86 83 118 101 90 51 30 52 25 40 40 50 73 26 30 47 63 120 88 107 27 19 44 33 59 52 51 32 36 67 82 64 54 99 94 106 130 119 110 187 103 132 116 149 112 81 72 102 109 104 129 119 202 147 166 111 138 132 99 128 154 154 136 98 143 158 138 122 112 130 85 86 100 115 136 109 83 109 80 103 93 113 116 57 88 70 80 138 113 113 89 103 87 102 67 101 102 57 15 41 45 39 82 38 50 57 67 98 56 84 67 109 128 100 179 139 157 78 148 138 155 131 156 152 116 192 156 146 123 109 132 120 134 132 110 144 110 117 129 128 90 115 121 84 143 152 134 145 135 110 138 150 127 136 132 117 114 139 144 115 164 132 196 113 201 108 136 148 131 94 95 113 104 119 130 103 94 76 79 64 102 88 86 46 74 78 29 51 43 52 13 38 0 93 119 105 89 58 40 26 65 32 59 80 83 56 97 33 22 57 49 79 62 120 106 79 128 75 126 135 126 125 156 148 123 105 132 122 127 176 136 141 121 156 159 127 144 122 89 127 124 122 108 133 95 171 107 103 111 145 96 82 79 111 106 112 70 81 49 99 91 81 79 105 101 82 84 77 73 87 130 89 76 114 87 104 96 63 14 69 58 56 70 40 56 81 100 81 63 103 104 88 99 151 119 136 144 153 119 147 124 128 116 128 149 128 146 135 103 120 144 98 129 91 102 70 92 104 127 92 119 163 109 190 126 120 137 136 173 176 144 147 124 151 181 143 179 175 89 147 168 167 110 134 126 116 125 109 131 96 151 116 104 116 104 97 40 47 113 80 52 23 0 36 62 46 60 59 31 19 16 107 101 142 59 49 10 0 65 81 86 38 77 77 61 74 45 33 119 113 96 91 107 74 128 108 83 135 103 122 101 111 128 81 164 136 172 134 158 130 102 153 137 90 137 113 140 135 142 133 143 107 72 105 93 111 135 125 158 86 99 115 111 76 85 74 86 58 97 94 105 80 67 49 84 101 99 83 48 126 102 113 111 53 71 90 66 37 68 0 22 30 54 71 33 82 96 121 111 142 152 117 106 150 146 130 131 165 186 118 147 144 105 139 142 151 117 120 89 136 100 87 71 100 88 109 80 78 149 127 133 161 160 140 160 161 171 115 157 137 164 144 152 168 169 116 134 152 137 120 125 134 135 159 130 105 89 115 87 132 98 111 77 80 71 96 72 90 23 31 79 46 46 65 48 30 54 47 108 114 129 83 52 36 33 53 42 69 58 59 67 67 91 49 66 109 60 98 167 142 123 144 93 140 142 114 123 136 114 118 114 119 144 131 170 152 148 168 133 146 138 143 172 112 135 88 144 125 152 111 90 97 111 148 136 101 108 132 105 120 67 95 91 73 87 97 102 67 100 73 138 73 80 75 59 80 99 115 111 115 99 107 93 94 71 47 39 59 28 29 60 64 65 48 41 132 123 86 102 100 116 141 123 163 118 168 145 186 105 81 121 75 135 114 83 119 118 52 116 92 82 92 68 104 116 145 151 116 133 151 184 145 131 93 161 211 144 120 172 152 170 98 156 140 175 142 105 157 165 140 131 77 45 25 18 32 69 32 52 64 41 57 91 55 42 63 43 20 24 49 17 64 36 58 48 82 102 98 115 27 55 11 49 23 94 89 37 16 69 101 89 66 58 67 113 130 77 97 133 154 86 146 133 120 122 116 119 108 173 123 168 125 154 147 140 129 138 181 122 157 127 154 113 95 122 143 100 154 111 73 88 144 145 113 140 106 133 142 83 74 66 69 81 103 71 118 50 100 83 87 54 53 73 108 103 87 127 102 73 106 98 133 100 90 59 27 22 88 44 61 47 33 25 93 136 108 100 59 118 108 127 157 178 146 135 121 120 78 100 114 86 47 91 104 80 94 92 93 84 133 156 126 137 133 158 161 148 123 131 132 147 149 153 168 146 137 159 165 150 135 138 141 132 78 68 67 45 47 51 30 44 57 40 13 66 36 21 45 29 79 22 26 19 48 8 85 28 77 55 60 47 39 124 113 176 142 45 29 60 22 31 43 50 38 39 34 78 53 63 10 14 72 64 64 122 99 84 108 145 95 133 134 107 112 153 129 154 133 145 101 134 138 147 91 156 138 87 120 157 133 112 117 92 108 85 95 111 134 87 121 64 82 94 118 125 83 82 47 74 93 99 91 65 93 110 96 105 76 136 97 78 76 93 61 91 30 99 70 52 86 88 55 64 30 89 35 54 62 68 21 101 113 83 87 86 98 95 150 101 112 106 107 88 93 87 98 102 115 119 114 120 139 77 74 136 191 138 145 123 86 110 97 110 108 104 130 128 167 169 151 171 169 114 149 174 142 120 93 89 44 51 87 57 73 66 49 53 30 30 55 33 33 0 93 34 47 71 49 35 26 35 24 56 27 34 21 87 42 66 97 123 135 136 137 101 70 109 78 53 92 64 85 66 87 129 118 108 106 82 116 126 84 80 68 115 109 113 115 155 110 135 103 104 149 178 168 120 144 138 157 121 139 131 155 138 88 135 133 130 116 104 121 109 83 120 141 129 112 95 140 119 161 119 72 91 74 100 96 68 63 78 89 94 94 93 89 76 67 99 92 93 90 84 54 80 72 88 133 39 16 72 50 64 52 63 73 58 58 48 58 71 113 56 121 93 112 145 90 124 134 64 62 121 138 161 110 108 149 128 109 84 90 135 94 63 104 83 122 112 84 97 107 122 149 116 138 122 178 128 118 167 99 74 60 79 0 47 65 38 82 75 52 72 76 48 28 42 48 75 40 22 16 33 27 21 0 51 12 10 51 55 77 93 47 61 64 136 124 114 148 147 119 109 134 138 95 105 115 91 160 124 89 68 84 90 80 82 94 75 50 102 80 96 126 92 106 88 111 151 91 152 163 133 129 146 159 143 141 146 168 112 145 128 112 118 145 74 128 90 113 121 135 125 92 137 107 111 145 137 95 78 64 78 64 16 43 62 87 61 80 107 71 64 84 107 82 99 108 74 101 82 100 98 59 67 80 53 32 49 47 78 93 73 58 65 65 47 98 47 65 98 73 73 123 87 103 109 88 81 137 126 159 123 70 133 32 20 24 17 74 36 82 117 83 87 106 64 84 93 115 159 148 122 122 89 124 117 77 72 66 59 55 10 70 69 59 0 41 91 67 85 51 32 54 46 18 53 38 11 0 10 22 49 15 22 36 33 7 62 78 91 158 108 133 122 129 116 94 129 145 133 81 174 122 111 119 141 111 101 68 51 71 87 100 92 73 79 84 73 97 107 71 91 97 127 99 143 168 142 163 154 152 136 144 140 145 144 86 131 110 141 134 138 132 56 139 126 112 151 136 115 108 127 89 97 110 97 84 54 75 48 24 50 107 75 77 94 71 116 103 83 85 49 95 99 120 101 72 73 61 139 85 89 53 39 52 52 53 80 48 35 65 48 67 56 61 52 24 122 94 128 107 113 105 80 101 174 88 93 70 19 8 23 46 29 27 16 53 56 26 45 62 67 40 80 46 57 65 98 38 45 73 83 76 47 71 52 50 35 29 38 30 33 2 41 67 45 16 42 52 10 54 29 84 35 41 45 30 49 0 0 34 74 0 33 98 124 108 142 113 136 176 149 164 120 131 120 130 126 154 74 123 114 64 76 51 91 59 79 70 75 95 84 79 57 85 108 104 65 66 102 122 99 167 180 173 127 107 156 178 151 127 172 110 139 111 109 128 122 112 125 98 110 78 126 106 101 110 83 139 145 148 114 117 111 65 49 56 97 51 83 83 85 61 81 82 101 99 80 73 80 100 115 67 100 70 80 100 77 61 47 80 46 24 112 82 70 46 99 61 57 84 51 42 54 29 96 107 122 118 6 73 58 112 83 47 40 7 66 49 8 32 30 20 49 79 91 72 48 64 62 49 37 33 25 12 41 41 28 33 46 29 32 59 26 39 67 2 12 59 83 40 65 53 31 22 68 32 61 46 71 24 46 30 0 3 16 7 74 49 125 113 146 121 140 197 173 121 155 166 185 148 102 144 120 123 102 78 60 53 103 70 64 78 90 54 58 45 45 93 74 74 119 71 68 96 75 81 69 108 144 179 153 147 155 153 128 173 147 155 121 118 169 134 108 148 134 124 99 135 131 84 110 110 103 120 110 92 149 110 128 96 47 59 81 78 64 79 46 106 85 98 89 95 127 97 48 81 92 94 101 92 53 65 75 32 63 42 94 99 91 64 86 72 72 41 78 64 52 52 77 5 41 121 113 121 67 61 1 95 101 33 38 40 25 59 35 11 24 38 70 31 66 31 38 9 32 56 50 34 42 78 12 20 27 44 49 28 23 2 29 34 44 18 32 27 26 32 48 42 68 30 46 28 10 57 39 37 0 27 23 26 26 15 37 176 133 154 164 164 153 149 162 101 159 140 135 136 138 126 57 102 88 75 77 84 96 64 111 49 80 59 50 79 90 123 87 69 70 55 103 69 81 81 69 102 89 147 141 155 167 139 148 169 159 151 142 134 158 129 99 169 126 115 111 103 87 116 116 162 116 107 174 107 148 121 133 65 68 51 88 43 44 24 67 85 103 105 96 84 44 106 106 63 117 88 111 123 99 57 63 52 106 66 53 63 47 60 67 93 63 81 28 43 17 54 61 43 71 54 27 121 100 111 51 56 35 50 51 40 27 56 11 15 6 37 51 86 4 79 56 36 37 49 58 5 52 56 56 25 21 32 34 32 32 15 37 36 36 45 77 32 61 32 51 27 11 0 48 61 17 28 37 33 53 64 50 14 17 70 130 121 107 137 156 139 153 157 174 156 139 121 128 110 178 147 107 109 85 81 72 103 68 50 103 89 65 87 123 70 97 63 56 101 92 56 99 76 52 88 68 88 76 83 121 162 158 161 128 163 121 154 147 121 162 139 118 124 128 95 132 141 131 131 99 133 105 101 147 122 138 106 127 106 61 75 51 64 43 90 111 81 98 61 73 62 104 78 70 101 81 103 63 91 86 76 30 103 55 68 52 87 119 46 52 66 74 57 57 57 58 57 42 71 66 39 84 35 44 50 60 62 93 61 70 75 47 35 34 62 53 30 27 14 33 57 60 42 55 26 35 28 68 23 23 23 10 13 27 38 11 13 24 12 46 28 70 35 21 34 56 39 15 44 38 32 21 28 36 29 42 47 13 44 33 76 123 141 153 170 142 142 148 156 165 169 137 160 202 154 244 197 105 86 66 82 105 93 59 70 97 53 104 116 77 67 98 74 91 79 91 107 73 103 114 84 94 91 73 72 71 170 135 172 102 147 109 126 119 108 143 126 105 145 129 104 135 114 94 118 85 94 83 98 139 86 98 118 124 129 119 90 51 41 48 51 55 113 98 69 106 100 107 87 52 92 78 75 58 101 58 45 69 38 40 64 49 56 59 45 32 72 72 63 64 51 77 61 42 86 71 76 80 56 59 66 45 52 85 52 67 94 72 30 24 56 1 12 0 32 24 51 32 61 0 52 38 32 34 42 30 17 26 23 70 37 28 42 73 39 71 38 42 41 45 29 53 18 58 49 73 37 35 24 36 62 41 55 54 16 37 143 97 158 147 159 107 115 93 139 176 162 146 143 155 169 164 216 106 98 65 110 88 122 53 61 52 79 64 97 74 81 110 97 90 84 26 100 116 60 67 101 94 93 65 130 81 78 138 116 139 141 139 137 123 156 111 128 133 107 108 106 103 96 121 102 118 140 103 109 105 103 143 131 146 154 156 113 93 41 60 108 91 66 110 96 116 119 95 100 87 103 114 81 85 126 54 119 94 80 56 87 47 61 52 59 41 65 64 25 76 64 59 104 67 37 44 54 99 81 75 66 105 100 95 71 34 53 44 69 63 53 49 40 31 65 41 54 27 58 26 32 64 48 36 51 4 3 37 43 35 40 63 17 40 11 75 29 40 9 41 33 56 34 33 44 34 17 40 32 93 62 21 42 27 39 93 102 116 114 173 151 169 133 136 152 122 170 104 145 154 138 167 185 167 84 104 95 80 88 93 117 102 133 79 113 84 95 74 75 40 73 81 51 113 74 60 92 79 48 105 74 78 66 53 173 125 148 106 124 138 169 163 110 128 69 111 97 125 137 89 93 100 107 86 108 87 95 92 120 107 133 126 110 145 128 28 42 92 88 103 101 93 141 122 113 108 90 93 127 104 84 90 91 93 83 71 59 80 69 76 100 82 67 94 66 122 37 73 32 63 37 59 70 85 63 41 54 58 75 70 77 67 88 87 49 43 52 46 32 17 55 64 11 24 0 62 11 1 16 23 70 44 36 10 15 53 39 19 11 15 29 60 27 43 43 37 23 65 30 53 75 34 15 42 58 57 30 11 40 15 45 123 106 139 141 128 129 154 140 173 123 132 170 121 144 145 167 211 215 175 168 103 85 77 62 67 117 97 45 66 99 68 127 95 63 40 66 49 89 52 124 67 67 97 94 97 140 105 118 125 127 145 139 113 94 111 138 128 128 131 109 112 125 87 93 107 129 94 130 120 114 124 104 107 127 119 146 122 115 135 131 120 93 30 78 107 106 110 144 111 130 127 140 126 55 93 95 122 119 114 75 46 69 120 66 70 73 123 69 90 85 94 81 121 62 85 111 68 55 52 106 120 73 52 35 48 62 96 108 64 75 70 68 56 31 53 31 43 25 54 56 27 29 60 0 77 53 46 55 37 21 0 19 45 19 45 22 16 23 48 26 18 28 32 39 4 41 30 34 2 64 10 35 26 9 23 87 167 119 150 77 108 132 137 118 175 164 147 120 145 149 164 107 181 148 118 105 141 70 105 133 92 80 107 103 47 83 72 104 65 118 36 54 72 90 73 69 84 102 64 82 66 114 44 92 57 78 91 102 149 165 139 110 120 131 134 124 128 123 121 122 87 102 70 89 121 117 68 77 118 127 107 116 156 129 132 133 134 100 135 56 43 104 99 143 122 153 174 102 117 79 47 66 68 103 114 75 87 102 82 97 49 94 117 110 109 71 72 112 99 84 113 109 80 35 85 86 80 88 106 75 100 96 91 63 61 31 74 97 87 66 37 67 56 56 74 37 34 55 9 31 72 12 26 17 22 7 55 62 20 1 30 29 34 24 6 20 20 68 48 26 43 46 16 42 25 46 33 53 22 52 35 133 162 134 120 106 133 56 161 138 98 103 145 150 158 122 133 144 170 150 134 146 170 78 100 70 64 65 68 79 78 92 130 50 98 59 56 58 44 113 98 46 68 81 41 54 80 76 77 88 111 78 86 72 152 156 134 153 82 106 135 125 73 127 129 99 119 102 131 121 107 104 127 59 86 115 101 143 117 111 93 95 165 129 121 114 87 29 109 97 92 141 141 106 107 115 96 85 57 115 84 56 74 124 84 67 107 111 70 82 80 72 72 57 92 84 88 85 91 83 64 78 69 86 47 93 122 114 77 67 48 85 96 90 68 76 58 90 53 76 72 38 52 33 44 17 49 37 19 32 22 55 0 0 25 35 11 35 19 2 46 33 28 44 7 15 43 16 57 15 9 42 49 21 0 30 52 132 141 143 116 79 91 113 96 141 114 151 111 110 154 161 118 130 155 160 154 147 122 137 105 64 52 125 76 74 87 88 78 50 92 100 70 114 61 1 88 81 40 64 64 94 64 121 99 101 70 73 18 56 119 119 183 158 140 112 163 141 148 169 109 88 96 88 129 105 136 114 90 97 104 97 114 136 133 110 116 143 148 107 161 110 151 98 59 59 102 98 157 134 128 147 108 122 109 58 100 78 47 91 74 75 115 121 76 96 94 57 71 78 89 102 91 96 149 74 88 81 108 79 106 108 75 63 36 103 115 79 75 89 114 38 87 47 76 53 34 35 15 56 26 23 58 4 26 20 6 63 29 40 20 8 2 52 42 19 53 53 30 73 18 34 56 3 46 25 29 14 62 0 39 0 103 118 169 152 88 80 79 113 108 81 119 144 142 119 150 123 130 137 119 138 169 185 165 118 89 75 88 107 102 59 107 117 107 64 106 56 46 64 81 140 34 41 102 58 92 68 53 78 92 131 92 83 101 52 84 108 100 150 118 154 117 145 123 150 109 160 116 105 100 111 89 130 115 113 114 107 74 148 100 86 104 116 103 149 140 148 130 165 118 75 82 104 114 150 110 114 165 97 118 122 86 55 67 56 64 110 103 122 76 100 98 105 82 110 99 64 75 89 83 89 62 71 58 72 83 90 87 105 82 79 80 57 65 84 74 68 54 90 45 94 58 61 74 39 34 42 48 21 70 24 22 35 5 33 37 47 47 12 22 15 22 43 9 54 53 30 38 40 13 13 33 12 17 49 42 24 121 111 138 116 126 75 94 119 108 107 110 117 76 92 124 130 103 148 158 120 152 214 128 146 109 57 55 64 81 73 79 107 89 62 56 75 95 60 71 105 80 90 87 93 105 87 39 57 65 68 94 112 97 116 86 85 115 133 130 132 135 132 154 148 138 135 101 123 78 83 107 126 121 96 107 87 104 133 146 138 130 130 93 119 150 115 123 155 153 173 139 127 50 88 98 155 112 100 121 98 119 98 99 36 25 31 55 62 72 63 108 71 86 94 106 117 81 64 93 107 66 78 116 114 95 86 84 102 92 53 109 96 59 85 82 70 102 75 75 58 107 77 82 43 30 37 51 63 46 62 20 67 51 61 11 25 35 49 34 65 33 14 27 24 12 35 36 0 8 42 37 23 35 24 17 30 101 89 90 179 129 130 77 79 123 103 126 108 94 123 109 95 166 137 153 141 200 130 154 132 157 46 45 44 95 127 85 80 63 60 62 99 62 82 56 52 78 92 87 87 104 69 78 53 80 74 66 57 63 49 107 88 99 80 120 139 134 130 130 130 112 120 93 112 138 105 79 107 85 97 109 68 106 119 107 145 139 102 127 147 131 103 119 138 132 124 135 86 110 112 95 84 143 76 107 161 108 116 159 78 71 67 26 75 35 41 27 89 119 94 88 81 63 114 98 92 84 99 102 102 62 97 110 78 126 78 86 99 63 88 56 69 60 62 79 55 79 78 66 73 87 81 80 51 47 33 8 44 28 17 25 38 36 17 24 26 61 16 34 23 51 18 81 5 0 0 17 35 28 0 37 0 112 157 152 90 139 89 45 54 106 84 103 162 115 78 132 125 148 133 128 77 125 156 137 168 148 69 64 77 70 80 106 107 68 47 70 102 80 55 72 35 43 89 125 110 56 96 93 18 49 63 55 72 103 73 69 72 95 96 37 146 135 142 150 142 138 176 146 147 96 126 142 93 134 88 114 96 95 125 110 143 111 119 132 108 138 114 130 116 151 148 149 149 128 125 106 140 89 121 135 120 115 85 129 83 77 65 57 86 55 32 37 56 91 104 90 72 100 78 100 80 68 105 100 106 82 89 108 68 56 86 82 79 69 109 64 103 74 101 119 91 84 76 76 79 60 49 73 20 22 36 31 21 14 61 35 33 27 15 11 61 30 27 18 0 27 4 65 60 33 29 21 24 3 22 63 54 127 110 133 118 150 126 120 58 90 87 65 74 89 88 149 148 145 142 114 43 150 166 160 138 158 104 82 83 75 73 73 89 94 50 67 51 94 58 70 20 65 63 75 100 90 99 65 69 68 44 58 83 102 73 75 70 109 58 61 92 122 131 102 138 138 144 118 103 145 120 127 164 141 75 113 128 73 84 141 106 164 128 161 100 97 147 136 114 157 134 160 115 104 126 136 147 108 106 103 131 161 83 175 136 132 115 66 79 98 72 27 34 2 45 2 68 74 91 85 87 95 74 91 46 42 98 88 84 65 58 74 80 97 118 101 97 67 94 73 87 104 86 52 72 108 59 78 117 52 66 32 33 46 7 49 72 15 52 14 14 44 24 0 47 26 0 32 19 94 26 0 32 38 19 38 37 83 108 95 99 185 150 152 99 79 45 101 68 150 129 110 129 158 133 89 70 136 143 191 156 196 86 63 55 65 53 61 83 69 71 44 79 119 64 48 52 78 86 64 81 69 111 49 50 60 139 88 90 123 85 102 73 56 98 67 98 101 169 130 139 128 146 102 102 149 98 124 109 97 96 112 84 150 138 125 88 115 112 129 148 125 144 123 130 108 140 134 144 144 167 138 153 155 115 107 121 73 97 96 119 132 160 74 92 69 81 89 31 18 42 18 27 53 60 67 104 45 88 100 71 58 70 44 78 93 98 131 76 90 102 101 83 86 81 89 78 86 99 96 82 71 64 101 75 57 88 16 39 52 59 57 61 0 49 42 30 37 51 52 14 0 0 42 36 35 59 12 4 32 36 13 77 32 96 129 135 178 143 111 109 51 77 70 119 91 114 130 105 134 95 74 125 144 179 150 168 187 92 75 153 130 151 114 154 135 158 177 154 135 99 104 134 131 104 80 43 39 56 82 57 39 71 81 62 83 35 89 76 70 78 58 95 69 122 156 110 155 155 126 154 95 135 135 112 92 102 112 111 103 111 119 113 111 98 146 163 165 167 185 124 120 105 158 117 97 145 105 140 164 172 98 111 60 123 70 62 87 117 143 122 89 43 92 59 62 77 24 11 53 34 62 31 55 59 95 74 80 114 86 79 103 64 83 81 109 76 94 51 83 73 72 81 104 41 56 63 93 62 91 74 75 42 60 85 69 40 30 42 23 4 20 22 20 3 34 34 93 34 0 49 21 45 43 26 0 2 26 45 82 125 72 126 152 130 141 94 98 74 93 72 84 133 111 125 83 68 98 102 139 133 138 110 158 106 119 142 171 159 142 103 127 197 171 136 118 161 113 126 91 93 82 108 98 103 61 29 57 60 85 32 47 66 45 74 77 58 62 88 76 70 67 141 119 125 131 151 101 113 111 98 106 63 125 97 114 134 122 116 118 119 148 143 125 123 176 110 104 164 131 136 80 123 114 145 100 138 127 113 134 137 76 73 86 95 119 134 83 110 83 75 64 42 63 62 43 34 47 11 43 45 44 59 28 62 98 91 89 73 104 57 84 82 94 69 74 108 93 108 68 70 69 89 49 74 81 78 75 75 31 67 43 57 91 61 59 0 48 55 23 62 0 17 23 6 44 0 20 30 30 17 42 57 11 20 19 61 100 97 127 182 156 136 93 78 93 101 58 96 100 49 30 76 65 105 153 136 120 121 124 68 137 111 135 124 142 130 113 179 113 130 114 134 92 79 118 111 98 99 93 97 48 98 85 25 64 49 91 62 73 36 54 87 75 37 89 109 81 84 134 115 105 105 140 126 65 169 103 158 135 124 121 127 80 86 95 136 148 132 146 131 171 133 171 141 122 114 95 120 129 143 149 153 124 152 160 128 143 123 109 112 92 69 82 137 98 123 104 80 51 42 45 91 53 38 36 25 10 25 23 71 57 50 37 72 58 59 81 75 80 70 69 84 113 55 76 60 117 62 66 35 66 44 36 77 51 79 86 57 65 63 76 64 52 25 15 37 11 67 23 49 37 45 59 0 10 12 41 15 11 6 18 93 116 135 104 109 139 134 113 96 57 104 99 91 71 117 144 109 112 138 161 129 161 137 149 66 145 96 172 129 154 117 109 194 149 138 112 117 114 101 107 99 122 128 123 83 82 88 70 81 79 68 127 54 71 59 35 49 91 40 61 91 85 84 109 100 107 143 107 112 126 123 142 111 78 127 117 126 122 102 132 96 123 82 135 153 157 163 147 152 131 142 102 138 97 140 136 135 140 103 141 153 148 153 156 115 105 114 80 83 83 98 110 24 80 51 60 40 62 44 44 21 55 29 47 50 17 52 49 54 30 68 75 53 44 51 33 73 49 45 40 75 52 49 81 50 75 44 31 85 50 31 73 42 40 34 64 63 39 74 15 76 37 19 86 0 44 37 15 56 45 25 27 21 39 46 5 76 83 148 133 107 100 139 101 85 60 90 99 85 73 85 119 99 101 130 144 136 113 154 141 152 160 105 133 140 128 164 113 134 153 129 128 108 149 111 128 95 91 99 83 79 81 37 114 61 96 108 98 84 66 107 28 62 71 52 69 80 82 100 85 66 115 96 136 139 143 143 134 105 110 107 118 100 79 104 139 92 152 122 113 126 125 127 155 146 159 141 128 147 113 86 102 120 139 121 128 141 147 105 126 130 120 120 109 115 90 82 55 81 95 59 80 69 51 70 95 33 23 53 43 40 59 21 41 55 33 54 52 88 50 58 73 45 62 49 27 54 72 82 47 39 31 57 53 74 50 70 54 74 44 78 43 30 31 80 46 66 43 79 51 17 31 34 14 13 0 8 21 0 15 39 27 22 58 77 100 50 87 97 68 74 76 70 45 55 51 103 82 128 125 151 161 124 139 127 127 154 126 115 97 161 138 124 138 108 97 127 141 113 138 135 151 106 77 94 83 124 96 88 100 67 75 111 54 92 46 109 97 90 50 69 63 55 89 55 115 77 96 132 157 152 147 136 152 147 146 105 102 98 111 91 122 126 127 89 96 140 120 136 154 133 138 119 121 111 148 174 147 95 136 126 130 134 106 148 130 129 122 132 100 84 130 112 58 65 37 94 56 60 59 94 78 59 58 50 72 55 67 92 25 70 58 56 83 21 61 54 73 41 101 57 86 45 34 70 50 57 59 46 77 36 46 15 72 27 68 68 72 40 44 13 87 82 41 101 82 86 55 9 52 20 54 0 39 21 0 52 40 103 95 105 147 86 85 73 93 102 100 77 98 134 127 119 82 151 171 129 106 132 134 77 112 107 108 143 155 130 136 119 84 139 143 128 108 131 116 132 125 83 79 76 106 80 80 81 97 99 59 85 95 83 73 66 60 94 81 75 80 96 101 82 64 33 99 75 160 152 144 99 89 152 107 141 125 108 131 104 125 123 135 134 113 136 105 118 114 133 149 156 133 152 78 121 131 137 148 127 110 151 100 111 123 159 128 157 123 137 167 117 96 77 90 78 56 82 65 78 65 82 76 33 60 31 24 52 64 29 40 60 56 20 29 46 24 10 50 59 54 35 32 34 46 27 56 50 50 89 62 63 48 73 85 34 79 48 44 11 86 64 92 75 70 41 42 84 43 49 9 28 26 25 42 7 70 151 123 62 103 120 116 135 168 146 100 142 97 148 94 98 123 114 162 140 120 37 139 115 141 110 81 102 123 116 148 105 143 131 131 167 169 114 122 152 93 116 75 116 65 92 119 98 100 77 63 91 75 64 58 72 78 82 53 133 84 91 89 77 81 89 75 71 47 103 98 86 122 130 77 91 148 140 129 137 68 111 109 157 91 122 127 114 143 136 136 188 92 130 116 123 123 149 91 116 117 147 104 140 148 158 140 138 129 128 113 148 133 136 87 72 58 43 65 62 55 82 68 41 45 38 18 15 90 66 53 51 65 54 83 9 49 76 34 8 33 43 50 50 65 68 75 28 63 75 53 48 18 60 106 80 24 55 64 35 38 84 25 42 51 66 46 59 47 42 35 48 27 14 44 33 110 91 116 117 27 62 96 107 95 98 87 100 78 146 108 108 88 101 51 108 92 58 98 125 140 136 122 114 114 121 96 85 145 105 100 104 143 105 95 116 86 62 58 93 77 121 93 103 107 94 100 117 83 110 100 74 72 72 66 80 66 95 120 73 99 78 72 121 68 69 111 108 130 111 138 122 155 115 119 133 141 155 117 89 117 159 94 90 153 108 178 117 144 120 150 98 133 94 157 145 144 159 142 146 115 114 83 141 133 133 104 127 163 127 113 145 97 89 103 34 31 34 43 65 49 56 31 17 51 59 48 85 53 83 28 65 34 59 29 51 31 61 15 49 60 46 46 32 19 45 78 45 64 46 13 68 46 69 48 59 55 93 20 63 92 58 82 68 61 71 41 54 75 73 58 64 129 113 94 99 46 13 29 97 76 69 71 109 93 66 48 82 53 22 90 45 93 60 87 129 101 111 98 100 102 94 97 103 96 45 85 138 96 134 87 70 59 102 59 64 60 68 69 96 80 80 62 64 93 76 103 73 55 60 77 71 82 81 84 90 47 100 68 86 101 98 44 162 93 95 71 107 130 143 139 96 144 129 110 132 111 119 104 107 103 114 161 143 143 90 104 107 121 137 118 165 126 156 109 111 139 112 116 145 91 128 122 101 124 109 140 145 136 115 142 60 77 8 51 54 24 45 48 50 55 19 38 43 38 2 58 37 67 27 63 68 0 44 33 33 41 30 57 20 73 39 37 55 47 104 76 94 39 59 69 71 39 43 70 66 69 60 63 50 67 16 57 33 78 28 72 41 78 150 114 104 91 74 22 70 64 63 61 88 65 86 76 49 70 68 48 68 84 80 80 90 92 103 103 96 82 87 109 39 80 92 127 127 135 181 176 117 146 113 122 111 118 70 124 94 90 68 83 50 75 66 70 45 63 35 84 49 61 54 27 119 92 124 104 81 66 69 72 96 107 115 112 125 156 118 112 124 117 132 77 126 105 119 119 128 91 134 117 138 94 169 115 149 135 116 126 124 106 98 154 132 133 130 138 123 119 145 77 113 129 100 127 107 132 126 148 87 91 38 31 42 73 73 36 66 57 59 11 37 22 30 60 51 27 61 60 27 48 72 57 32 76 41 27 25 14 19 58 39 25 8 42 52 38 86 93 44 84 96 46 32 46 38 86 59 79 63 83 110 40 72 66 55 53 100 123 106 77 104 53 66 91 84 65 108 71 93 109 55 52 57 39 95 84 91 92 91 84 97 104 108 88 84 80 132 116 85 67 73 89 132 185 180 167 91 133 109 128 159 117 174 115 112 145 67 77 84 79 97 65 32 58 75 60 58 3 60 62 119 61 90 46 78 73 115 100 143 150 109 124 120 90 82 114 129 162 116 142 122 103 110 117 104 98 128 134 121 143 130 163 142 174 135 82 114 171 89 153 151 152 140 158 141 118 131 122 112 110 145 118 101 125 161 71 85 50 59 86 61 85 31 74 39 62 55 95 25 74 43 35 41 59 73 46 18 56 2 48 21 32 17 35 11 83 46 43 15 74 16 53 31 63 50 82 92 54 96 86 56 54 117 43 68 36 50 54 48 108 55 84 72 116 104 111 39 65 61 61 66 86 76 85 80 76 59 89 58 32 37 59 62 125 125 94 110 111 82 84 61 85 89 116 90 76 62 82 118 168 158 170 123 140 132 150 111 191 147 140 140 131 86 124 85 64 66 62 84 76 90 52 45 34 69 49 18 58 70 114 120 65 49 92 52 121 116 134 110 111 126 106 148 119 131 115 77 115 102 129 179 154 112 125 145 158 90 156 128 180 135 147 133 106 158 120 145 172 168 117 104 146 119 139 119 130 100 61 100 97 106 117 150 130 60 92 69 77 62 44 49 35 45 0 37 41 73 66 33 42 33 34 20 42 41 31 37 62 14 14 56 43 46 29 59 26 31 6 52 61 0 31 16 56 68 36 37 69 67 79 68 74 74 46 63 41 95 19 63 80 120 84 72 78 30 56 65 69 88 107 67 58 74 37 101 24 72 50 87 73 92 102 98 63 114 95 90 31 50 121 85 96 99 165 175 172 166 218 176 168 176 154 116 130 181 104 142 118 173 148 110 45 50 63 77 96 50 59 84 54 76 77 64 70 45 81 91 96 69 73 118 127 107 159 142 136 106 105 130 138 102 147 135 113 136 118 144 173 159 67 100 131 111 137 130 154 116 165 114 111 98 132 103 133 116 155 112 146 114 153 109 152 72 59 85 116 84 99 97 148 153 116 99 83 74 54 68 73 65 69 81 69 30 71 76 51 21 12 35 38 41 41 36 59 53 49 13 16 19 29 48 43 10 89 11 38 56 41 51 31 30 42 28 33 24 51 70 43 78 65 21 46 55 88 60 67 127 104 58 94 71 61 57 90 67 66 108 104 49 79 85 49 93 45 95 87 29 79 100 69 52 31 66 23 21 73 92 157 151 183 226 197 189 216 219 209 213 202 215 172 195 146 140 157 139 119 107 99 86 36 86 86 57 73 73 76 59 83 44 50 72 40 58 44 99 104 87 100 81 149 122 142 127 100 153 154 120 119 122 164 96 138 156 136 143 150 111 124 133 119 133 142 138 126 145 99 108 123 157 135 82 132 103 150 128 134 118 97 120 90 74 89 120 83 108 78 76 122 130 121 109 118 75 97 73 60 33 55 29 39 29 43 10 31 25 68 17 0 60 3 23 19 31 40 60 44 45 31 34 47 0 38 49 57 52 43 16 55 74 47 0 36 73 23 48 53 6 39 41 55 75 73 127 169 95 34 45 60 20 42 29 111 118 65 74 94 74 62 62 40 70 43 76 39 41 79 49 83 109 95 67 62 81 159 138 190 188 188 196 181 173 190 202 163 205 180 196 173 143 135 115 141 139 121 99 64 110 82 81 54 48 55 32 60 66 60 65 60 55 101 51 101 150 105 77 71 139 165 121 165 162 121 144 138 154 114 117 101 97 121 146 133 103 115 128 134 129 143 100 111 117 138 111 127 116 99 95 143 107 162 95 148 125 145 134 102 70 106 105 138 128 106 88 86 101 113 110 136 89 37 91 37 90 75 43 9 62 62 40 61 31 43 28 74 32 27 58 26 27 47 39 23 21 38 0 53 17 25 57 20 29 35 29 64 72 69 62 34 5 68 37 36 53 20 52 33 39 21 62 147 77 86 45 23 55 69 104 90 90 92 65 75 97 137 160 151 152 185 143 168 194 189 225 169 175 191 149 148 114 85 152 118 126 148 120 210 190 203 150 203 163 223 207 224 175 179 139 132 164 92 78 140 83 92 80 85 81 74 120 30 30 54 52 45 66 85 65 100 80 52 54 102 96 138 131 128 135 158 117 170 105 140 133 131 127 158 127 102 117 71 99 147 166 120 140 143 169 164 126 143 89 80 160 143 137 137 101 155 115 124 117 124 89 108 84 91 74 116 106 138 69 95 106 110 120 96 102 110 107 89 52 77 57 55 71 19 45 28 62 38 29 18 41 43 52 68 69 39 26 12 37 29 17 63 26 34 32 33 25 28 34 15 69 77 51 74 37 59 53 41 41 16 75 53 58 90 137 78 97 89 19 64 95 69 70 69 135 174 229 142 177 179 177 196 198 201 231 181 218 197 209 189 235 207 197 110 138 112 118 125 87 141 153 146 172 174 161 180 182 191 205 190 137 115 136 128 105 67 66 115 121 92 72 77 42 55 85 29 40 55 76 61 54 40 95 81 86 58 107 60 140 142 170 149 156 154 122 142 102 95 134 90 82 117 110 99 104 156 125 113 106 92 148 113 139 153 161 139 131 107 100 105 138 128 144 135 137 103 100 112 112 121 73 117 80 47 104 55 46 69 70 86 83 95 70 101 70 72 66 79 88 23 53 67 57 58 77 39 11 58 20 58 31 21 24 67 22 67 18 43 52 63 56 74 43 18 21 41 50 22 38 3 71 68 26 71 35 44 26 50 9 124 122 82 71 39 54 78 15 32 62 101 169 249 210 198 171 221 229 210 212 210 216 210 214 201 219 249 173 203 211 208 178 198 143 126 122 118 124 104 147 142 160 147 191 189 200 182 122 156 116 76 124 90 73 95 128 113 84 27 81 58 77 47 34 40 47 27 38 67 53 34 16 55 72 102 133 132 149 147 147 146 147 154 140 163 124 125 71 129 113 136 107 125 126 84 101 107 150 108 163 108 104 125 160 135 140 121 134 125 131 101 123 141 126 125 90 71 82 73 61 58 104 121 112 69 60 95 94 130 112 112 120 93 76 63 88 73 65 43 90 24 34 36 64 33 61 62 16 73 84 36 68 14 49 54 15 17 43 44 44 53 38 64 63 50 40 25 29 60 18 36 19 71 46 21 42 91 126 111 100 69 32 54 43 98 157 191 193 212 204 231 200 189 224 209 203 167 226 242 174 196 245 225 255 203 240 196 207 191 190 163 144 118 82 121 122 116 139 137 121 177 154 158 143 131 159 143 132 140 142 108 96 52 96 72 70 73 132 66 82 41 42 54 71 70 73 85 36 60 49 94 59 81 170 168 143 150 138 201 155 134 142 129 106 133 134 95 193 121 113 161 94 110 148 128 142 132 184 140 128 128 105 147 122 68 129 88 139 120 131 142 92 107 110 107 57 82 71 101 99 93 84 93 71 53 99 98 94 69 98 63 62 40 73 71 89 72 58 48 0 48 46 38 40 50 68 31 35 35 53 72 52 64 38 57 26 64 34 33 36 48 40 69 56 75 41 39 40 49 40 83 84 121 154 120 96 99 41 61 85 178 191 161 187 194 217 204 195 244 211 245 213 224 255 221 188 245 239 176 255 204 217 183 225 221 215 164 170 135 140 73 121 127 129 114 138 157 149 132 150 142 166 161 167 133 113 111 130 117 91 88 56 120 61 113 96 54 51 59 60 86 54 71 38 70 79 40 42 71 78 147 160 121 148 147 153 134 132 156 121 104 151 95 113 101 115 144 97 121 120 130 128 103 104 143 155 145 152 145 129 97 83 162 130 103 101 150 73 114 77 106 84 109 87 121 94 104 54 85 51 50 63 81 96 112 100 138 95 85 116 97 40 89 57 81 61 23 60 42 48 58 48 24 32 45 4 33 35 36 61 45 41 48 67 68 46 18 59 59 41 58 73 41 55 34 55 107 135 172 120 125 97 87 145 205 193 157 210 183 193 192 205 209 208 240 212 217 203 232 212 232 216 227 208 244 229 193 200 209 217 205 192 207 167 160 139 111 150 110 126 107 136 82 103 110 168 160 132 137 134 153 123 77 89 127 107 121 100 73 58 69 79 91 87 59 71 72 70 65 103 70 62 60 121 80 54 71 146 151 168 183 152 192 157 136 114 150 120 96 109 132 115 110 139 90 89 124 90 105 78 104 145 114 106 116 128 119 56 80 95 109 124 162 100 124 82 94 140 97 111 99 70 78 105 103 49 78 50 62 84 66 102 141 80 113 124 80 76 68 82 64 50 92 97 31 75 42 42 52 33 43 53 79 36 28 66 26 73 70 33 48 66 29 35 60 67 61 57 38 43 62 36 15 62 117 103 77 100 147 175 213 230 185 184 204 214 197 177 172 221 192 201 189 238 189 184 224 246 237 253 245 205 212 197 196 211 213 212 191 151 137 130 144 103 58 101 85 123 89 95 128 75 133 112 98 96 94 99 104 76 68 57 126 100 68 47 65 61 92 70 96 84 84 76 74 21 84 77 55 123 63 92 66 86 134 126 162 171 118 118 165 132 129 121 145 123 101 105 63 110 143 113 113 127 95 92 70 75 124 134 105 105 120 120 84 106 67 102 125 126 107 118 113 116 85 106 126 67 80 93 86 88 89 71 22 106 46 60 97 68 67 93 107 85 83 35 80 63 65 19 19 116 34 47 52 15 28 13 24 48 8 66 69 56 31 60 36 70 29 50 60 86 54 50 52 61 32 54 31 44 17 105 71 173 180 193 186 200 190 212 191 161 181 155 183 147 183 188 179 194 225 208 190 197 226 219 198 198 221 174 203 182 197 218 195 181 166 174 114 123 83 85 101 115 99 108 92 117 106 93 101 125 125 151 99 104 58 70 47 89 127 87 73 94 96 79 87 96 75 74 58 44 36 37 77 81 112 70 85 78 94 138 140 166 128 148 159 128 126 106 121 137 83 85 87 132 139 137 99 97 59 98 125 80 100 109 149 113 109 65 74 66 70 103 80 99 61 113 106 104 77 117 117 131 82 84 93 100 96 58 122 118 91 97 64 80 116 102 107 94 77 56 79 63 59 59 73 29 53 65 81 50 0 46 45 44 47 32 42 3 63 64 58 63 51 50 20 78 58 1 52 92 48 20 56 57 15 61 106 195 196 177 156 190 143 183 152 183 183 122 169 166 194 185 219 228 156 245 193 230 230 211 203 202 216 207 255 206 221 226 194 175 173 155 116 158 118 98 87 109 90 127 77 94 91 94 62 107 72 133 94 106 59 69 68 53 76 79 121 130 62 117 48 50 114 42 91 71 59 53 59 65 59 51 85 64 61 57 181 117 149 158 164 145 137 143 118 139 100 88 127 105 89 87 105 145 126 45 83 101 92 105 66 119 145 118 105 94 94 77 74 106 107 94 94 81 91 107 78 81 100 111 89 109 90 65 81 126 71 64 49 89 61 93 77 125 112 75 107 95 72 66 65 87 70 76 76 46 71 68 75 51 17 59 25 60 41 34 57 67 60 57 65 36 28 21 33 44 72 25 84 66 39 35 142 190 219 198 158 189 152 178 136 147 95 104 164 126 183 155 186 181 217 163 205 208 221 201 208 203 224 213 206 188 176 179 171 174 180 128 174 147 87 102 121 133 122 100 116 100 109 97 57 97 67 63 80 75 78 73 53 38 30 23 84 79 121 49 89 44 78 89 79 67 97 64 52 53 96 45 80 129 60 97 98 194 145 135 152 152 154 154 127 116 125 123 87 139 109 87 148 144 101 85 99 63 110 104 104 77 116 139 138 132 65 61 66 83 94 75 66 64 75 67 100 52 79 62 98 88 106 86 80 78 79 53 83 74 62 83 80 48 82 97 120 93 139 51 88 25 42 43 4 76 97 44 62 77 87 70 54 42 40 50 0 58 45 34 39 66 25 35 53 53 45 14 51 73 24 101 170 190 168 156 165 175 159 107 121 56 89 33 58 151 157 160 164 227 225 223 206 239 184 208 233 199 193 190 189 169 197 165 158 140 109 113 130 151 78 89 89 75 55 76 108 108 115 85 78 75 95 34 82 69 78 50 53 83 44 62 59 68 33 78 135 58 60 62 84 38 99 50 22 125 45 57 75 118 74 96 53 102 141 147 169 182 147 123 148 131 124 101 89 93 107 114 126 128 145 104 69 77 73 125 106 124 87 72 96 129 154 125 86 125 91 78 51 64 59 94 67 83 71 85 86 66 96 141 103 62 69 84 56 89 42 52 55 51 60 49 84 72 78 76 86 83 56 45 62 63 91 45 52 128 50 32 40 75 63 52 58 60 47 27 47 40 4 37 39 36 56 40 62 39 74 87 213 193 193 181 184 135 130 89 71 44 79 39 16 152 180 209 189 169 197 187 192 196 171 213 163 198 180 190 199 205 189 186 120 170 81 147 136 127 92 131 106 86 84 89 81 88 130 96 60 95 78 93 57 108 49 83 75 70 39 24 57 41 83 122 65 113 49 65 69 101 67 98 94 80 80 99 84 79 54 90 67 63 115 188 168 142 143 126 170 114 128 125 83 115 115 116 113 129 110 164 126 110 121 75 111 110 84 87 81 93 127 112 115 126 116 94 123 118 52 69 56 69 75 86 55 89 66 144 94 109 106 115 57 49 82 44 72 64 56 96 51 55 44 97 95 149 91 62 83 75 85 57 92 60 44 65 47 53 42 29 78 62 41 53 65 66 56 73 27 67 53 52 5 88 48 114 174 202 178 155 154 121 96 53 24 68 59 38 58 159 143 182 164 142 201 197 170 186 185 195 189 208 205 191 203 189 196 177 115 136 152 143 135 89 52 68 66 73 75 96 71 93 86 124 53 94 62 74 103 27 115 117 93 77 50 61 16 60 68 42 109 112 58 75 82 69 55 78 79 66 98 46 82 79 82 111 96 109 54 60 162 171 90 154 121 136 134 115 94 150 104 76 130 119 79 128 139 111 133 102 115 55 64 70 94 114 91 68 125 118 111 134 100 133 148 133 113 111 78 92 48 66 63 115 50 87 83 120 73 78 55 64 58 43 66 66 116 62 37 63 41 56 86 72 107 47 93 53 36 38 53 81 46 63 81 36 59 57 83 70 59 61 65 52 39 41 43 70 50 69 104 137 157 174 155 172 100 138 66 58 50 22 54 34 88 188 196 168 181 182 164 165 181 157 198 207 161 185 174 152 164 152 182 215 133 90 138 120 122 111 98 108 63 40 101 80 96 88 55 74 54 114 91 130 84 84 74 103 103 74 71 79 120 104 92 50 18 101 105 114 116 125 38 56 53 53 73 94 79 80 64 71 95 99 46 104 88 154 154 100 100 119 159 150 92 139 132 115 98 97 126 107 126 90 110 87 112 63 45 105 120 73 94 97 48 64 76 101 117 126 131 152 104 142 75 138 104 92 55 100 90 76 69 78 98 67 65 80 121 78 60 94 44 99 85 67 75 20 46 42 68 78 49 43 49 22 73 31 50 73 21 58 76 69 68 41 97 53 57 73 40 64 9 63 64 60 42 117 154 188 137 150 102 111 61 43 40 57 7 44 141 210 196 215 148 182 160 121 191 149 208 180 163 216 181 183 138 166 171 155 140 154 141 128 52 99 68 88 0 64 23 49 73 107 93 82 120 90 98 104 102 126 66 96 73 73 81 98 41 97 76 71 90 39 72 124 125 133 123 97 56 36 75 55 76 76 63 92 70 127 55 64 23 75 125 92 130 123 132 169 95 90 81 108 98 113 104 113 142 79 152 123 74 102 100 108 98 71 68 115 132 61 73 117 93 76 119 83 39 128 138 128 112 118 114 93 139 94 113 109 108 54 72 56 102 73 103 76 59 70 75 46 86 33 91 54 56 67 61 83 73 65 52 69 49 74 24 50 80 65 57 66 49 82 84 49 84 34 73 56 52 42 84 100 221 136 134 155 70 74 7 27 30 18 28 40 162 244 194 181 152 93 120 117 121 127 172 164 187 173 179 161 155 134 140 147 133 130 115 107 69 75 87 33 24 41 43 17 81 0 67 59 107 61 107 66 80 58 88 112 75 95 63 114 94 79 68 58 42 22 32 79 124 112 77 101 110 73 78 100 50 29 23 76 54 71 57 100 83 54 56 145 105 96 117 134 92 119 110 97 101 86 132 75 114 136 89 138 92 102 102 80 74 76 100 90 96 91 72 91 98 48 69 55 101 71 73 103 126 115 98 90 115 146 110 127 141 107 105 119 105 106 107 76 40 41 61 47 58 38 44 14 30 10 16 70 60 43 66 28 74 73 64 43 63 16 83 52 49 68 59 32 40 44 6 8 75 53 50 155 159 166 142 99 102 18 0 19 38 35 34 35 88 176 155 164 193 159 109 112 89 110 105 195 163 177 161 139 170 123 114 140 119 120 122 134 103 77 65 0 23 0 31 0 79 18 15 33 44 28 30 48 69 83 103 63 111 76 61 58 78 43 111 78 45 60 67 23 34 88 71 146 103 122 70 77 91 38 86 58 57 102 111 49 90 109 80 77 140 122 153 123 135 113 137 91 56 97 102 66 87 126 39 87 103 115 65 59 69 55 87 118 38 87 118 70 56 68 79 46 87 56 41 51 70 78 111 77 93 129 137 119 180 104 79 112 127 106 167 91 104 127 115 62 80 33 61 56 20 20 33 46 29 57 29 82 47 15 49 27 43 33 64 38 36 74 59 30 84 48 81 85 61 67 96 129 141 174 94 79 67 49 79 64 38 39 70 20 41 88 186 187 145 149 105 90 75 100 108 91 154 160 137 173 160 148 140 144 119 107 107 83 90 54 14 10 44 16 30 28 41 55 58 24 23 53 43 46 0 59 33 24 25 33 5 73 21 27 45 45 28 0 66 60 0 52 64 74 77 66 84 85 134 81 86 92 32 112 109 47 71 82 113 72 56 87 119 90 108 119 118 103 127 116 91 76 115 62 95 107 111 95 101 97 83 116 76 96 78 89 83 120 83 89 66 74 38 33 53 36 68 46 59 82 41 55 97 120 112 112 74 104 93 81 80 158 140 126 116 104 95 180 134 103 66 88 56 40 61 49 56 49 46 98 63 63 77 92 90 86 86 126 121 105 99 110 94 79 102 109 108 141 85 104 108 34 46 59 103 122 82 61 52 17 51 69 87 174 124 131 88 101 15 178 163 161 147 115 141 96 146 96 117 82 132 136 58 61 69 61 43 28 72 56 105 80 102 90 76 73 94 106 114 117 72 71 60 106 74 16 39 14 72 7 17 73 55 35 74 63 30 83 25 39 18 12 61 74 40 21 98 92 78 100 106 106 68 65 67 88 40 67 141 133 124 160 112 103 113 123 140 130 136 71 95 47 103 108 90 97 66 75 75 83 82 85 95 71 82 72 59 44 51 3 46 52 50 36 55 70 40 68 106 64 83 103 62 74 104 101 134 50 105 124 100 74 136 122 132 146 72 110 128 82 70 77 98 89 98 71 72 105 134 114 115 76 121 94 105 88 108 96 57 90 97 71 44 71 68 46 66 70 58 62 51 117 109 72 63 7 57 43 110 61 123 113 99 95 83 203 173 161 109 117 84 117 127 131 112 118 75 103 95 75 70 56 53 0 35 69 36 51 48 49 52 75 38 66 54 23 58 90 63 104 82 28 66 40 74 88 40 35 60 71 68 91 109 94 91 104 110 75 15 97 70 92 90 28 99 101 64 66 80 54 101 90 91 72 114 139 143 152 142 108 132 132 127 101 99 88 84 94 105 75 89 93 118 73 73 95 97 77 108 75 70 128 86 47 51 61 0 9 67 64 32 68 64 67 52 48 29 89 93 37 93 47 81 95 96 97 55 90 80 95 102 123 77 124 105 93 126 121 103 86 79 93 97 127 93 115 92 74 99 117 102 75 74 82 79 84 108 77 46 94 33 97 59 82 68 45 93 129 120 97 64 12 30 43 69 53 83 90 72 68 72 155 174 181 162 90 82 100 98 137 138 98 79 90 66 62 10 29 35 13 11 15 31 47 33 66 74 12 53 58 71 19 52 29 35 55 77 78 46 41 42 90 39 37 41 9 36 55 58 69 61 121 118 111 82 92 21 48 122 62 95 66 114 75 84 83 88 85 116 81 104 75 102 131 161 161 106 133 75 129 110 108 86 119 90 73 86 88 85 77 126 116 95 90 72 91 90 40 106 80 72 62 91 61 38 26 68 68 34 60 73 44 75 27 33 43 54 85 48 69 80 80 90 61 81 77 121 123 86 91 88 75 114 108 115 75 91 101 103 49 79 130 58 54 73 90 83 58 71 58 60 62 84 71 27 41 42 54 56 32 40 62 64 136 80 106 82 93 20 29 39 38 66 58 60 56 62 91 84 112 85 90 92 20 53 59 50 78 27 72 54 22 22 21 67 21 25 0 48 3 33 47 17 58 27 26 43 57 48 25 25 25 67 29 86 46 70 33 60 50 36 65 49 35 3 5 38 85 118 119 81 91 110 59 78 82 66 97 57 80 88 55 71 118 108 105 65 44 89 144 158 165 178 94 131 100 83 119 76 111 96 105 114 83 80 88 118 89 94 81 111 64 84 93 43 90 55 81 13 86 62 78 32 34 62 38 61 58 51 28 67 35 70 62 68 31 32 83 90 87 65 96 74 106 84 32 70 86 55 88 50 91 88 47 87 76 50 45 42 73 102 64 67 58 36 15 63 43 56 44 18 31 48 28 52 52 59 72 65 80 63 81 101 60 48 88 45 57 66 92 40 23 78 60 30 98 112 114 84 38 36 87 53 74 84 50 39 14 28 41 36 44 29 40 51 34 55 71 45 45 40 59 52 87 1 58 50 59 50 40 83 38 49 64 31 50 47 43 23 0 40 60 48 48 39 36 108 88 121 81 112 76 62 87 109 76 55 117 48 81 78 86 97 44 78 80 141 147 140 123 92 97 105 108 78 95 33 82 92 89 41 96 103 69 89 78 62 101 62 101 68 59 65 91 48 119 115 41 52 79 102 39 37 59 19 18 26 48 84 61 56 44 69 70 58 66 54 82 84 26 80 68 83 87 93 97 60 46 77 74 22 39 42 44 51 1 69 80 56 62 44 27 48 14 51 50 73 39 44 74 84 47 54 33 75 64 55 122 75 61 85 18 30 83 83 89 61 25 23 86 44 77 100 117 56 57 88 67 47 39 58 68 36 9 57 10 46 40 43 25 50 22 16 34 17 84 31 45 58 11 41 36 70 27 62 54 11 43 46 18 51 15 54 16 60 57 33 76 56 39 65 43 58 28 64 81 40 41 106 69 64 34 47 65 112 93 103 100 71 94 58 140 76 124 137 182 120 157 127 140 82 59 94 85 106 88 100 76 100 110 52 98 86 47 62 60 62 90 85 124 92 54 51 33 76 63 25 25 68 62 87 83 86 36 57 56 76 40 46 99 38 72 88 55 59 84 79 52 73 53 78 63 57 72 67 44 40 58 17 55 18 64 35 61 55 32 71 31 55 18 34 74 15 57 8 30 49 63 49 41 59 22 91 81 86 84 66 95 72 61 110 87 42 47 68 80 53 111 95 84 66 62 84 0 55 42 41 15 29 15 28 41 0 10 17 56 69 23 0 32 27 39 27 25 63 35 66 73 44 33 68 78 61 54 16 15 20 30 74 37 74 70 25 44 34 51 65 38 72 54 44 11 47 44 78 43 21 45 0 25 78 66 64 69 71 54 81 53 77 83 97 141 114 122 121 107 112 102 49 97 121 72 129 58 83 85 118 67 76 89 97 95 97 57 77 33 76 90 57 92 39 46 48 18 75 33 29 30 61 80 61 36 34 69 12 85 50 21 56 52 34 59 76 54 58 85 76 66 38 51 48 65 26 94 81 57 49 48 27 74 76 17 66 49 0 23 60 52 34 57 53 53 51 96 31 52 68 6 73 89 126 100 88 95 45 52 89 58 69 86 66 82 96 100 73 8 16 83 65 65 65 62 42 26 32 24 39 31 22 18 34 49 50 59 18 18 40 52 0 62 24 36 11 40 34 6 21 39 35 56 23 67 55 31 42 73 44 81 76 84 84 7 52 25 17 36 64 66 75 67 64 38 62 83 52 24 36 68 67 51 86 48 38 106 98 48 72 92 159 120 136 90 153 85 122 62 57 80 104 52 59 69 83 64 117 97 66 54 86 111 69 25 87 80 122 48 67 55 65 40 40 45 52 63 55 26 28 33 65 56 72 45 22 56 22 35 41 70 57 60 74 46 12 79 78 53 68 107 93 53 49 86 26 43 49 57 60 40 33 16 53 57 39 27 49 57 42 40 27 53 64 69 53 45 53 106 118 139 101 101 82 48 75 31 73 74 81 80 67 88 6 41 111 61 94 82 65 39 20 37 21 2 30 56 17 47 24 47 35 30 57 15 52 1 13 72 47 46 23 37 21 9 45 31 84 55 76 42 65 53 75 87 83 66 65 76 59 6 38 49 39 96 15 43 32 54 51 56 51 82 52 36 69 53 43 43 89 28 56 90 95 69 67 96 134 109 131 141 112 106 110 95 82 93 83 96 84 78 93 102 82 76 91 85 65 64 49 65 70 87 71 62 54 73 96 49 7 44 49 38 42 78 53 71 57 59 75 36 20 17 77 78 60 65 40 40 63 30 52 64 55 43 63 54 60 104 36 40 46 59 90 50 39 83 32 65 41 27 74 88 49 42 36 62 61 89 39 17 63 74 50 77 118 95 75 85 95 45 50 29 100 56 60 84 43 53 32 47 67 17 65 87 59 51 15 47 55 22 41 55 76 25 9 19 51 24 19 26 42 21 46 0 22 40 49 52 23 17 28 37 81 27 25 33 72 73 102 95 89 58 51 89 41 56 25 50 50 1 47 55 49 66 23 42 64 47 36 37 48 51 60 47 57 61 103 103 81 46 38 70 104 103 139 106 120 112 97 97 123 97 68 72 51 70 86 122 132 108 131 60 74 67 96 39 62 62 47 61 95 66 84 67 50 27 46 87 29 32 28 39 49 33 53 72 98 19 32 50 18 80 64 67 63 50 62 81 77 56 75 35 48 36 78 19 89 55 63 72 54 68 62 36 67 65 46 19 31 34 20 68 75 41 64 48 41 51 60 49 49 84 64 93 86 54 61 74 49 14 71 68 1 32 43 18 19 18 65 26 35 38 7 14 36 29 34 48 35 27 0 0 57 42 18 18 14 25 29 0 18 42 13 42 61 16 41 61 0 12 41 47 100 77 87 51 66 74 79 77 41 58 97 27 56 73 41 31 63 84 33 59 25 45 41 25 23 90 50 28 63 57 62 56 36 84 62 106 59 69 138 93 88 137 160 172 143 107 95 93 26 81 86 89 95 63 109 71 68 94 68 102 84 57 25 53 62 135 127 78 43 40 65 96 61 59 27 24 31 54 73 51 22 37 78 27 36 91 24 63 99 68 72 60 44 57 48 69 47 60 50 71 52 7 55 35 72 41 34 40 28 45 58 39 35 51 39 48 70 66 67 49 53 57 27 102 39 46 25 26 54 59 60 36 33 14 40 29 49 46 42 0 4 52 0 0 3 0 26 51 14 43 22 37 20 17 63 46 22 12 49 33 32 51 33 43 52 47 43 9 11 12 24 13 9 16 44 20 5 27 33 53 28 39 53 51 43 51 28 38 29 37 30 21 44 24 19 18 8 0 58 0 0 25 39 26 46 13 70 73 83 64 54 0 51 53 53 137 107 156 139 102 152 100 118 74 63 45 44 39 69 71 69 89 126 72 95 99 127 56 83 62 30 29 133 62 99 83 66 61 30 71 37 48 66 49 34 24 51 34 71 24 43 65 40 50 85 76 42 58 61 93 42 107 71 45 45 51 44 71 61 55 68 68 54 92 42 90 51 53 33 101 54 63 38 46 32 62 44 55 41 35 89 42 49 25 28 72 10 53 55 37 34 45 24 7 32 41 33 23 0 13 19 35 44 75 41 64 50 64 43 39 62 38 44 52 35 17 17 63 70 19 62 18 55 63 43 20 23 33 14 25 0 38 5 21 10 25 56 52 29 0 41 35 41 31 27 21 16 14 9 25 0 14 23 7 4 0 0 0 17 0 10 44 16 35 30 33 13 43 14 7 0 84 132 170 149 141 145 53 116 50 85 94 76 120 81 51 65 53 106 122 58 58 94 116 54 66 90 49 93 88 74 80 77 72 83 69 65 33 53 95 65 63 48 36 65 30 30 77 41 65 55 86 63 62 57 56 54 50 64 25 31 7 64 30 50 25 42 38 50 45 72 53 37 69 65 65 62 66 50 52 89 44 99 69 71 39 55 17 53 37 23 4 69 58 10 36 70 34 41 38 42 18 60 10 82 6 35 51 56 43 11 31 60 57 107 39 58 30 0 36 51 46 42 41 21 14 57 0 43 7 23 29 19 30 27 13 0 33 8 59 29 30 22 9 1 3 25 20 21 41 41 14 34 34 0 27 17 0 0 20 5 16 29 13 12 0 0 0 31 14 33 39 40 25 0 15 20 24 105 131 108 105 109 88 106 157 104 57 107 85 85 73 44 86 80 83 88 139 33 64 77 104 105 80 56 92 67 49 99 44 63 54 66 73 59 71 32 67 68 50 28 31 59 12 43 48 29 67 69 78 52 68 27 52 45 36 67 44 49 16 60 50 77 52 53 57 79 43 65 39 66 39 42 52 58 48 40 34 55 59 15 35 78 40 57 36 54 45 34 34 31 46 63 60 67 52 42 27 48 63 80 56 55 29 40 33 45 1 63 109 32 38 14 55 50 45 39 28 55 34 54 51 26 39 11 68 70 21 67 30 20 22 30 20 19 25 0 0 6 0 24 0 0 5 2 0 21 13 27 37 46 4 30 19 0 0 0 15 0 56 0 0 47 21 11 0 6 8 14 4 2 38 43 41 0 4 98 167 112 98 117 139 140 99 94 114 74 96 76 67 102 65 93 104 110 33 52 84 102 81 57 86 32 111 132 93 124 59 93 71 38 71 41 62 27 17 66 49 61 24 74 64 0 51 65 21 46 56 14 47 60 16 64 52 33 47 62 32 76 51 91 76 54 42 35 78 21 68 49 60 27 54 37 56 23 33 34 44 30 80 62 47 7 2 27 15 56 49 50 67 79 25 25 40 57 67 26 63 40 48 51 17 44 46 45 14 32 41 17 43 35 3 47 23 38 13 67 0 28 33 51 36 59 54 55 73 23 46 18 19 3 13 3 28 19 42 48 25 0 5 14 0 22 0 0 45 2 1 31 24 27 12 3 11 0 0 0 20 5 17 23 44 19 43 0 17 6 47 27 4 0 24 20 149 116 126 141 123 100 95 120 67 83 98 74 81 81 77 88 52 120 48 74 78 90 107 65 75 86 62 143 115 80 67 99 60 68 21 43 7 25 16 37 74 36 59 16 91 48 34 18 67 37 38 50 60 78 74 63 2 27 19 68 43 55 3 30 58 101 41 39 21 50 51 34 91 71 34 27 22 39 42 11 31 21 26 6 29 52 79 58 99 43 38 34 56 42 55 34 70 52 58 38 46 51 16 63 8 62 46 44 0 57 65 23 62 28 15 35 44 58 7 109 47 99 65 27 78 31 64 31 45 69 29 0 31 26 0 34 3 0 44 1 6 2 12 0 30 4 10 40 19 44 18 0 8 13 18 22 12 14 0 30 20 16 4 13 29 0 31 33 41 51 39 32 10 16 15 66 64 134 166 128 119 106 115 102 92 93 102 55 83 75 76 96 44 47 81 52 72 56 46 104 105 89 89 44 115 74 104 91 55 34 68 26 68 51 64 8 45 117 59 81 31 9 84 56 48 44 64 38 27 37 40 55 54 21 58 44 21 53 64 74 62 81 10 90 48 77 53 52 45 40 35 29 57 26 70 23 58 40 15 74 59 31 53 26 19 6 13 60 34 27 58 59 7 41 33 0 57 42 60 54 49 38 63 27 29 16 62 18 21 28 21 44 45 32 19 48 7 52 5 48 76 0 50 31 28 56 31 41 37 16 0 16 23 7 35 39 0 27 11 0 27 32 20 42 14 37 0 47 20 1 36 42 49 22 29 42 0 30 16 48 13 40 16 0 27 27 36 49 9 0 23 11 23 3 118 141 125 131 74 95 85 120 101 110 60 78 47 64 54 38 56 75 71 64 73 52 83 33 131 35 53 69 95 86 58 64 85 46 27 58 32 72 32 14 47 14 58 54 66 35 79 29 55 46 21 33 36 34 3 31 35 26 33 55 74 31 34 87 70 55 41 71 96 67 5 42 54 54 53 1 84 36 6 50 0 48 23 63 24 26 37 74 20 55 9 44 41 42 16 16 52 23 6 46 66 53 32 61 29 22 37 23 56 27 48 26 35 13 20 16 35 66 43 97 46 45 43 27 10 26 61 62 34 0 0 53 30 33 13 26 17 0 38 13 4 21 43 22 25 22 0 31 31 11 40 27 28 30 2 22 16 3 0 47 10 7 51 49 34 0 20 34 49 14 0 0 28 4 63 62 2 165 108 96 135 115 121 108 78 93 92 68 100 96 59 75 52 33 63 54 54 44 82 74 59 89 83 81 36 120 70 89 46 82 62 21 43 41 33 16 84 3 61 17 43 36 47 92 79 60 35 22 28 30 27 0 8 0 26 16 36 26 78 43 20 55 69 23 6 42 77 82 54 59 40 15 41 51 55 49 2 11 83 38 42 10 47 20 55 50 56 55 74 27 50 65 29 48 95 1 38 9 67 4 41 48 33 48 42 28 23 66 20 27 24 68 40 43 26 33 31 53 26 26 25 47 41 7 0 25 67 23 6 18 31 24 7 25 0 13 42 28 22 33 24 46 33 16 27 0 28 60 0 55 0 49 8 17 15 60 46 25 38 0 19 42 16 0 8 26 0 25 21 84 42 0 29 36 124 159 167 124 97 103 93 61 85 59 94 78 73 95 50 55 59 46 65 86 89 60 82 99 127 52 79 57 99 76 82 74 18 90 56 57 53 30 41 70 38 38 84 49 33 63 37 40 28 60 37 16 24 0 44 13 72 67 0 0 41 21 13 37 15 82 12 38 71 54 62 31 75 45 65 55 21 10 42 29 35 40 42 76 12 48 39 13 33 59 14 50 47 36 29 21 24 10 50 20 26 38 22 52 24 18 31 4 10 20 33 46 32 85 22 47 19 14 32 10 11 5 29 43 35 34 47 14 26 33 37 13 0 42 32 30 26 27 28 0 26 36 18 0 30 21 32 0 60 23 0 21 0 20 17 7 30 20 34 28 74 29 8 39 35 11 14 24 55 0 45 57 17 0 48 19 59 123 140 127 84 104 105 108 118 78 108 74 70 60 82 69 71 69 92 79 38 109 54 88 100 125 83 73 57 103 94 49 85 81 48 28 44 0 52 0 63 43 45 35 54 29 46 51 50 36 0 44 63 0 0 6 29 37 19 46 51 15 1 43 0 59 10 57 23 24 46 44 55 61 76 32 24 20 61 31 42 79 6 45 66 22 54 50 40 65 15 9 16 22 46 37 15 53 5 27 18 24 43 35 22 5 10 9 13 46 6 37 36 30 25 22 0 22 0 40 36 3 41 34 49 10 62 91 25 43 5 36 3 22 13 12 27 37 36 33 7 4 21 29 28 0 13 0 6 36 40 2 32 7 16 20 34 0 15 0 5 10 1 27 60 13 0 45 23 11 18 0 40 63 25 12 43 5 111 133 95 97 119 92 126 76 89 71 36 38 14 28 71 19 44 76 106 78 73 112 114 92 75 97 72 68 65 102 100 156 37 82 35 68 10 58 26 47 80 33 8 75 55 53 75 65 49 22 36 40 29 0 43 32 19 71 9 26 43 48 35 47 51 41 66 34 0 5 82 38 51 73 75 41 29 40 41 69 31 53 54 14 43 30 9 0 17 33 42 0 15 21 7 22 49 22 21 39 35 22 33 36 14 39 30 33 9 22 10 24 42 10 41 54 0 43 8 18 54 35 39 27 2 66 59 24 10 53 25 20 0 46 53 15 2 36 14 18 13 38 1 63 28 51 10 14 28 23 36 16 33 9 16 23 23 0 41 17 18 29 21 0 12 12 42 51 0 27 32 31 19 19 57 51 43 99 118 134 117 121 100 106 83 81 65 85 96 59 86 69 57 44 43 66 79 45 107 102 64 60 111 86 75 46 94 81 80 80 30 47 32 34 37 23 35 21 48 82 53 73 46 43 37 56 17 66 40 35 39 44 42 0 30 15 16 3 35 44 58 33 7 36 37 37 36 35 32 50 46 59 1 19 12 26 17 52 25 56 3 22 11 25 7 46 17 48 34 29 0 59 36 0 16 14 64 39 23 58 64 34 6 19 24 45 25 1 14 0 27 0 17 2 11 60 6 27 29 11 13 22 49 20 51 2 29 37 43 13 16 28 62 29 16 0 25 38 33 10 32 10 43 40 19 46 13 3 2 2 41 17 20 0 15 13 0 40 22 29 47 41 18 27 2 39 5 7 28 39 32 11 61 32 104 109 80 120 111 67 90 99 97 67 108 96 81 22 55 63 39 89 90 94 48 78 85 80 72 86 96 62 57 80 119 67 91 67 69 78 41 47 45 16 16 54 0 11 34 33 53 63 56 19 74 53 19 6 6 78 32 19 39 27 58 46 19 36 36 40 45 6 42 11 24 57 39 14 34 0 16 0 1 45 9 47 28 4 32 3 27 15 10 23 13 40 46 74 28 27 5 0 38 11 6 13 25 21 0 20 26 48 26 19 15 19 0 38 29 49 12 12 34 1 29 24 54 40 0 61 43 2 22 31 41 40 25 4 20 0 61 3 32 10 42 33 2 0 0 0 42 45 10 2 11 6 28 12 25 9 39 32 0 0 48 0 34 16 8 92 7 32 42 13 43 26 17 75 66 92 55 118 102 90 86 131 87 134 127 52 89 112 105 79 78 37 59 30 89 51 57 98 50 111 84 65 78 73 50 75 68 75 76 68 63 34 51 42 28 29 24 66 21 45 2 10 15 62 41 77 34 31 31 55 47 23 12 21 0 55 56 28 54 70 14 8 19 11 10 40 21 0 51 26 29 11 54 49 30 25 8 6 0 26 26 17 0 10 31 59 4 47 51 7 7 32 17 0 22 5 16 33 27 65 27 17 0 0 27 21 0 20 15 41 0 62 7 12 34 58 22 27 43 12 33 46 52 24 22 10 60 56 17 26 3 37 29 13 8 0 15 12 21 27 34 24 0 19 27 33 30 32 0 22 0 20 36 16 0 0 36 23 0 6 7 16 51 63 33 38 25 0 8 19 4 0 41 45 116 127 137 117 92 109 137 95 82 91 64 74 100 51 56 75 49 106 70 48 94 55 79 96 36 70 80 74 74 0 83 107 113 60 75 72 4 19 45 24 32 33 9 42 79 17 40 71 42 26 102 52 70 33 42 42 28 24 20 59 0 16 55 35 0 0 0 14 14 38 6 6 2 2 20 13 28 2 13 28 27 0 23 19 46 37 48 40 12 34 9 29 24 0 46 0 41 43 5 10 5 28 16 0 25 35 19 38 23 62 3 60 7 46 37 64 11 0 0 0 13 43 67 45 17 50 64 0 35 15 16 12 41 31 0 13 0 0 22 0 22 7 22 60 41 22 31 0 21 0 32 48 0 12 40 18 32 28 2 35 26 43 0 41 10 1 0 37 0 25 29 15 43 38 52 42 83 130 102 111 89 137 103 74 109 85 45 69 99 89 65 55 78 72 70 110 80 115 95 115 96 81 76 94 87 54 36 92 114 73 102 50 2 75 17 3 23 50 47 57 45 23 3 27 92 62 94 57 50 3 63 33 21 38 54 57 33 39 17 27 68 15 12 40 28 0 6 22 12 40 37 50 39 0 1 23 42 56 60 5 31 35 18 36 20 36 6 23 27 9 22 4 46 48 8 43 13 0 10 0 0 26 43 18 52 30 25 17 56 54 22 0 48 20 25 43 58 47 27 30 36 26 10 77 20 64 19 31 7 37 7 26 29 0 43 20 0 13 28 36 43 54 33 35 36 0 26 16 35 39 23 8 31 39 12 59 57 22 9 23 0 26 61 27 43 20 23 4 62 17 47 27 42 43 \ No newline at end of file diff --git a/data/libmv-ba-problems/Readme.txt b/data/libmv-ba-problems/Readme.txt new file mode 100644 index 0000000..9465ad8 --- /dev/null +++ b/data/libmv-ba-problems/Readme.txt @@ -0,0 +1,5 @@ +Problem files are created from Tears of Steel production files. + +- problem_01.bin is a final camera motion refinement step of 07_1a scene. +- problem_02.bin is a final camera motion refinement step of 03_2a scene. +- problem_03.bin is a final camera motion refinement step of 09_1a scene. diff --git a/data/libmv-ba-problems/problem_01.bin b/data/libmv-ba-problems/problem_01.bin new file mode 100644 index 0000000000000000000000000000000000000000..74891e861768cee8d80e5ce588a9a651d80da3c0 GIT binary patch literal 104514 zcmZVGd0Y+c|3C0TiPCOMg@krds#(rl)r6#tD0NCjB>NWHQ=u%$5|Mr1cWTaDGifh5 zMYb%-ZHeqlge<@JIiK_W>o<@4{^NDMd(Ji2bkj|^ z|C^t>ni~A0R`o9p`D6rgyVuxJ$u?3V6LMSk6n<8M9sfo@g&Gfe{EO{m$1?}FzWgn| z3z%AH+ka~^=l0()YIXB8A_sE6!sWclond^(q2*K%WH0TP#8d|Za!*Ay-xbUaXiLuy z=J<^kRIO_iu^uw+wTwTJZox0=vy7Swc`j*1ME@8=dR^GdcLUP^Z64W4+_tY~6q}Ku z>_?`yoFDPRjNjdJITZ@^j(4YuDk6K4`AO?}4KR(+mQwbp_{f_6)Rmv_-8MoVsJ@hc zl-8e*(^yJHLY@{ok~6JbKz312;WfeBhc@3U9>wPt8&J!uXSn4-uKI5wzjJ{BfB5-A zY8K=#)0T1{7EL9O&CTMwgLw>XX7wkFYw7OP1814rcF1#>IR27rcRs=+j#>iw?^&tL zaPCpkvUDx41*TbHK29v|vsshsx@)1^Zpa7AqxnA@HTk5b z#d+ahVaMBLzL9B^+fk<=mj}$0882K+YFirdI$+*I+xS6$To1k~BMGgRBE@SALpE>20@6maO{NRx8?+gz^>*8(l}}FEtX$Lf79G_Le`LxC%b$91gYrPc106sGPWC;Ytc<+2&Mzt&J3RJnszjcTzSL4 zNHM+~NxtmQ(JWbiNj|BVS5rHlyPU60{@LOvGXnDy+V&JJD&}`BCH+?|bNc~#Wm&51 z+xDe0sZtYIex|j+2Kc0*@Nj5 zNJYQLleQL{zt$p+UGur#V17ee&5q%2?WT6*q_;zh|3Ge-G*Gt9+)k!9aUiKUjxcsU zXZCgw8KW_n=mX|2w5?v6ezo#;H!^Nzwu>Tbjql)&-0mjx8{a`F_F4PoPI0;M0J4op zk@W@h588TEHMyuAXd>de-@U5H)`c56`aly`ziT6**hkKbhsA4GO(v^*GO~UuGw(mH zsNcydqW5l@D_q}D^4djQ+=(hq%vq!~XDxdXAGgO6Cwgq>`m4-c^{K_JXSWkqhE8=; znDZa&-ak>FP^nOaD>c`7Wz$pIa)JYxA$kKx-Ijut|@=puL;yeov zZk5DQxsPuX`waEg6&{V|M;vuGz;cdp>f zRAz>gWpSXb1!v}KsWkHkniAKnEr?!&O_j!fwl~=)_%b2gc9=6)nY^>r#ZK3Zxb7v@ zO7qq|hBzcMB366FaEdutb9^~j8hVhR=lRG6f>E?(PirqG=FHa1VU`Gjjzn&`>7q@U!ft06y@uvD3=5&gLA{rzQHr~4_-uOAs*$kT=W z$@AG=WQy05dT=!P=4k^lTs~ViRAsKE%;w7T`pSCM%vPG{U%!ZhIep0j?M_Z%-k;AT zb^9a}meeV3m})$Geh9_q&vlcHj24x1u&tt&n0lrgDO|5r&cV>AN^;PgV9vOUTJdm| zc^4+(lCE@-rEHQY`?>m3P86N*LdrkOm1aR>DfuC^t6M2&!&#}0EplrV$5!ggqV7Z~ z4f*0F(JtzfrtL44bKp#GBp3F<#QT8YtJW$r*k~D-HmbTQ~i0 zuAg2mB-iTK6MkxeG8@&g9ef=$?mAjeh`zDW=>88ai~F^e7wCvY1$HBl9d;v1QSzUY^O34TJpGpNuRiV zU-SNFBxi`=v7d;!{%4e?MB0OT^kyKDK4^o?{{PG*56<;N8<(2kK`731ul!SlS!){+ zu>X|OtU9Ajy{J9tcJYda%t2+4>0<8ev~S!epT)|4g6@|Q&OzUZs+VO-Gvur`pV zp*wq|Y=p|}4vFKkBL8w%*TyML+n!P)Y4Tqp_H?PzOnRY3eg3b3h<d_rBA_jCN4dPoJ(R{^_Zs2|bCfuAU=63Jp9!O>N##9=ks%8R zXO($ZIG#KDbQ5>#!ubF7b8Q#V{lO-prh1pstXoA;&O1%W-gloAk5-uh$qt-e`ebh2 zItQis`8$X3TQ-?US6`Z9qoQ9oO*R4 zkcb(qE`y7v(v(fh;uh{aR{Sq2OKF-kq=b3OF*i?bsnY!UFrOO!{2_6q%Q21sqqv5r zJ?qQ4h#f`ri@r)@Vm*uan9$+sZZk`1^6ZvVEhi2VbG5H=q{=XUsa$+O+tnL>sY;XI zyqg&QwAH1dc{it+>u#TyQNh7MB%?*(w@dY8FWNf?Ga_gTG!K+ zM(157HENb7`DEBrjs~OHPhj0DZt>3P#EXhmN@F`6@oCH|3;kR;Mg7o{GgQKX zZ^ZlK-ZD=xihHk}E{}^Zg(Q$B?;k1OPaD4XA&RCZ$htl5!zt=VaxYVBgZ2=MPa4Wt zFp7IV-Pec<*qcdOmLcV_`0?Dl2Kyk;12in`ZYr>HjGRWMuis^pZ2RHpNYGaCM4FEu=1~z ztr+jiDe4yNFY3e#b29D9DA_nLZO|4rZgla1IS_$2f!t8MR{7pIrE?{bwe5qf@X<<6QE&WiO}~j6OwO{YmHB{q4sDx8 z4dIqFeI=h`3+23>B32M*9(9k}Yl)y2db}T)YG^y~sjm2mnk_Zy_;uxY&OVJN+|_OQn%(i7;&WHf zv&A&k*+Rr@3E}<0oP)N}NBxTL`A(qryZ9*0^W=3zFTV-=k=g4wMSa?`OxobS6WOIU zm=6H66WU%2*NZj$W>U-8|IM}C!XP5lZzg})IEYi!M|{{!>+?s51$rTTAed}uTR(M^ z3!A%w+O+W4RmJNx!+RWoa#!%qe&aYr-DS;QI^g9&V%qaCej=FV(6&SUe6e#!7Dbhx zRnEb@xc-EHM;0HX+n-a^HCLRX6U@%JJ)D`%PXZGQZFA4di?h0Ipt^E(O7lK&7ICrL z2LAigncOU>x5iwh*G;b{estZ+2Z5OYZU54!;z_mz)X!ILO7mOPCZ^dI@JH5abBg*< zt?P7V<@(|yt~>b2U>u-LawV_mMBO23pJcuA^MX#f7IC)j5Fc_{i&NBJ_IpU1x;7Ni z`}Xrwz!*YXPmLSJiwn+DSAP9(-jXpQb`+fDdyGPyqTasc4LzXiPNJD8Ix``%MQs*AOqbT0R8KZD^|wUtO#oRY8qx z&QOlW>~J7q8dbqpGJ#wp)X!4d66@$ku5<6c;HQEqg0_`6D_jgG$*GOYq9|^=Txx73xbz zXG)^Y4snYErr{_sKG1ek{W{_E!I)Olt5d$OX=TnNKE5}`$416+in{Nc4U#Hp3AbY9 zavTlj$8UI_3%X7Gh&QAEtiGc(DQYW-&GBYU_Wnvk-X3P;IbkAgJ=5nv2G1r!S z60wwC^Ttluk9kQI(Gb2A=RU6EDxm&;Z-*q;l#<2i-o|slSU{W3P*?Kg-V{1A*G*{- zq+cQq?@7UTM{?XysGE9qVP?Myl-;U)isyov(~*YON!>|@rCGE_n}_Td%t6-=nAo!< z3%{@{=N3S{cx(^GbI^R*n7a3P9+;xKfpU7UmWKa+D9 z>JwRgMqZsRYxwvX&j)kwTN+yE8A^^c&7<=g!(@v4o9YK=h@AuSaLwu~+#{$bjOfP< z82&(}ZuJc>0Amhq15QjPoh!TMkUNrh(!WN9D$TW$hs2|#ojCEqGcFbCSKkj~B1T@6xsK8h7J;e#3fB<3 zIb_D4J+ztSJmq+@R#p>LzxUv4>uz%OP@mJ_z)am#Cv#5I6BdKffVMk}7LhTJ4$_0a zEs-hiqiiF85b+NW;)*|NvYt>cOm$(}SKXDZiZT+Gfa&`Mo?EIdA>DQ#r>8LSGR3pP zOqmVzWLc$Mte`YY+bs!unbJxCm3VG1~PleMLP0Ju1s<7HL5O>+_LB*e$X*f zHXrIweFB(oEnWE=`9p+wFk3#RA^S%;WKWkOdijA3GQ~4U{?{_{gHsWnJUU6X4eI0D zLzsKBba>ax*1~cypFgCbAHQdlugYY!@x}!*#WTq16Bd)hN@aM{spYayQ2%d96mydw z#5dWD5LSTEg0`~R5v1>>658Uzbme$v^p7O3T`0k&Au%#VJs>@faURL?AOE=sE5Weu z;XU@HA9<^)oSsew$rR5I)eeM{Gb_vSuszW-PpF%jEn((*`0!c9NJs!P>s=a>zb8p= zuNwN3zq@j-9WRBFUDz7jD|nhL2I``E67#e$ke^mCR!9WX?=8Ha9+*!~F0ZG{ZZ1(C z+pZ}-@Xj^?Oa9joTzs+#AQvSwo^eudz69olH?*JvEQ< z-`1Cx?42g0f;sRUJ`V&PCS&VA(KWA+$=-rldTRmsq3#pzy?v$Z7}OVx*v6O*kK{{@ zqlGju|2<7ZW6VU-aQJWf*1A%e;yJRcdMdfX@;A=h5hHsK_1;Yd%#gB!{P5$^LOK|` zCva|P+#q8Xbd~TCH)YSj2)(n&bMv|it(Vrx+@OA1zMJ{k_XzJ{KT}u*X5}OJe#Ges zIVn#|vhewH*#j`XcaD<3Hfjl5rks^!LjBv({mkFC&3x0t`9cO5>!viMG3gVzb(gNB z;MI3oBbch&#bo&oU7;|bROSrzbGME#FV}D2kIz^xWPU!CV?`7RT(z=YjOLnj8bk}pF|B%{!Knc_MB=by#o z$Pg3Zb4{si2GrZ5&ogZ&Zt+H2mJ6%FB-N*(R8LLn^)GYDJnf!*Etu#t0(r8-Trx(vZ6r4i8SxlQ#p~zffc-Xtb=OZa_3AV<=!d{m&A83q zn35%AgSl6lh8_|9sbK>~NerFM_);*p2An6)_8ld(?G|M1P#@(C;M%FXCURvN2(i~wum~B_!Gu{asD(8`>S&Qt*K`py(Qai9r#ONW}LZ3 zo_y;qq-NieXP!zvRwgTcxqct0WEo^B0yK zy(ja6dat5p=5^yJ{KG0w$OSY07<^ZlW=-v@oh;eqI)Xn7{kUu2CjVAU7WRFAA)5#F zg=){4{k6{cXY3YX6Bxro@H(|Lr-t4RmG~rCD#!Du_$9ftK2#X^;=9ZS>S5boF_s@4 zv2XJhArH)lJ#gLpXhMCciIli>4CWP|t2|c!Alu6$g=z1)@&BNns`s9G^U4YzC-a5P zU?e-?b9-w)s=UukiMr(=rTNtPle}p#Q@C_ZgZG8{E}JjR5yBp?%ik$%0dsmQ+(#Mo zrWTTOC7?o4VHZmHyhyOK*5Mp z545RA-B$?1b9(dHP+?uq971*rSX?}4t2 z^TdfhCxikpP4nSc9-2`nc4tenMBFFWS|g#5pFHg*{;IdZ!_DFNSh%Dv&r^EaoG@{3{wgEyyCO+?Sm%NT94hrBYOv4 zfI9Kb6zOkw!$#~?VIP@n`A$Brw8=KGfom2Za%CHoUeY%v+iT(!1%2#qBcT z02u$_@Oke3Lh2lSRAOb3!cPG+ds%;~%=M^{oodf-hI-bRq3D){1fQG03kSjEo2Q}R zsq?73+!GQ+C-4zqW=u1nzUG_|?xYXpA3%LU7c1m<%@0#!1>q2wL&j-n#iAH0)a#67 z|F6aTbTIp`_ol9)GeR|I%{N1RL8lE$3mA)!4lNN5gSp)^4Rr}$N_jV)m%MgJ=fl9b zZ_%dC%g+lP4uko@+VGu{V2}KbCgKO`CBhLfRci45X&g_nvoA~hTvzcSU`CJ7p$cbQ z7J_0e_}=Pi=-z5awCB-e+&xtkj)K|yJr%7Uu#&poUL-Mg%;W>WEYdNe?td&2oHcCt z_fW4I>x9mZ4#1t!*MwtW>fWWIo_6Wf%89&0&2KF~9?a8ZJu2Rp7cLzf&Rf1uMZ2wC zkVfAi{2<_(a2(9w7pdsunGC9$7A5=lNfGtVCFj-QOP>EAFE6Cm{BK)mu-1D)Z6EJp=`Zy{5G&!I0Gj8d@3?}kw;~e)=OsIF5oS|#Nl4l z4ZdFJ^Td|dypW1~T*e{ZX&U~MQze`Q6Mi@q6@TAAc_uYVUVq-k+ksjAQ=2M_Zxntt zS@XA`zPy(Y^7oyAtv*x>=fK=9NJWw@dDOZOcO?d81^f^&!%Jb_Uf&h=y|m>6cc!AS z)4nJtAqL+Js1?qGxwtVE-MpGlc{@LlZ0Ww2?+a#NR~;(G;ek*g*zr_uDzcm&fI2m2 zipA6S7j#t=kjPzKv11DzHwt z2|F zLhXC-QnG)*IsQK|bj<*2a^p+kb$?I39O_zcLy_N;Fr4RhUAO|qJ~$PP$v8%ZKX@%^ zU3`Im1ZML_6YAfs*TT1#9{eMy@7@-Uvgs&%YiO+i55d&DeNvI}u;bJ&!*>$zMHl(| zVAj7jqk3t-6Hfja!+(dmR%j%Oo)wN;|J4dbihh_>^k>>x>V?lo$;JF)z6MO)sQwhi zeiXF5S^fjmuXLM^UOkD$6LM<>cnGF;+A$Sv{&+d|}ivV#aUbZl49bnocUx={_Ij?6b$l`Q-uz zbN_D&dMz!b7N-A`gifgEmxB4Uel#_4`9HyWXDr-nrXb(F3(?8d&iLeqGC=@y`BMsN zI8#Q2r>Zlbk2Ua%75zLPMNLdl7jJjWpDQXAL@;-sr65POO6r+? zS7zJQTl_*WFIU-8?N(jI(8fq!{yYUm_{O6-jhwNV?tR z6Tn1{wWRv&=_Zb>n#zm!Q;^}!6)0_{AO7B0B3uLWrzQpUJ5x;^XEhl;_dEPNFiDSx zP} zFmrQK(9nBw$~vzXvv&7GJ{(Mbya^S#zL!`%X9~Z5T?$%@GtttbP;4K9g(@&1$tmcR zRxMSbsmE-uy2~#Bb9GriYFHON(c#P_es)RN<$E2XZ-8m@y(rg?!LJ;b}XgQ}KfAt3HbVDB|>hb?fH!WRiP+cE!t;CNXH97^^ z@axboJ_bAQ;)NSvz6?r1FWxs&o9p^9$9A{yQ=lJii58_--A@cVI-a+;NJ0O7TaP-2 z#NqU7#ey8nSiKaqp!orHZI=n7exa3@fH8QkN%h}uBF_Ei!|&8jLCJa>Q3e%4b zo`K9(`DeZ#nB1X%$mW89;@MblzVS&in(Up2PNIdl!SI}L3rvzc8M&Tor3&l@Gaf}> zd3`X+fBum2;e$n;!9KiN1JtFPQNQ~O@!qAUghnv9BpJ=oZKIqrEtmzt-+4_i$9t$z zeyJ8>%T8b3r!*P;@!o>m3g+SyJx&R?!HhbWjP_f#QRhu9nYg^~yat%aUjNAJeJ#cJ zuYCDy=aZ4vjIHR~+PQf3%VWYFFjw~_qqc<~sLbs{nGw`){=*;mJzuUm6}x$;IDg(m zKIA|$s$8@Ul@!I`gHMhKcfmZ!OGfjmK2zy`hcPnwU;Yi4;caip<3ERq4-?1n8@D8* zJ!|t(uhu2Ff7&789vJzmWMsIggZe$oijkOf!S}$3QBO&`=~kj1U)2%r4;p7&Ijr zwH#Nc-81Z%@$OpqFqlOfACtBzcH+YfZ=McGMtO60B9ni!aHn2@@DPlRcQWEubfHTx z+B0olJ@76t+CQI>nP=?9-#>kMJ0Dmd_g$#Rl}OyvDqna6CXq}=Gn%^5E$$um;W3zI+hp|WuqHi~c4XSsdf{|1uWnb8 zk*<#7kX4?14~Jwlsk0E7#?8dN$vmMMjEiY9(k$&kH|`zDObyY;(O?Q+Unh6$94Qv+ zdGpEU$w>NkH`3^g!tyoig(qNYw3E@6Up;8T(1~&3^l=23+w1GeRvjlXs?CSj(@lo& zWcQ%#S25VJIa_D}bM8+Pax&7UtNfgqfK~%M3C#J`^<=cSvp6W$m;d)K2^E#@MUA&+ z;F57`gr{Jxd`LpElpZ~@U^GLz^uab@z9u%18@G%WhaL&!Z9gZWo(K1#hhM_*@;Rx( ze_({CNhs9CfZki@!qjH=!-ilq(jJhfD_umoHH2rMCm~6~e)P;E5XWaM6P|%7YfM5H z?&#Bl|G6?oM*VPKFh_&#klsIC#a;Xqe(c>Ov^wMfntmi08+b1io`d;Yo`lRQ^yx_+ z1XDVpA2tGW^KmojO%bBEzm!j}Ndo>A->tRH@%q5x4O(t0J zUDTTNm*n#pQVic7&0i}{Li@E2p}V)o;X{X}3opSOJO*Q=jcJ=h6m#VL0Q?C|)Un6p zhuxGoMx4fvIhllRv>igBy#w&o6X8NDn9dzZ$Z}I}y7m*zxCEQw=U@hyJ|yl7GVjuc6r-wIK<4 zo`(b z)C@nN4b1kqBy{*|KYH#pcjo8(LAVzBdHK1V43W8uo4SPZbLS$YYgV{fQFc!g#SX4{)`|Kgkw~gReL?of&oa4yYXev&5?j^hhGu=N4 zHSX_5y7UCP9vg;tl)DS>z})gkLR+#-=%3$M zCT^?+z6z%CT@`uxBP$a3BKWIbNvM3tNwoi7D1Nt;65fM3?*!+;GE+Lf_ZVigmnA+3 zCfc@=?5{UQbasm5kGmwHH{DL5)@Uh~M7szdz-SLkLMG=-=~|ny%!qPJTnJ{ri=3n^ z$BLTHF?=`cBxLpS6q0Ibid$7Xb$$2cZTZ5Yl4GhT9ow5P_22dB;C zT?ZtgK>2CZK5PnpmFOgV0`pWm3AK$kqx+EFjBN2xyba8X?sa6Qleg&cHHL4|O+w_+ zGiYi|DBd&GLHG>jXO|=t_1AjAv^i zl2@72cZN=2R#gwjE5LZ>zaV#*PY_QHkLP{c5>eIl^XT})$#~i40m3&h*B>ULpOFLU z<=uUmwc6G=28^rIZ}RNF3F4BWtN6RkiOAyY1thZ_i|d~B6TXAt8xm2x;b7Xm#g{qW zV1p-uSugD*!|(fwdT&;1(1TWS2^+C-G(bqP7w1z;UsPxt|5ypV{Nqz$IOj`e3o7}+ZO`QGO@HCceWVy$(oC&{b<1dz+7LPh(h7q+4U)i zxf@}PBf$K=t3k!S4ibNFSPdr?y<4ETZ^q{zqIQ`r#l$@vZZ4ihem(2Qw-n5j{L^O6xD5!no>K;Th16SXNMiee9K7zY}xq=drN7E46c1H+9#yjG_o$x#)(~@%C7$P=a*~LHbOhmP9808g8 z@x0Fmu?Coh&WUJH+faJTtf@?8pc7X7hT%}(kUj)^_YJB>(09i)h!GeI~QzFY4O=I@Y1 zWV&!D?YTXac~$6yuY-AdR6=!IA1e0$eViXWJP|GbE25k7sd!YuGOPur#SC5_&xX=d zHNzP4t1~_a#(Rh#75*z!RP(yPcMeKK+_@6;Oq_(DWlX|7z{CwmL@V|Uqd$%cV+_{1 z;5;ysTBX$JVPWDcXO2%dPek*`Yv{q%K%8S9hI@i3>Ys>OKU>m)L19cp9~YbsW?#Rh z)cG-C;`Epb{+MYZ3Tn890$RNA)0`Nr4d!TXxJIN8qxbC&WA;Y7;V>}&BGafbxnbg= z<#qh7eu*e*V=0;v?1@JP#$X*V$%cuj$Y&@$_kI}D?U5@E0#p2VHC0#>CTb<#;)7wI zDX0v^@Akqk?@h(Mz_jWnq7Ay1baQ_xv%}n>%^IT2U@QF~wjr)LE4dV&DG=v`O zBxROb(|8vc=Q})gcp$84mu|QMjN6VHv`Vzc(_52pUohvuj2tzDKI;f`kVoM|V4_WU z%E3%3ep}NOzXfCFREzFl3PKAT1mx#^*!(a=%+UII@+E+ z9Pen)#wK9KfjM4hMGqP)WqR)S#5Q2k23Au=j#6>-yPkL_%$xp@I<)BDFf3YS;Q?S` zVLz?AhtnOsq|Ds?9@r5~?$lZ;^GBHYuT&c!f%AIYsXBC8W`V7eHeypS?y#S!hb(Eg zp;D&9iNP^o_ElC=S^83O?Svk9E{w-%&J7e{VvoP-Z@^|?Ucwy6o)3k4F)5>S7GXay zn%UKq*jp-2Oz4UGg6TApqpY_h@YfaD*c?n7^mA7jMsMpYWlRTqD97`z^#=7yT`H>0 z?1hcs*itUY(a2Iqth+Z84+QfD`WbQ7iVn7tG9Oz!u_^R3=)iTV&`>J6pVGmOihh>Y zql#Dx8*I(SgTUBAKmDaPwA4b%*x7pF{$NJktfDG(q~b3lZJY;YzgYvCmX7eXh8#Q? zj1QQ?&sH=wSjt@f&l6jM@%O5sE^14~o|)RX5X{=r2GsP1!Ot#bU<)uKVXohiHgu() zlqp*0g*CtoNv)%VpJC#p1-Yz&sxzr=l)|i7$HT;dyW!{n5~fPO#3n zG;kXp4u*g^@VMnjcj+l*Iv@MsGB8t5RZ|PThKW<#bnr7cj&X&z(eqgd>s`*lR$$D* z9CCN0XX{9r{$@V-7MN{)t0;r-VPbZtHm(BWPToO%K6&CdRyo)j%n2}+og?Y)>Qd%L z(F9xyX2RYIYUi6U(O{=Go&(4J_xc?)|GPUb`@SCAfLQ^?WdA67NH;L!eK7{(*icSg zdLJg957NdSVD3cUMaOeJ@D%^G*cQxIFc~q<^nNud6EF40yTJT#s-iBog^4>p>L~j; z`{FKoVT17f#o5>n%oSME*FK|YcS9*-b=nsn0y8B1I^_s!>a|xF&w}v`oqrGYigw4o zLo%>Em^OHAM?W4#=Z=yx@|V8&6d2)S6;(DsDu#6Hg-^qAbnS8QgBxL=gHAp`Ar34S zN;9xCn0xBbPm3EJ*&$_q-kXGD!Q^$8Q(c})#V@~g@at}g=thr+sLj9&pEp{CM}rAf zOGFX5B&}``&e$%P48Q+`=VC|7sP#YLT6IweXTov3jCzP1GCZ(dcoKF26ZaTx?L&#d~3&TZM-xfpo`qeX_7C7_VOmh*6W!5h>x!nw$`9 z2F7l4HPv-yxR~Fhhm&EST}&P!4NnP9yS5s;fqC&G0d)q_^uz7pjQA-STYwoET|;H2 zhKu?Z`q=Py0t$|Pgeo@Bc=()5On~VClM;&PH(SD)#U^3+`w#dH_nR8ZI5AwjWN3iB z!DQ`ugu?$g6t{x;Fu#UMIT$W}A8LSgV7$AAJVw_Sy5NGVnV1IS z-=2VK=6cfmUW7BlwIlFdFfaF4QTcV@V%1T7e4`@)*@r$xT05Na!0co!0dx6t0($?_ zgSI!0V2)l2SDG7xYp5Qb;bMKPE|$XV_>F@ zuBB2}M~GF24e^rq3Fy<4$LN=nBet0`2fKqg|1tr2I*g-ZUPmzVMo-5%V8%SFrjqI- z#BJLQaV+f9xMwqJ$#%fux{=reOvj4^^fPrFJ>**ilao6gXM*XbT|-$viV!D?hWNtk z1e9jmj2bi?@a{G9u_u_D&l1q%$KEt&GK~qlKLf{u*)Ol6&ZmLwqwjI>ioes+fnp zzTH5e)Qk^ zX^dmpZ0raITUAlMm#2vpAx3y79LHL|841g*ar4m#JPyp(y9wypD}VZ3mq^C`MI2WA zrg_)I3JSfRCZ6LBvFt$ta;k1dzY?r)Z_QBb4QAV|1f;ghpT6f4$)p6vVHYs#HkDFY zj*;S%i3Yd?_StkB=D^q**RGg~$Aekbkbsgj1L&-Uk&JO|93BBi_fjckHYHN*z1jd@ zxSfEUA2p+LaX6+sgRl>n+4TvC9OzH~%Zy~M3bU~%n5%2AQIFyx#Sd5?=QSoE?!RW_ zZfJv_(a=wymS*%kYdHQJJq7!M z!7v`1fBy8jagj{GtT-$I^W>^X9kP!U=YP?|?JynLoULRk?S8%&k1mu!oz)z+czhyFzYRLZK6nK8v`%&Al7sFO_V`H|s*C zw%=2C4ag^LR+M zvoB<7h?B?hL_7DXE5~~FgS_uBQ!-`qFoyV5<=!81mR=od`H_x#YF_lPhaD=`M6pd< zB(nW?JY*GXqS&^Di0q3E4_U>UD7Mb!B5RQOkX5XSVl&+;vd6bRWEE?o*eWYTb~|Ln znkcpw`x16t_(N8)CW>uYLmjRH6UEjqtc0!j^MF;XiDKh|O4zW`4_L*TD7Hl_ zN?32ZCRVW~itV)DHMXnmeO9q1ifs;E%HGbo$12uDu{k^~Wlwj%$12uDvCW-c#@;f& z%PQ7HvAsE1#(o-khgGbJV*4SKu_uFXvx+rQYFl{ zzN{=~t1jMR6>Fl{oSv4m-g>uK#hNI#<#83P+NPVVVoelV)w>GTu+L3au_lV`30uhq z6CRRk7sZdUnA7%4*9_RI%5?>RD4& zzTi;Jdf3;qW~%IxTg~3-RnMBM@~9)#tY)>G9jMB=7pvKBTjcB@RUXl;hW#^9&JI@P z8L2g_mbIL`tf;Q|0Ma zwX9_qIXhgHdk(5)b4}%}l`3;uwX9$xXRTE^s8=mZ50$evs=T{TExU`Bv$m={mZ@bg zOpvp7s+{Fp%ZAR9v-YaI+P{{SPnWX}s(fa4E&DN2&W=#!#-+9FxjAyyQI*$()v|W+ za(1LDFPl=!KA9_LN2&5B$ZN9XtdlBxkE><(o|UuCs;ui=%Py&rv!hjcuUReIqfySf zsB$jk=2vpoRh7eGJnO#8SvOVA)~scXe#%)wmHnR8us>ePSyGjw{;OeI@5@VY&Y27WL2J>RmFCP{-&sM&F(6;tz6Cq ztMaaH)$GNSayCSj)h<-C)@$YLR8{`E7uFBXuh9SVCu-TCm2x&rmG8Z{&KAM>E>&e$ z-5abnC1=A`*?^U^*|u^vLY4bosb{Z3o~Fu|4Q{gjgXCTvbkg`i%W@xsIKu%2nTAu#Y#?vGY~=V4qiPx?df;K$XvrX=8V5*Rcy#d5HNt zR;E|SE>h*xM<3V%-8y!$Di_TB%;Mtf>=IQDG;U{g?60#+Rk`KYcQ*N4ExSyWGhh5< zms-@a@v5BI^ABs;P{S@)F1A=V}eRQk5&4x_T{1sbLdT`AMdR zm&J}6Hc^#rIyJr4jIUvnR5@(4mRCV-HJhx;j*EMEjc%%DQ&hPEDU#WifID(`sH z(~B*tX46zTmDBbbT3W@Xt8(d39j{-8RqQHN&dt~Hy6#=cW~lP7gT1^;&R4LRs=T6? zu9r2cV6#-YphMTI?N>RwT9te0>UsH0E@#)M@{|R7UWFUW*|n;iVW;nPt)-03R^@)$ z242LQQZ`4GHSQUBCCw;h*QxS*nW5LgE~V^xRaRT~|G2sjpr+FA;o}I{*M?ouwfEi? zMSacz5$s)pti7TV4fa9@0To*)Hk2A-S2`%7bg2Sj7aO*<_xj#*e$USQ=e;vKb3gke zA;f@tzxU*BLmZxw3VzZzr!>Nw zFCCWK6cbG^!5-<~na%Lf-HWhS`s&T*Xt3rY?313C(gHPAFT#H5=MF7V6P^MGq-Xax z#g!rjw9=-pO;Nl~h5+de(XDXAu4D+5o}z7y6Q?Ibko05UztOo(G6YL^TG9q9t0luh z>EvN;v8G`%9Fk7F+ZNMHli;wl$NF~YeIyBvNXJ{X$HZMpa8x?|OM4u*AqhgHEt5N7 z$gm_hCf##&N7M{Yg5%Ob9XnxE%_Inwb}Z_I&weFBnDqE@o$)~3BnX$@Skf7z?j%Bl zbVvIx=z1g(BBk$-?22Z)6Cq0aui4$u{!Ak1q#v#6j^Uw+5G~zdOb@K5N(8-hC)1wj zRwWTmNV~o1iF?i`z)5NK@m^SWcLJP}wrSfNx2{Nl)6&i{y)mOr0-TW^v#1Y7JdTI6 z((MNJ#l%bTa8A0@x6*V;Y; zD{^8XP1<9lIp&we!WHQq-Xn3tp;)*oePPrn?7uM<(xnSOkHYfVv5+A>>HKKyW*-Zg z(gCXlb~lTKENPR+0tbzXg>31sBLU|s>p9YwwgN8h5evD}!HUOVEL@Y0*Z`Q^Jr?q$ zD@Ooc?GOw3((gtCo;HYu0_jx(aO;g2D3tD_2Icor3=~QC4gg$uB?gM6?_2_`S{wt{ zr5*kN_B$N|CDK;I5t~KCK&f>31w@B4F;FJ0Z)t&E2{CX(+RefO4d2H=x%5}H1&)0d z12?7D9JIh%l`(KjI-tS=tKW=)+tU6&EwDoQe(p#=>uQO8TF1g&=~lxn@!t0sxF@~b z(Gu-X#=w1PV{c1z2#bLS(kBmD;<@w~sE{rzwM3Jw7gAO4v z@K`!(#~2J*9s^ILv%<#U*A+4FRQmUuG3ag)1C`Q08d~A*p)v4Gdby1i9`7Cl&!zRN ztZ)*>zzgY|J671xGzMNupP4)sZR*6ptN*;`fBsi`Ks{@$S9AehOMl;BjcuYXz#Hk5 zch(38FTh*rDcfz(bJD$@J)JN+!Q=C{ycn_ zPQs~pr`37*A^qvXR2*^Z9Q>62GISa)^*RT?q}LQp!_Zad;J0+^)zk6d$aC;VdRxO8 zxbF8^`0s#!n8{3x4?YVtOF`S@b2D+A>MYQl1Z|oTv+!Q+vp_Qtw7tDN3t#!30h({1 z?QYxI=-lcIRF$@Hn~i5KorY@C>r8F&rRp@$%mHnad#cdj@F}2q0^TOuVcY8`fo270 zyR~W#UN=4oGzUPNsooylC!YX1$4^_!33KtvH9gSzd)n#-%)=Ia^g!q4XH@j&xvpmXZ91?Dfpyc8YK`EuHRFJFSi)pbDU!f7+Cy$l;oi2^#$P1~BF z<>-_g33LvdHceFreBc-fbbgw)V*8Z{Z6krsJ=0d};VMkL9RYM+nYOkw9dXfv2%vMu zv`x%ZyhJ~bl#M<6R)>om8dYFbE34py0;yDhJ`^J=_VJQ zvD&OKpmUkD8N0jS2;F26TRrw)a2W(7aO^bd=T? zyW@^FVbDpsdw>V_X%z-^&W|=bttXm~39Vo5@sPyjdp< z=$sa9P9?tB%`^Pbkp2DBAwI?uT!FgaVysqHTBgov3;n3Um&Mwogtw zaeZ+p(D@AG5+k zfzEBvHej(o4s#C$I&VSS=N0}qUb#P=lc24`G=FS1FBC>e-?i~a*Oj3#S~^>~|IKBg zK<5c)`?J*_yRQocItM`8VZ}`XLxK7}ZHBA;vDcYUu#i5v%paohMpyO6iVvYc z{hGFdPX4&dBn+rc)8_2qkDk55`03KWn$vG4o;8l=o=Gn5I}`u?8OJ@7Tpwm)YK?gA zndHD3Gx0~mc z<3`U$1;+{!<)!!CPtxs{!B>%nH7TwEEa?d229JR&WGfr~PB$p)F zV&L-=+%w4^AKT&}-3jiQWXI|%>^SEH_e^pUsBl%C6WlY&`*)}?s8Y{8le{!Zg%K%w z?wRB@X)3hYs^^|bo}Hn>Z-eyEM%gEKd#A#{YI^ROii+l*Nxrw)4nJRt=AKC&qO4~YMsv?3A9l3E zsrRC}XObJOutS5p(cCl1uFB(ocp1$-ll3$tnvwba&Bn&m?#4t32P`dhVIz4UOzDBtXwSlN|R}g$|*5?wRDf zu__!Gspp6&?wPb+_{tW)U)6KZBzLd0#alUg?wRB#6}Gq}NzXl#?Ek?Q51rF< z&m`Y!sKVIedhVIz3qpn0_UgH3lDlbC*nOX#dnUPPmI_-dug7?0pKSQX7C$Sm*97U* zO}3chtmmFd>(kH{3pVPxXOe%6u*DjIdhVIzfrD)^{(zo)CfQeUGdDf=OmgEPwm8;b z&png8zlSZZ(dxNplC3-2Vx#?f?wRCVb6YgnuIHXfKDyo(JK5{GXOay|Y_W>1o_i*_ z*9a9RS?RfFl24sgem*ecQ5sa9?sX_e^s7r+-iz z7R^1AtX?)3{Z>VD&m?C=&qeQL(cCl14{p!JVQr(iXOg{f9)5kMeWF7ZRa&*K3RBzRB&m`BLyAT}~>bPf;)0!;8P3?8uGs#UK zEW$b!QQR}h6|WcLlQ&V^Gszm`rC94>6!%Q>k>5-4ic1vtOmf?w%dmd+DDIi$Ee%&- z%T1BoGs!DDI$)@AB==16(FH4UNOT1EOmfkURhYLYf_o+z+B>4-+6eBM`|K8oA?30Cu6N<0l+%w6!gV*5_iwN$S zLkcK01thCOPQLI-D>%jC&@z ztI2vSEDYtINglCsJ=Px<$~}{OJ7qmyynLK{Ci!i}dQ4q*oO>qOzj8eu_;ieWCb?0A z4Op@6823!_-wQY3GUH?1Gs)`;HsFI3A>1>`pWAN4-aA9MXOb-(He%Z15bl{|!;Fo% z=+#l~ndBp#HsN{mqueveIcqmzRQ03WGs#o)HsSFjN4RH_*9_Z?XGb03p2_zw+KhX{ z4|C5XS2W&&u{#cP&m{jdZwvlxc$j-8c~;;S>>qcCdnUPR;TB9?a)^5-`A4;_ILGi1 z_e^r@C0jAz+ClD_WRt5~vDNv5+%w5}J+`6wp@ZBr$vw7g!+C)Rxo47xM{L6#%MNnS zB)g|=!#e{Ha?d2U`MeE>k2uIZliZ;9cI@BoAooo2SG(=lQvvO!DU9?KrqJn0qEU_V#x4Di7wKNiHhijwzwR+%w6x%JI`xhhXlRCTw!9?U(H{CuY~KHnD1J(H}9aYjG$VD6dZbEVEW=uHs!O!B+$&e-xy z5cf=Sjk+#){&*1gO!D4ZE@-_khp+d0QXFCLt|G={i)@iNzU!;ijSKFaL**4vvI}F6-t9 zPyqK#a@81Dbm$zwJ(JwL%oW{~+f&aZ_x|OIGg=04&m@m)?S>ud2f$^ye$LtrZ!3>S zJ(Jd3dAngpivaGK=`?ETvf+dR~A&m=pTx})DSE%!|F zhym_seMieZle}f9JN|j3<(^5N-N_y2zR+^dBaIu9cR1Cb{DZXDl<(a?d2ca&X3o z8d{*9NrqLwjl?& zXOdUdcER$M2e@aFH%)Ots~HElXOivxT(Fk;0q&W6`ztQ!Uh4q&OmfHXE_m|Me(ss% zcRgG&vtU2>O!C!PuIQP%pL-_xj=L+yT;9(;lU#hl6*UL;bI&AiNpruWxQRENn0LOmcS<<>$BOUhbLX#%CZc2-&pY3|8AlWhD|i(>|Pa?d0;Jsp5OEIqkrl55!oqM2gq znPl%jfoR^tlY1ul^|2tlKirdhCV7qs#zxCLxo46i?gnFHM^EmVm?lk5zKaj&;0_e^qn;$bXMz8>{VvSHgJ z=(56-dnVa-^%0z?^5mXLu72(a?i%dLJ(GN*%2D*`@5w!rthYXjd!~DG&m?zpJ&Iw< z>qR}2tUY%W=Vf_t&m{Z4Jc^^PcyP}ot9plE)lv`cnPg+f5Zr&>gL@`17aL*)<*M(sB6CT_%$z_K_&^gY7dnWm> z*buCB)`NQ{**_-)m!^1d&m{ko9)dX!Jh*3))iELH@XdpJCb@y~e11Ii;GRjo6&ix) z5Zs>(f+e7sL2x)mF9&m{W~i^Sq^WA2&cGs^n4A;#P@$#IHJ z&KYvgBv%_8i4(3EaL*+7cTm3mvR{IFCi&mvk=W$l@1l;hSxzJtz5FVuXVSXy%SdcF z@sp@0edbFfe)N4O>PvenR*To7f%NF#krI2ytO&0Zjik4Z zj>5Wwo`}ZM#dD(YuSt)1W|qFbm1`7EUsb^~vt-r2DD1H6KF`dOUxh>|=YQ^s=JNhM zFGQh@_Z`tfdQnysj@8~4Ev0KbjY8Muw}h#5$C^4c+Iv&9lJ3+_hmmz}iq_KE?R7Zo z*A4Nv^tNs~T=}$2w2_`?uEX4pWumS0s@XbxFt=2+lQv(c!)2KzqP_IbEjsL%Tp~J1 z7jMh|bdUl=Z>=N<|mx$c;K&VO=V^N*`RW!}C_9 zqMLNmW*ye>Diz(OgFJPZez8>ake=wH!}))eiJsEAUOIf$s!UMNq}TV2vfi<3ndmM3 zXon8V&C5g|>1^fkruvqNzS8fN=Nr4EO!SkU?4rYI31y9%$#{c43JLPphLTp zH^e~c0c&&^aPfv1B;9qb4)6Ca7lWmjI_mJ}hH^1PdhrS!9#~y2hDyT{9gZ?77sI4~ z*z2(H_YGkt-ED>r&zhEt;nM3Zby#O)xfmh6WPlFUbIOIew0BD#9@CeLky-0T zH^nIFy|0z`SErj|v~x{U{1=4lftfGwJzkJs*XphUJ2KCVAe*C_L4wTuhV>_$La>29=9R z(s?tYuy9Sem@FMPH3|={C>K+tlO{!BTElWNRl0CW6i(|?E~ZJJu~NQ&<@rsQ{%H|~ zZN`_28Pd+m{f8Kpi<#1?E28l8@*857ba`+T)|hoe%$C;VN8yb2H-xS9)2hn*c~6;8 zNxvJc!_WVe2|MZOPCBd@UMA*9A3vu<^BHBrUOM-^4n6yniGQT8cZ$XyiKSw$w02H3 zHs4Sx=1DgSP+YrI%$NRjFB-+i60tz~c^5tQIawkWN^6$rasQv|Vv+P3FFlUxR3a8j z-#n(r`EXqYtynCRelp_(8hk1e%cVp0C-6XnVzEMc$LAAx z!mCI)NY9*j5>NFn5-X*X!%pG@pF*)pI;qwvJifO;td@@6bqZ4>3xuO|yy;in6@<@*-vY?rRvI~M1UNEOb~r`pBhy|5JF zBK_7h7TcL730LW9gJZGRq6Fb4-EvMW8r+H#?$YY5v3O`xjPQ^i92$$(YtIW$>2C3{ z_`&3y@RIIxE*2MzKO?-QpI(kdKlLfGLwfAXSaeu?Lik8Kw~WJzetO|6T|6QVf2KqW zKj}JiEI`cXtd#g&`aO{lZa^x_KOqJeY+;%;Nknk z$^Y&@Dhcz#_li@}u_KeP?aMvlv~(K$yjjKSENXf z9+r$=DZb*ObmF*V3|{XmE=iwVn2c$Oz9Lon$+~2W4fPe5rERpySYqub(xeAuC8NOw zKXFC+pc`m_ufa8NjpU);?qE1aYMS6@_z4r%}5uW4wq&PxDBb>UJic$dQ#_LPx)hK5 zUiyj0(k~9jOD@i?lhpLi}k zzhyiw_3#rfq!X0i&*PT)iI>v*Tg2mwnSSDx^c0hLOr7E<{*`v99gj7t`-#`m=87j2 z`HDBv2O7p>+bh1}t@Mia@%VO&uXrcjW@J2WpXw{#OLterWB5HE@j+Sy#N+kDKH{Tv zx6F9VU+5z~Ne6z4$3Dk)h|kim+a%zuVLQYZ=_|_XKcV^#@m0Frssx-~?k&Daci)$Q zwSIbu@6vzt31~9fOZZi)EMHy2SwdPsO8Zd~djXg-tHAwLm^A9fZ-(vNQ?qOI5_ zjHPcrO+@RTn?zOVt?v`@?$!;Wn)IetNw{Q>lc+A8vOEcYy>=8dpGlAZBr6FomaY&q zpGofAI~fbz773cqB;PrhjGo?e1FM_)nnndGvwSFu&MUV`Q`$-5oW@o?R4g61>HSBx@nW=v;6^O@vp7c#Krlum-? zGs(?uGqIy#7eVuxlA!t66T(Y4MN9$V% zn$IM!GAP1r>CFVqXOgdLig1i+6G8KtCFYrXOf-klwhyn%>>P7l6`GT zutSYzg61>Hy4@w%>fdI9<}=BmmrAfOzlorpNltxUq8xuW5;UJlwlOWmf4?>qG@nV{ zKDQJt>NgTJpGhtXEX6un6G8KtN~OL3>0i5MgOJi8PR7c>+!pGl8r zbEFjSRyGzipGh|KD#cFqnh2WDB%5q3#jE?82AUwNcpF@V;&lSDfdirm$rF$XQV0jOtN|BJT#nW$~}`@wRavKUt!8U zlYDbn9*)~>$~}_|Q}ghbxheNd@;duG?A+LtdnWnIoIGq1(vo{7d4RH>+OGxoOtOA{ z9`0%1jC&?IS(}Hx{hIK6Ciy{89_GGo#PgZtlCODKV9~}UFyNMb+pGoe0H6H_pR_FOlvf1@~+_JP9&u5YsJY9_XOgcDDZr!|#yp=%?mndeFPa+jd?r~ny#S2^ zjd(tje12vD4ly)>Hp)KPbX5VmMjAp}=`KD6m^#{!=QC+t94o+WAFA+tCi(tJ(0{Ta&u5Y~rwcG>lEwN0yq9gn^O@wCOA7GqO(UMqB!?=0{vj`n zcs`T-$gBXfYZ>!=Ci!xE^R<-=QGJWlJfEAP-C9Y zByYQ%kIlOp^L!@RJTD(VHZbP-O!AmV`MB$?5zl9mmwn8~8gGnvK9k(7Liu_RjCeki z{3tRXTjv__d?tC@l6<`T%!ubR$w}7v`0$Al&u5b3hUcTciZRb;l56(QN9R9AJfBI9 zRenE=QvQ6VD*NQ6?ecNWFC(7MBu6*M#|@2*c|McuQ#Btq85{F_Ci$shKE^8dpQ-GV zzctCnAt#M^K9dZC@(~Uj@q8xvmVG{+@iyZ5O!5uieC%&$#PgZtEf@09c8n3vXOeU8 zr_XiSRpQ+ScT^^$(>6Jae!kLp3fxP*DgYv z!Bu!ZlU&`p2$hSw@_Z(FjC&Cdi&n-olznn?ZV?XeZNT%H<&u5a`9xBEO zBMf*xlf33zF@E~{5BE%R?J3u>SGQl>Gs%ew*Rg)@AKWv^qHPHt@&Cp>lRP-E1YbA% z$~}`jrfVr`SAOB1NuI7#{=PT=!ab8bsc#v&H~qprlbm~@4Cj3O%srFbxZw?KGW0X| zOmg_d8~Dfj6ZcH=+}$^Darh_hndHKAH?UF0C+?Z#mnUxE$YGzjXOhc(Z(zvA55ig5 zCpWRZfit?k6E4#3J#Jvu?$_KiX?;qo8(7}!U+$UY_|IjSTIoO>qu z{+%+s)bJViOmdroGVGH3lzS$5{joB9yypq`O!9N@G8`B9hZyA=|D&?L@Ubm?X7eZ*L)Hnb|iK~3|yXOgX^mf+Go`P?(fw`Y`~V?;jp zOmZE|62t>}+%w7UJxlQWhHKn2$wQkcU%xV!dnVc8%XR#@FPD2Jd7Sd|ddfMMdnSA9 zb>;kb4);v*f!Wv5-zSHACi&y&>v()b4);v*KGW;iEH|5bCOPeEF*;t!;+{z!_Ouv> z7G-kJB)gRtW2ZTp+%w5m8O7M)Wd`?5avgm!&hMAOJ(Ik8doh0QmCikr+-+_#irlN* zGs)M-7NbY4bncntq9Mf?+$EiRCfUif80#KP=blN{d@DlBxODEBmXG3CI`>Sn z>-2n_q)q3ZNzPS{7e=>Tcyn6@>CdnWlpy==6y&*7d)u3M0W(YvdIovbJ<0ocetzkLbGs(4EWudw#n|mht;;l^lnw8BxlYA{Y6WguN=AKD5+MJ2Y zcV=_XBtM>$iKZ6W+%w4wEHkmj-`U(V$@9Bp;;U#U;Qggp z+%w4z9c>dnVbf zWhS=B&fuO&uIQeLld5KL&m{jDmWg)ybncnthSr(r=#kDnlYDeiCOXeZ=blM!tMsWZ zE7Q4WlKZMMaq6$D+%w6p%I&vLyUIP29DtelHvJ0sO!ApFnP?c3#yyjK=tl+?>C(7o zk{`9o#Bnb!bI&B3nrC83N-FnEa$So|oZBFkdnS38L#Fb1=8N1j$^MR+_(n1HOmfn; zOzb};g?lD>)h^}FuQZ8!CV9@GOq}&Pk$WcjpX^L*vM`=|Ci$V#-}>ufxMz~POv=Il z&vV=}$*$p9=wEi4dnUP5c|YcSKfyhd{Crb3F6k7_J(K+4ZZ@vk9mzeDJY;kZKHVSA zJ(Jw*QVwn#9?CtFyvQaOH77#2XOho6&BbRShq-5xM{c-=Y4r|r&m<52ehtI?gScms zFKo(F{(J+tXOa)s&ByW)TJ9;viW7z(g%-yqBefQ?$-twqG+;8)ZOOeXjzY}-$w>S3 zkH;G2vn2;7V^!(F!AGIWfyr1++UVm^WdwOLR+kR!6awv6Pgc&+{_p;kZ9?GA_{msP z+M<03WWAY$wWMc?5ID1Z64sVp(Bv3&dNUFKlI~-09M7_fuVDIg5*jTzwy>Mt2JPw;k8y*aYkBi1(Q)$1a;ZV2zIBX`pq-_KYcx!{r zrQ@6<0Mc!gnPvI_k z*arWWo^KZgtJ>RO8)>7kD46)u8rw=&Z?1zSPpq+>bb_M}nwMK+d+EA*9bCR{jUA+? z2J2vQu{Cy-UKOK*u>027NxFmbSvAAk*4SCvN2`NwAFZ*A^q~VfaQ|S9U8TqG(Shk} zYwRYi57NQt&(_#oy6!cd@>v%f>>(|Rb#SAG4fd3d%GbffS~f^Mh2Nuhb)Zq)Tl!d` z4yxC+!9LQv3Uu&YS???TGgb!%^=+`9^r~nbv^TZE{?hi!^B>UF1_wx+Z_z=jnGFt< zuD?+SR^~Q1Ncz?)9sD)M1_w(IRX&?HafS^Jk!~?od3|hbka`L|Uwua%j2vZy!=$^^ z)WH$7K{M&fCsFWYqzw+2o^~P%Zd%#k2B#L7uwa4> z+DI?XRMxF+aGZ3&#t1m6+nJC@6nQ|?QDK92g39?QD>G3cVgd%I}L6%Ih^vdPaZc_rp>foG$H9D-`}H z-|r0RgfGhPC*|>}r_lYIj1Gl3<@=o_?R+d0b|`;7v!y>;g+Z+H{B5Nl8-~LP<^70NJiaBYMQE|Av5MZ*Z?{k>3n1%_Fq-Ux0utNELvsk*P z@>%mAv*z_|aH({E#}hERwhb&=1H%l+Ml?e|j z#^M&~rI}gK`SDoXD!pxTHVEbMw@Kf#%7(9%V{yB*ZCVzLJ~FZqi>{Wx}R2R_HE$Z$u^-I9Q>Fw9lwaXfntOJ*7WC%mDl9 zR_G;NcYFrCEE$8|()oANq1%x$xI@}j@qYCf^pRd_pj=OL+!*wgKL0Eo-kFU-Kk2Ji z(qVMpF}PFucvLz}HW`DvqirvT%Q4vgDi2s^zeZh(6gB(9+2MfC>?fuv_P%2_r7#^SZIL((&zf7 z!<7pb7%1JiQ#!bWT40d0Yxi_0*l&Ts(rLre;r?z5JShFKZ92q;Sl}V)ZNXPzl(K&K zzuPyx3b(gd;1TIbMOWa>MhiSDeSFOoShdaqL!|w`rNJ-7$D~J|PJ>A0{>P=a4M~Gm zt1K{7+T_$_XtUk|!=&A-T!uYcEihdAR=-p@IM)Irq-Slo1Q|9K7%6Q(AHNMsVU4@8WSK7S|))b5C}(#^Ief!8L)IO%6Ym1`|7LyVVxn34#y ztq>EW|NbWtX7)i$lzuTT5!!b{Op;D+qg)$tAY!ug^9Kp=7b2!eFWHs=9mgPEln%E_ zfOdlsFG(*LoB(zs5mTk#KZ}R$Ll7@ZFZ&b^52quhNq6d*02ft=SEN&yB!Kw@#H-S0 zCMG~5OT={P&rK3wTR+4M>1l7`q1gb$OzEWa%C&NoYu;r^KQ@eqO@Np!J-#Qt8Zl40NrSVnMR`8?(%WX7hH=W*E0BJhe-ipB zE|d-pJ^`DQ*Rx34N4eI8X)nZL>4Fo{V9*!wy7VJw9o+4WSR(!WobvZ)d&E-duYX6u z=GAH5bsD=`+N+3yCB|`4ytnu2F^#kC+*%S1R9$m-j}}K<0vfYkN7}(nE4UVDz9&a zv})~PsA`V*P&zl~5PVhc|47>M+d=55yk3u`BL*CVgGBPM(CjPVbLq&70m^5i5MM|Sw+n!uKLB4!Pwx@{zCQt9N#|uN zpB4TW@L%cDrCJb=0AEWluC0aYir+}LtEYt^SrK^2C0IM5NO5& zewAL483fH0f0Nez6%4Bo@VoQ{yI`n25b%d|L;GOZWCHk8I%|6{oPQ(mmvrpyVDP#l z@V9hRaS)!R3H&2%pKuWR2MaW)^1t7QW5gj?*9;RF?qJ_g~tS;>xdIVaw9gQ>} zM)$Y=c@)Owj6#|ZBioxDgLubLNb_Oj>$i?Wn&~K{`7rW#cjel0*G3}Ehmk#kA|Tpf zB-W9xGdK#OdXGe!52N+sYSFOrkvYG=2`~>fN16{K|2}#OR-2n6&4-b5d!AL^ zA0v?F!^llS&qI5c5lHi4!N{f}|5rSk}+`7m-@+eBqnVg%BB7`eXk z_e(+LaHRP#c8g2U^v7_d`7kn$y$qwS4o8{~BWLZs0{2!8N16{KJHJYYexrsX&4-bn zZpwlwifKNKY*RfK7ORFM&4-bX?8^h6uEUY$!^ra+7sBR;W=Qj4(1d_LQEr;612Tnjy`H(YoQi53u@-8Pa?hx%K={ zaQd(r(tH^C!n@C~OZk3iK8(EA>MN85njy`Hk?n?mgW5aIkmke4Ut4{Lrt{2@=EKNo z^?yL4`DRG-VdS~re?ZeEW=Qj4y%lU~0dq?Z}ed>HxhuV1i1`2|h$ zVdQDAf5V|JW=Qj4!N$ZiH$Te&7L&4-aIrx>7FJ2RyDFtXP_2DrU} z8Pa?hdDd(LtoeHw(tH>>v5x_6dov72NxMG#1Gl~p!_m@K-3>77?J%SuNVnGvF~BKR z%n+nc4>Z8;)s?>xq{aI`@S>@5OI7WKRus?A2^Dw0O zFnavf>fg{udHysXMlNaa8^$*?Lz)jGml^zq)xFJ-=EKN4+WrRPu4YK{VdMrSzd_sI z4982W>l@$;TQhok233`R+F#!U4*fQB&m;%_-UMbtHgnG;`^?%5bq8+do=G-I*$hvI zZ|0s!{@r5>yjIq$Df{I5kG81#yTi@zPTVueqXOMwd5jbHO!C!IcL?!w;+{!v z(aHnvs+_oIl5a2efI~J;+%w6ZHNlg$Tvf!0gIJ(GOzuot+vXt-yRb82{luSUZ?lWaRmx%R*U z4fjm)ib38Gxmd$Jlf1;n8>X+)aL**Kv+#z>wHof3WXoaRaMoSJJ(H~bkHVmfuZDXj zd3R%PDD=^A&m=GH<_-NlG~6@EcSn0emAxA7ndBdnyuswOhI=M?jI}rXdsM?cliX#Z zHyl2w;hssJzR(+1L}<8Yl5>^y<;v^PSJ@}$4D<%uBO30Rjfj11u)^N`xKYi~7->zx6XOina@q#sXHQY1FD{go}?++U8ndGPhFX;TQhI=MC zf1elF-O+H*Brn_U1*H!(+%w5LExaJ%sfK$d*}tk69C)JPo=JWm=Lr|yXt-yRH%w8k zC7^u0k;*>V=BWp?`K7^8(k4M35Le9!M@x5C-fwvZ$~D2HKeX_G?KPdaXVU#0f4ak? zI!@d($@6sX@cl0*?wRComhO;U-HCf9xwwlvbW+}*W0ZZew}CqhP#(`pdRJq2$oZn- zo=NL9JGg_@M-BH(vZvY|_W#jv&m{j+zFrF>C+?Z#JLBD9)K3lfOmdjY4W=oNH$mAa z?=*LX;BOl4ndBMqF3?PQK9l5n%3K#%s65_e>G{oE;EIV8_e{EdPOdY2R9>H{a{XVe zGgvir;+{$Cw!NJpq_GqCOtL}Rc39cPiF+n_-lFZw|6tgOdnP$Ty&cvouiq?XpFF;i zGl25=v!!*e&QQhJiF+okTYh(jrnQ{7XOg?ja{;>_8t$3om9Z}HMfrZ`$oo&~>k8wQ z``b%9?RSNze>-u{q}zWlcZF5T*PkobcePMnucl5oPkP-%H`uM*f4;OqiW~H4?!-Nl z?*G24J5+7t#66RoHpd;NRB_^-N$%0h9b#%banB?lxaX$)zSVHgBx_3Cz*u>IE>-r) zHygOaXT{5;D;B$h=W7l3Oj=)a-5rJ~ug?m(exRENxGI014${R}Jm5g3hI=O6zEMBr zS|ZBN%PP6v^PwjM<~!iaBMtXVat8Xq?(-V%ndG##zM$Hr z;hss(8RrLE7izd?k{#yl1e@*}?wRDEOS|B19S!$Pa)h5hq}SGP&m^BW*b82NX}D*S zs|M@?vql>3ndFl_55URl8t$3ol+Ie1^=B>jOmdo+7FK^=%RQ64@TC?~3^m*{$vu>7 zTNx;izfIXEJ512Rq*@y8nPj8s2S8u87M+!S^5d%eVT;dNbdh$;*$ewE)^g9Jb@6)- z_%>L}J(KLbd=He|T7&NL_VHi+!RXW)^pH*)?+?by)^N|H+Yes38;(v}!#$Jydc-a$ zYq^GdCb?qZP6&9a=AOy75A=h)1U2_ea+i*N;C5WiJ(FC2t}kQ+s<~&9bC3DJ$}lze zO!D8=eBj$*HTO*N6~7(O##PNdlWf^%2i)1BTr*MGCr3Q+22W=-_e}EB6mPH$QFG5E z&)Dt_bCs{ZPu_mqbuZYYJU;bIS`SE7{(e2A=AQXKd$6fzl6@YyL*q+o?wMqDg&XXM zQFG5Ef9vT6X-R7CndFjHuJHDlntLYMEZT*iFZE3FuS3pIGFi<%lkD1X8w@m7bI&B} z=4^t4;f~xh$=Bbn}=+o`!{k{eq(!2H!}?wSAdGIoTrM!qp?G0atNA1PfvYau&Idflc4 zFngn#dnVn!c>R2^by0KAB>SD83j-Icxo46sv+be!cs2J-@}SRlFap)wGs(TmZJ{ox zxo47p7|w#tGt}HO$*tc{gQgSJ+%w5mNmJmiP;<{DKfXH&Rw<^QNj5w=0h*Yrxo48S zSBwK)D>e5_@`p5QxK%~XJ(FBAWi0r9cjTT))}9#yU*9-#&m_ORY5}cpIC9SBv2keEh>u2v)w{ zMP;9Sweb*W`qGhmCV80SAo%gk5mV)QyMqH@>`zDTnY6xqM1PpwT+Ka`tX|#^n)gt1 z&m{No=nF@Bs<~&9J5}ui^*gA!XOcgU=ml-ssJUm7ZwB{(6Uyx~m3{KkqHeIfpPG9n zIc-T7SgyRj)HBIAyCWn_P;<{DJG^WQx>;)OnPgRQE10@m%{`N>d(#XGH>kO1lBaZU z1o7+C+%w5Ox_aQ?sOFwY?!CD-1gq8DGs*pLREHYwYVMijl3m8|c$=DgCfRwf@>vIE z{kpPG4&Crm?DA7{&m@ampGBjcYVMijdVk)DU{5voOmg((m*UG-HTO(%(61-rg^!wh zCVBdU3K68-o_Z#E{q)-+V2+x5Cb{{~Qc-h>ntLYM;#GlYt^EF?o=J9f$Psme)Z8=4 zZBASj83)!Z}r{$movRORuiDC=~Lc4XpRc;9V4AMcU-ZMqA6I?m_g zJ#x72E@Ua|bnHm({_Za5d(P+MJ@V|@_rPuNd_LYI+bz2X?v3X2@g8~VzI&jmJD-pD z$k9jd!Ij7J_;`=}KI$Ia@tDWQd%PZZPZ^h=$H#l*lvDTNiOXC*-Xl+1_W*A7n9Ij| zo+T4-w}I0-XojTe+YHP+Vk-q z`SSFKV9?l}kN3zof*-=o{5gEQN8bG6A;fH%!^eB%W~(2;jA3*5c#k~Xg^Xww zAMern=qZ)($Wz6~d*q_nO0eIk;^RGX&8$kewN1sxd*lIEDBFLijVim50vjWAXUZ3d*nyT*ZX-*#m9T(o7XF0X0CEgbY-7>-$D8M&s2Q8_kTTD zu0IZ|g!I=cKHj7Cwc9Jf<++NF_sDr&Dq*T}|6%g>|Jh7>Q2k06^H{~ldvyC3`loRF zt%{HL$Pactg{e)Y}19@(YvF&wLI$H#kQ_4&tep^kEbMczNv?J;btV#mjOw4Q48KU>Q6LGKd;^RH?t2d9pRav)|_Yat<{JeZn{+|QVv$xXElZub` z==QUJJz|fS>oo>Hf>z4wOUHY(p7Xl`x_njf@g8}?jtVIIuHxf8a$NTc@K9b4I^H7( z)~e=z}9^F1Q z_C9=8zWMGcO6#MwzUBqFkoXVDkVy&*m1BB5at-RV1f#QaqR9c zP_YmUL_}cIDh<+L7m8vl*sXw_NcpWX&b;3r=Xv(;uFWPyFXNr>V$k(rD_%ku<@5KD z*YDMP1&5UHhsn~vm9Ni&7j8W7(eszAcmt<^6$?g>Dqlu0F<2ti=|ywm%>K18_#?6_DB87Ab7PK&wJ$a8$LjU zaN~K8JRt&9+P!KenAUmCjrfS1vr-`^tc}y-{^Bq36n26re_maNB^RE+l z-lOYB^1i~8(-U~!BO6}&0)GAzc-|w|w)z66JtpwHM}B?xGk6W1!1Eq?ozrJH-FpJh zd*tFBpP-=s1fKWE-*rDhQ=I_^Z`zv8_)9| z+3Md9kge?C+OIq&Z*A}a7Wt0nd5^rny$l*o9MAI}S#w7z#10G0~&wJ!mU*3YnSr?x7$cFB3A@70<_gBdA zr{93@RTrN3$fput!^JBuJnxZb?R*9L$u2zak>4l0gayjmtCh#(n`d9Z!AmYY?~y-e zJO@YR{e{cx1#h3hhchlb@6q+~kDn^P;=+aJJ@SyOCooufew2KEf5*oVd((yIJ-R+e z>k%wXcj5jDIU=GM+9tU0yhmPMTm&;yUAVtO4)QI67nfal-Xkw-R|KAlW0l9`^$Q-r zU*+}Uq$ljZ4+TeDc;2Jy4+`%=@ zx$wM49ysh4uqPA_sG%B&Ondr&OGmt4J%GTuY1ls?~yg; zpM=yG&OGmtFFekL29KS2-XlMImkr2OZ@dKW5>$u?b2 zz=Ma*Jnxa6l=JBt<>S36ub*6)1V5D5yCt3fCIJHPI`h0o&#${99wsUuAI*E@R?2Ra zQFokq-Xm{Q`q`b7uQ&Bq$g8uCL4J`l&wJ#cBS+!b2WOu5$Weo0U~gR)p7+SZu0%m$ z9T%SW$gg)rLIW)qp7+R`Mn*u>`Yt^0k?)p9fnI9F5F)s_i7jji$6MZ ze}x?TQTbi_pPaeBLSA#`Ae23I=KczKWV}CUDxd#b;SA*zW?4ymu%e+H7A|9 zze3lIX6=J#Y0lhVAvd?)3;RzybAN@rY`q`MR<4)Hw~znf3(-l=++U&V+f037N3t{b zSIGMo>;a=A&fH%iPfPQGNr#-dze1kX!w1IhbLRdEIiqklG~4OS{S|WJ!QHTGlQZ{M z`0ZcphK4hoxxYdl($NRDO>*Y`3Ryke2UZVr=Kc!#lZOuk|KrU474qE8KCr;Znfohb z|Fu4FrKL0XSIAbLK5$genfoi`o6CJ*WHV>(uaM`=@`24YzG74nE~d%z-X4EI;a<1Bo^cH$WBuaJ!v`GHaWG2CAv zpZK~L3bRLZe}!zmc|Tm8G@AP>8rEOz4l3VBqMG;km0#Qhbr`=kum^4*d9E99D} zEEsa%k^3v`Cpl36qa*iM$W`C+V4SjJ)l7aoF||&^ypxXHU!m(JCTF2Vm?QUB$mfTj zhgC_A++QJ2*?AE*ra5wdh3pY_8Qv(@slP(jO}+wFk&fJ7A-f$afU+D%?yr!)`&A)j1$1D+K+a({)~$nX|SiFf4w3b|hJZTPs}k^3v;x%KWsNVFsOSIDpI@4-L$ zj@(}%FZ90;af+$GLVoe%0qCYXa({(f-?SLUC?7xdSIF~T7Q>`CNA9nXC(e5aWd|I& zze2ug_Xu|Gape9Ad0G9(Ff-VZ`zz$c?T?{gog?>G$cM@wLt`gL?yr!Gw>^P+BOJNE zLiQQ`6w1dsa({*Vx7{=F5RTkmA+O%_3=WTWM@*N?#TTW^1-o>VdN%9?yr#NJbMhId>y&JLJphz z6jULOoM&n){#;)V^j#Wro=Ltwz8MrbH|9K(+~a&R_-xmh^GvdpsUFm~Y|MEkd4awj z6n1XRc_!IzpdMtlY|MEkIs3LA+|+2yc_z6}kRJFvZNzyddGKdF=sK?v=b7Yrt(rsn zhlZSIl6^B;K-)PDInN~DUa1c^EE;m2Ngf$v0H2>X;5?H&?xZ1D&2PYYCb{y65iERH zpYu#|#y}(J>|3AnO!DF(#xU8qKIfTa?d!(y;$=O~Gs!x<#B!}&64@)MiIL{>8bg+cRV^y4Ik}c|VfCV-x&NIoi8(6{y z7ZvB34gD;kq4NGa zDv!x44qHO~B`VG{$(SZXOe5II>3odD(z-CUgLNb_gBalcUpq^4Hf5^DSwidy z73Z1cb#*Oa>nRoYSIA$}+JoIi73Z1cW6|xwIbFqhCRtmzJ$%Vgah^#IHf#r)%JV7D zBzsS93w!RV&|dmuy|xf}S;cuKU4Lq60fo0!oM)0R{4|Hc2P)1p$$z5Eq0SQ(=b7Yg zW6h!Dj*9b4^88Nbkaj`E{S~s;D>GQCe7=K~$7H`Y=J4gLit|kJp3COooU7tIlN@Gd z0mIIzIL{=vDY1Z8c`D8`$=6NV!A9lt9icoXN1L{TopCDeuaM6vZ*QEa;yjaVf6ffF zVpW`Hk~@`}f~)fN8KpcXcd2Uz+mx>_<(cF>OEb{SQgNP1w&`jHvy?y2vGTf$wK)Wa zsW{K1>!X^OgMsqrOL-=_eM56NoS@=7lf2#79C9*LoM-ZN{kBk~{QaZ;3R$P59h_3W zf2qGho|#|?;mUQ&Gs#UZc7#>CRh(y%A3g63iCa{hXOfFUyFva+73Z1cpKE)oE830|!t2oaj zpE)65s`Bpv<(cG&(t)tCw~F&j^1TK_z^%WE^Gx#k-$S8RYZd32WqSYB|4mEl7q6x!n0>OoM)1CAGtu_HyzG1$;bA)g6%sU&NIn17d+s?LmkdD$#I)A%2ez=b7Y5gEzuE zTOH0b$=McOP*|hQc_z8x@2&9VqBiH5?;sm*yNdBgf6U}>h!c_z7*X9$cPpv`$E z`Ha5u^Y&0}&NIobu3<2(xi;sSWTVc??#IZwxLJ8jcIp@oX1(ijo=L7=90uN9>T;e* z-eVFDJu2&Po=JW;TiFG^qz>nqAp2_~L+)tic8@-ilb_S@>0Dd7&E69=b7ZU<;gI? zsut&&|2YLFD)v>bk(Ya(fX6?zIL{>isY!#JyIP!QvNvWxw&H#A`N=hz;IEkSOuBw& zQw~@!)#5ypd}e$e=vZoTo=M&^^d!_a*Wx^rysh9A=)KY8Jd@n|(rFm-Qj_yc_Mo#c zBtnz(O!DR2b8s?5lk-fndGQ5MP1WQ)lRRzUC9qha$$2K(rsOi*ovF!rCfV3GA2x5& zzA_uRTyY=l}2b>~!h7KTBcHioZbj57kEAwR1Ia;0D2`3}E=Y9LSgaKoQ) zC!+@Femr`AVS9f;kh%s=NslZ24F$^cDbJ+qZ%6!r_=p-fBR%|b1zg`%181dc+^V1= zr3TJP=layZ1-}|NFKyaZ1OMHq{BP3RzG^7@JZs>hv`}l}ptdziCidU^^Bb*&^Sjo- zW$FF3YT*E-bDuA*T3ri&o74dHSLoxjx?BrK7}UU3>1nFkcv8Ct3ZxC{)W#6~8n`B1 z^Qab{Yfz(fZvT7xq{v!mT&D&o&!pEowYwIEzp4hhACJ8CU@dHLs#=*r{&TO*Y93b-hWax+?F2rs}_2sR0HLibUoa%HXc7v4R@tCOsS1lJF9{6OuBAxt2So% zRRi6RM{fL29rTW=h6mESrq;nOx2vH@dex#j==`u6sJ}wbuTHI_{66Dqcqr}tsSbX) zSPhS)uQaQRO&(PP^;hWmi-*@mm2yu9-H%81TUr-q7gobl>965+@%GwkcqTpnR9%eq zsD|g#Ka1<)0q<&fA?<9ejh#1C!%OL=Q?#+UTQ$6r?h>tywtcGMwRFd;+L+L}8s11> zZ>WQv8&<4E?1VDkMccqe_$QwRUttb+H_QCT{8;bIlg{dn~8>;KTfAK6t7DiJV@0bf_$oawu0HOrUj^T!x9)0y-Zv`Y`~RLlw;|?dSHchJlO86~Z;?)G#bghJP>2Fp|v5`R~{E@y{@}DcD zf9!6i?CY+8N@;ZqJzTG@fGX*0v3h9YRsnQB9=*Q?!N%9Y2h_)Ag^ZrS4T$v%}O#aRLC&>rD8ezNiU%Y>koKmY5w%7Z``zOh% z9Zc|=%}?GxNp_ms8uuOk!TTrK*V>@vv)ZA;X@{Dt>Vl1CozfTsFifbPd5uNmD5b?1EM{gdQR zS309_lh3?=lDti`D-L=3iT6*E?KXD9&_Ly$G5Pj&Y1F_tGBzQU-KC9@#u#AU4e_Xh=kKF*c#{z-Cpdq-^XsEqedk|D?mNB=D2{gdR-4``8ebNa z@%~Bj?IB~Zd~F%;pCnsu9*cc~%Xt4J`9f`HoO!#9_fL`om9wG=&&qiJB)M8O93OsPQVh8#8&s*VvwVXFUa1@ucT;X=Hyo?U^9A{mhYjAa*5vtueEfS07FT_aO&9K91|NMoc(m}iJ@LI>ea7_Bx zXFHrQ@Gl&f-ZpXo-go#5)R&<5w_(EoY^&S@8z0tHIO9T*>?a&b*O=4>24tdu(9&t07f-vPIuZlQepc~(K|V9n9_OB|;`xGHe^QE zd_h*VcfjHSRXksiZ#g)it@85|%@^bY3mj0@zKZ7yvfmyDJk+>~=L>RSp#wIvuHyNE ze7l3d1rAj_UywuA3B1v{Kl< zuc(se3-X1x%Ihhn`GV{mE3o<7N}eysAIAtRc~Qyp1=&aW_`H?Zqxpgy+uQ-QzE$#k zLEfQ!y|%{I zK9xLQkZ=9%hviEvdA=aKPxkf2btM%%Uy!Z6`(jm51z95Hh=!@!Y6+B;%?f3RYw^bE9Uyv=*`l9EQ3Z5^> ztG@L`Q>@_mg8XA{P~CH3v%bd*2?eG{=@SH`B98Dz6t%q^94D- zPJg_y><`ZuZTZdf1v!6{^7p~=H_sPj_Z&N%ef}5E7vyh+cDP~EFP<;R+VAY} zX6;`*Uyx1h2jJF#pFCfX@znr)Quim%7vu}U_UJzC2hSJeWiuTxJ@`A%7v#Jl0vl9+ zxt5>FzH*uwrc~&lmK3^G;LH!J?Gs3o@>rip@Wl@O(km zyE+XMwM%)vAcuFJj@KHM@_a$o-ZTRZ8!t(_=wqlmjg(~Iwg0FX< zqwM!7<@th~;5HXmcP{1mg1ltTJS_cC!t(`r@znXaa&HOG7v#bb3vk5a5}q%}TE+{} z(yWx{3$oLfg_xzh9`z;2eQqv7L#|wtGuTLuB`GQRUy#d{d*!dGN_f5?Pg8zZ!|5(1JYSHH zuUd}k#U(snkgq78fANA6o-fFYdoRa&+e>)9AlnUGj)6N%c)lR-^;wQzj+O9yL3SUy z0+(Mdp$}I>rTo`?W+aYY=>l5+^Y}>24RqmsP;|X`QY7|0?85t?$Sd3`@9vDmdf>wQpvWFuBGK%DGw*{UyRMJK_T$I#J}9!i zay@kX7~Tg(u9p*uk0y=ceNg1&uaW4|dnE6JBA+mf!ierpybp>zc|a8YnlOU*L6I*G zk3y|^!+0MQIc``Kj=463_d$^>$3|hl1A}=V6nXf}D0~_=i1$H}Yi*3eX}bpUJ}9!~ z9_96BBkzME&p8o=KSu)ZgCf7W8-=@O2;K)p{{A)!gU2~2o$&v@-j9DqVa|Sg-Umh3 zvvi`-@%;ea2Spy+G8)ac4d8uH>^<9t_d$`5D6bd4-3B_z=kHKnZ^tnk-Umh3+ZRRSvFkRx4~qQeel+So zw1KYj`QcBaQSYh^?}MW2Lmx$>)khoXF0c13j>gCJY@vtr@SD*}m(><}N=GS+ zpy=&K-Hygv-nL*RuU9KyAMXRU&`WyZ*=Rg+!j|_z(eodjkH)TdZFwIQIqg(5&ZxG9 zzVi8P)1z_BD_h>-?Es|zD&LO-N7w;M*VBo{>ErESp!CdNQMhrq9q)sp_ZR#n3a5{;gTeB;%jYPx zbF<@pP;~vt?;3S=s5QQawY+3L971!f5Gko1$>Ja!>Ub zY3~hDX!gh!#!9CsfBz>duQyJ5%(5svsAC7t(&@9Kuu#hmT%><4jzay zV+-!mdt;+_Wfoam3 z$6|1PlnwkVo&6yOM<{+rSKIuf9j|wy=Sj(%Qq1qTiGLFiSdQ@lmWd zw?E95-WhpR*$ydqrV=@l;`wwiA?!GD+I~)81o2A1hB`fnu5Ac+B!eq1z?G9ejNyC%T{8l&E zBK>e?GN!!h3R|To98N~96I@W1PY%JVhN;gEFinZp-@Hu0nSV{; zuylT93R>Pag&^sbdZ}ofqI4>ycblc6PoXIUORs8`iWB`!Aw+s@!&E#s*p%~3`ueVH zl!|E!O*zjbKTxihk2Zxc`TQ-aRJ3Sg%6TST&rqI!r>iOFndJ4lsd(vQ8_qMy@HYj2 zerv;dCV9uJ6ufR_%6TSP`$`J_xYdU9Omc(d6dbar4d3Fn#QlYie;yjb=`aA`L?ih2PNq$$7g61K{oM-aeze~Z`4#u2kl9xV8 z!3`&kIL{>ixtoHg1B^J&B%gVlg1U)DoM)0By-vZ#cZ@jCB)3#tx3MwjndA;nQn03# zG3S}&HP2G;?N=ktGs!RCrr_!}#&AY?Opbh?f=+deInN~b`mKDtQ;a#!Bs;W7#rz${ zoM)1cSfyf+lQHL+>Lu6%!6>2sb*Htm{<--JHrndCFd_e=O3ea)YQa;jYR0oM)03 zWhCLrCHkCalH=AVVg4e0&NIoyW0LUs0)5Ui$pv;v_-%(i=b7ZfR!R8wu0H3PQ~nux!r8gQOT{@peabCpi`W92c~_)h}9 zZg0qWCb{TB0-k$ezB)CVBsq1YAAN0G=z4$;&z?VBApy&NImwwGwbg zz5(Z%>=*H9tz3U4pP!c%kJa7=oM+PYS$pE~r)&NIoaSI46f zw&XmM{3b9S<2$tEJd?a6B_1nUwB$UKtZ^+KH4IvEo=J{WzW#l0x8OXJeCd5W#?EWO zc_w*Lc|4j%HRn8&Y^j-mXCLWto=Nton}ET;nsJ^<&TW{0sXd!vd7SKW;SPJd=EWYyvKy+=TN?@{V~47!lBz^Gx!y6$#k8dt=Ts$u(OO@X5JGoM)1^ zg(hISMI+8L$-Y?$_-kN8&NIn69}^JQG~hgw?Btk;dk)s;Jd>=ImWbY`>T#Y)KHo73 zt3q@+&m^CUNWyg;Rh(y%ht^BRb6d1I&m{Y8NXA1?>T;e*F8Y~_vAb$>o=L7!{{3*R z(B%9>m!97<1WzX35?ab*a*ysIIDGysQA>JOj}T1Az9ni)FR>0m$h{@%NM9Npf+xyu ziMs#0J~;%vb#4i5X_ti|cs1yzpzMWSf6kl`^i94Y=wl&&n-zkO&t4PsnEo5TGz8O= z^F=*rzQW#2?*HvTM@d#lg z4VG$5nHnyPrN0hRX%w)~RuK zj}T!h?S5E|4l9C%nRM(4HLA6Og}L;|Ts5AHKO!uoTji*6eew~}Ryz5l8Xq1yBHBs6 zKdr`Vy1}Bo^p`v}wwV&eAbg)Oey>i0C3cAYY9)6nB+&ysF0fin~c~DpaG!*bvcO`nhtwwpWPgAzh%n z{XymVJ*5wvSL2Y=A>tqDPM6fUbx^3Vl6F!){@i_`qL*~-G&R1y8Y+5A+bW;WD+{&g zBmFB=jn0m0(N{VkQH|Q}YSB+R@R%BX--QZm>GzRp?Ab^y`b$q!{(N?*)WSyk#V$4O zGE@s&>0@ivDD2h3PWtr}wbEZyiviNDN2sy%p<38WXZ2O%ydt%r{Db~Hu3D&Z-A}a; z(nCztI7}-{fb@yx%Aa3@FoDwh>ZmbDxjs;O;-65w^Fu8LNv}}8pO4lG6N9B6{0>Ej zi)t}Mdc39@Umj44q0+9+)YxLAS`3pe?xMzvs20Perzqd=37ynpgtW7@8g(9r3P^G%gM zFRf59QCfSXTKRc6M7T=3`Koc6d5Cb6ZgyRbm*RuPBp%0KAiY1Tgy zt9}KFInq7+BJo99pqMMYyetwm&IgKl(kC6GaMAogF<*L6dK7wB9})|suNo-%Pya(= zp>$UzA6(cmKrE7eX%d6=ItPfw(vLD@FsJIESR&oP;V4cW=r5K^hh8{}mwN9P%cS>C zJBHo$_lo7xZGIiY2n%1aLfSR#IKEi#BUVbkoE(c2ymyOL(qkLMVPfVkv06I)ava(& z+a=aW&)KH@yxC)ySS#J9X#zGh+9}pa@9;`Mht501dg?5$qHQ~G^aB942uNq9-STuH>Poz{yj z(ycU;@bR_PVykq#O%mR3wOnkIE?Ja>5jBg1w{)(55{{3XFSbit9ZSMdWwXT&>7>g^ zINNH5*eQLzRx(~&HdXABzBMcvCuMnv-T(7uC9j$2E_|ddUw5(-3h`x^8|dwhtR90;DrOD|v$ph(pruElyx9V|x)O-Fnms{1j;? z4oipooLZv56 zOT(rm{e)V2@b)zHaOx+*q?a5^!wYr$ig4*MH`B14-qHrJuw53(S$s2kH!Bulrwmw_hk9Yl)s$G;ia;<%+qm7drt6MK8N7bm2jT4!Rrrxqej z`tQt4)JQiI>C(TCWa67arXoYSSwSY=ZqY_$N(X+*#P0P?M3!_x?JNwsZzQs%%T2Q| z>b{}Kk)H0Dh1bgrMXq$i^;tMU*GS|^uZYM(|2!jcQhMu|EOb3*Bu+{Hev^fl^o_)6 z>HUqfQEP#bI3qo~S2pVXG8AW}HD+hy))B_yob-+3+4w5YSe%zOf1iyD`WcH0(r#UH z@U4@fxG24OP!1Y3GZvSmm(R_?GY5>tW$7f(95ftkEb^r{?a09ohm6G)=^JZv(AB<` zxGLRcY7X9>ZzKw&KXuQ+#?Hp#nzYB8Y;-F&7T2XM)!Asa-dGe$KbVq@f$xmO4e8`g z*;shTNZgdptDTJ=>x{)M>CYuu%KZyQ;=hv%);fBM&iEo5yiJ!v=R@bgF>>fqeW{`B%QHcdA)$vqF8#Q^5;9%ptX1?J$XSE z_E^wbJd!pYn}sVP+K9)}x9qd9?Z0N?iS&{7Sy(pGR6Lcg(@X6aq@5!((e{>s_$)m%Cle1ZH4tB< zgNib7NS40%Dm_N|`*@_TzW65XHarVQ&1oUNOaBPSLZ_hS;)nE#ds(>WwVwDX{k2&( zE*sNK{E}WWFdHvD)Dyp@Lw9B4%)WY}TzZ@G{pxV4nfN39CO;du9cU^lq=%MgW8Yp) zMWuAPaSpDrYAmXxzYfSj`@RiDwRGb}Irwr-15qQrC?E#|o7WeAr5`@dQSyp+bh{@tj_`>@Hc!*g+XN|i$$ z&HsMBu*u8C$6tOs)Rm5Sk&E~5{B+QkK4zbXT|GWH=twUL$ipp<-#F0zCVIVt`X{j< zsK|l#H<6o#oWuz>g$}g8i9EyX6n0s2-huWvk(b4s!gdbX4z$0CJk9Jhc5ajGK>M4> z%_C0Zkt4?)Xnzwq+TjfL)d_Q;{Y~VhU(aCMJ_j9We-pWP^jRz%y32w3Tx4_SbIQEA z$$|Dak!$@phnu68Ine$la+=S1T)1|Y1NFJcO-Elqzd_?1=zbCM1g(oWyV+<5+TTRJ zk$e$jd`3Ia{w8uq_e&U&Hqe27{|&iwoy$0LWKRd$-$c$yy^N*mjt;cHi5$EnAN5;z za-jW9{Jxn3?QbIQX;y$^!c-2_=OSlZ zDZoA-8#qv(i#&7PHJsV2p#$A7Layn49ozS)>tHTj{O&rQ)6sOWkhbtI#7^UDIkc5F z9eo3v_pam6PTE=PCLaG<+kx&Eq1Q`2b`#$$*K)9wKIwQ1`wXn*K>M5M`j5}I(A!eS zf%Z3%&-vU&$HzJjw7-db%IFSO_SSTu{Y~V~>O0uI*GGHW-$Z_Ccvm@Z{cBJAo5+)P z+{G`wR1UPiiR}01F2>H(b)Y^MdClT`SbJL?2fAN`-0AK;Ot!4!K)?Tn?9lo?W*2BV z(EcWJg~xp~JW^v%`|+v2sbw@wzrqwVN`@> zWsmJ0q*o6v!bwR*_Cnfwd=b8keP~YsA-#PYry|s=``R9*Q~DQSi(RGm1EojyEW%wj zZ|nz25A2|P{Hc%Z2TSYLFG3xSH}-VD2)*9zSIXz#{--_dZz6{%pZ~Rp@AkC6iGAS# zZe9Gxp7uA9yIg;O7ELPcX@3*B-@ zFrO!p6MFcIUS@~kjPjW5ViYJk7YD*w>5EQ5Vtj+ce4a$t_01y0;-o-6Pa-e(I3^NT z1oC+j+5KgLuxua5=Sk%5i78@~Rv@1zk#DTc5UXAt;`1c(^Ap*k@zXJ_~e4a!e-9AISeHp;#N#r%@=_2550G}t313WUsyu<)LPa=0YpCP<< z2k?0k`9+;fvD!C)&y&d6BeKNwJ^_55L>@CON4y^%z~@P1y}~>(a#aAICy`SI=ZQhv z0{A?MoOCQt6uT%p9hJxAs@#)eq zX9e(i61h;E5p_NtWrwHsQiuxPsk@vqm zD~4=7$mdC9{fp;B^74axoca&*w?xwcZ7y_A-AyPa@m( zx*>WE_viB@^68DY#7Sp=K2IX2Zoeard^^DBN#tFl?~Bz>5Ab;s8GaOrGxrYgc@nvC z{U@SD>;XPcB47FWT*P@D;PWJMv+3`|rCA5~Jc(R?z$ekS;{iTTB6qXO{*&*w?x zQ~7_ysDk}`oG zoAoNleY=m(lgR6h>cOJaeSDro&aB-4ZhP+I^Ca?+1C3zVn0UOrDETP`#JAN#$0oiU-rCL-x*zoA^CWUexH(iA`0{xYS!bE@`-9Yb_&kZ+B&QRMFZJQ`By!y^ z-C&Wm51%KIf7)6>`MlkHoqY#EJ+R5ihWUc-~ z;e)axhJKzR8=8y+F>wcAr|YMb-;e3^WDED>$*wQ`AiH`C_v6V= z1}giAc5mT+JX!lv0Ca!p#r=4)PNN_ge#DFW@#KweArO}0#r=5lmtkR${@IKB@noY@ zk+67$7x&}Im+!?u?jSGj$CFQ*#KMvxUfho-w;PrKVRO8=A5XsIn+#?hy|^Dw-t2P% zT6Oc{emvPaCa-BU3eBQ z-t**sJo(0^^AO*_i~I3p`zU1}y7Kz;^Ax#f-eqXl-;4Y4WS37@;JB?9_v6XU&lf;N zZ!hl0lfyb)hZiPZ+>a;E4laa(7oOaYC*OT|171Jza-_4=;woA)efiCs%ANh95mWxgSqXw=9M!6Fs>fPyS|A3?cTO+>a-R z=oZ6sO;7H}lW&C;!H5Q)+>a-le0Tt>l^t&M^Avey%mYZ@?8*Ija^;Q(FlDa;w78ZlqNl!i>uCMsD$!5{$Pd@kK$-yHwiMmDk+>a-( zow!-pe$3~7JXxe~7AAM|xgSrqca;M9d}5a9(bDj@nrYd!=mTsQ{0ayoBRzDALpIoemr@l zbFk2PaFYA+oBojtZIs947Kum2f|y+H$CJAb zIW87V&gFhQ*=SIlXk()6u$RxDR1hc5_0Q#gJY63)CrV-Jxzn|y;$Hte?#GkI?KvtIb<5*^JUP%LM%;GD z1AFB$x%KcUk>Zxe{dn?wtw=G}HIMu8a+;+Y%)r`sHyyo}Bh2TI{#U<9<9j*)dv_*W_|Po_udcxM-@%<9<9j=2nQXQQrSZ zvBF--aXn;@@$To^6ZD&OxD zrSJEQ6}1lLazCD)Uvw)`pmQ$wAG9y8By_XF8AZfVXhZNn)3Ejl*eR4^%c=qHy5T#U+^mw`Au_SnsluCj##Ui%l&wI z{tn|u;>Cj;?#GiGAAKe)Hs)|Yp4@!OOEK$e4)^29*B8ANwYKEIEafqIK~R~{yOYiR zc=G1oU&N`>Y?vdjyJq|ndv0gLT8QhO2-*oH=9YZp>A5Tsj)(>_p%HV!Hd5q}* z$X=Pj{dn?=)PWH0kiq?Ua;pQ%?^|4z!Tosh(dnb%rC&O%Qy!B~oOcGT_;l{alV66o z!n-}`+>a-B{NoPzJDvOSa+8d9n?HEaJHzPd>MFJKVe;$NhM6*K%cl^PD*D$CKOX?t-S@V!0nr?q|OnHXe-S zemvP^rw^1H#d1HMyeoDOtd2X*{djUjGe6Luew_R9a;EY`q^k+8yV9 zJlTBF0dQ!1ocrkXx%Kdn<%cx-Z=fY9$$CG0Qg}}beN4XzQ zPS*~FlqE;GA5V_H8VUh*j&eVq{Jm`$1UFZ9MktTTqZ&uRltxFnA5Tt7iiBj%quh@t zFLjTGmy=_-A5VU@HwG?ujp2SgIqJtz*!wt|`|;#v{fi^+>a;c|A<%q?TF@nJbBExM0mP7iu>{8jvh&{Yd{qDq& zlELqGB=_UV&)iZ$&pVR)@#IfOPr%O5Nbbjz-_}isj+GJIk0)<8$$&EN2=2#|-)Lk) z{nZhiXOe>gvLIn<1m~ILDJ9u(aYh8^nPkVoxuCNlg7ZwW{fsJo=Kh+c^;B}hI5`t{`Buf7*ib1 zc_umS#3d+N8qRqpdEME|a6dYn^GveYoGY-fPdMk9Nwguqj6wY}j**EYi1QdmFo=N`I z?<(k?3gbMJysPpGEDZ|dJd-?r#8uE(8pe4hxp3!Im^?9z^GtHRsH^aIXc*_2WY@b_ zVXb01A11HWEr5TN-`Ps%!{pPS3n0WIjPp!#LgY2*rI^l#$^Txs23B5SoM)0RKE4L^ zSB7z(Nj92&9ZFroIL{=v4Y>~WdW3PFNj`SrI^47j<2;kBdU_pV9K$%zB!gBVH0&0} zc_vw7bRld#qvkx5tUtC8+Fnv~o=LtHQV27ys5#FhyKCHl^NDKCGszbx-+<2B)SPFM zFDKoAR!M5kGs)u44LCYp&3Pty{J@)F*ImtdCfVfPO=$Bel=Dn-JLUJ0&U_fkc_#VF z^jom_RVe3~WbZ|{AmC{z=b7a1ZnwcSDU|a}a&@aakQ*M#c_z8;)jLpYTPWw5UfZ1zWBJbDl}IuKxyFuMg%tlRPi=4NS5L<~);JyWlNYyg0&n zCb?;w_h6NOg!4@Dsd*)^dD#)pGs&~UO2O6S2OmfddAK`_65a*fX zs1u*yN|zwcGs#b5KEtn5hdIwAN3Qz<)0Qj$AENo+_xJ5VUm>>EVa_w@`njxcFv&lV z^GtsG>>n`s>LJcE$)^&2LAApn&NIm~Q_A7f$^gzY$%UgUq3roV&NIn7DyyLr9^^ce zym*=hc8T!kJd+%BS`!m*9N;{YJomE}4q9@6^Gx#Pg|*STa6jjnWN1-Wxw(Bm=b7YP zY1$Zkb|2@N z;f@=AoM)2FHJYHtP38ad<=1QfjHVc}(vR~@x_-E+9(rH*2 zC3Yt}+WT;x3ENF?D*Le( za-Ip#uG5^ni&8nygclXHpdX`CInRV$#xUlf)vg(;SL9SQLwz{ z5Uvlyw*BP#bKWVOXTsaR_NFw~6wWi@7IXSgRdovIneelcKGf7Xh4V}}tdl*xmXF8v zVb~_#p6&#uaGnYK80_h(d_1lX!yAI_>2RGC&NJaw0roVidkW{7@QJ1NRJTJ4=b3P& zCvttdnkk%T!lBaMniS46;qAxmDN)`d3fG5W{SkW_+c$;tO!&bbdkUzO!g(gFOOVgs zJB9O1_<)%`of|FhxuiT^Q^lS(NaOl2_OB`JL+{d4IM0Mf{p~|t*QRiu3Ey|Lr{Vij zIM0Ml%IwMLMGEJcwWXtC|L@9jAAB;=kKUGz;ye>hTq*AjY&@FtOnCYM zdGA?iBjxxVPyDFv!BL!NVt#(5@u`K6wM+Jr*c2>c@E| z{5d>;rVsMvJQMDEFo2?*eK^mAXWb4U8&7Y}GvO}30%*(_FU~XJCoSZ?s2>mGJQMEb z7)ZTG4dXl$Hk}tpi_Up+o(bPL6-bfeJUP#V$Nvqa53M~p&xGx&29ajDj`K`7+c=1} zw9s*$32VCrk?$@K&NJc6(Ltovd2pTyU)mHz4{LdFo(X>{2qORQLpjfc^*Qoh+s}t` zo(V6`3zF*%4&^)(c0C+KV;g#Ko(Zo$6h!?TJUGvUR~!tYVFNul&xE7*1knsf56&~; z;qv+Org(6k3AZ>OL`|1?aGnXf-3g+L`#d<$goj-VqR06joM*y29|h5yEDz2z*)Qb# z&-36s6E@rrqQdJQoM-a>n?cm+j0fkL@VmP~MmK7)0fXTo-k1Iac*$9X0^q+uYvn5yGE z6JFIOkS2}Pah?hH*9KBS7aixBaF~35^xT8l%%e>%9-%+wl7)(bRLgyBMW7)MOO7Hge}Y6Z==0j3#aRV9qn) z`TfSw-jjnl&xB>ZM#C2m<~$RQ+&hl^@&|FA370$>Pu^<=a-Ioqx0y&5>j!Y232UcM zq7~`=InRWXK1`;%58XJ=gx@WiO8KkYIM0Lwtf$i~3pdU)VaKC0sB5{F^Gx`5XbcTI zujM=wez<2A)$63?JQHraV>b0V<;r;`>>L_PJ7>9ao(YdS9ZR9HuAFDW^^NAx%#p5~ zXTpQU95QL|!g(fqe()R`bjFGEO!#K#97bLuGo(U(vilgmM`*NNMpQs*BM_<`-4=i&xBumPoRn8 zdvcx$FQ-K6^WL&$*S6z4 z6TVboF5Qmk#(5?jO>=4Zmad#1u-mC*a_rNY^GsM}I*;CT?96#4Y%^dUeJir%JQI$YK9ABT+j5=>=jG3% zZKG{D&xBk2oJScNTh24#3O(l2rRQqSGvTk(=2NqqYR)s^IS1yGE>g{TChYNiK1GaH zbDjyO8ZV%8F>1~;;YwW=&?6%?=b3N?zXjB7o(<=jaLJ|x)N-^9=b5m3jTAa?(uVU) z_{-=Nx|3|fc_#cSCxzDj?8JE{{G(DTnfK|$c_v)$l1dvMbmTk}KA)6IR~B{TJQJR> zDV0u!b>ut~{(dx-3afYIJQE&So=P{;J8+%}f9<=F$|rZ=JQFUNypS@Rci=n|UYEU) zB1T$so(Z4-zK}F0tT@kv+qf;FB2O#MGvR$p7g6KCmYiq8b*?Ryn9fGYd%!97HeEua<19GO#C}(|B@{N< zg7Zwc+T11N)nDF|PC35s*hqrnDx+S{D-O!(F)gY3UI=R6bc7iSDOJQH3dk6(AqobycBdy0WVOU*gYgjY>AP_X>}!h9F_bd-U- z%q%$1guTKI=M2m`(FHRn7N`v=OOAKTrW^GrBJzTP@N%s9`4XUg~Ee#VUROgLz^ zfm&vpah?gs%relet7e>M!f)3aXx0=n&NE@-BKdxrnQ@*8e|&GC@3-1>o(bC+rPI-M z?K#hcTiK9YS{#d#)dl94XwTd6qDgx_CJrx$)I&NJZ$U6#_gEA2SX zgxkh0rC*=hah?e`y}gt=uWHA6CcL0U20ig?$9X1vcw`3UwQ9$CCj5F&2K9c`mh((F z=ywMFx1}xTneg2{%j9~TZ8^_`m(E;9hmzZJo(VrGT1LL^Z8*<_*BLFRwP#y%o(Z=Z zyqrqBTXUWXk55`od)u_;JQIF%d^t5c+KTf`cv96Bv}I^3&NJaMmlf3ZWlPR8;TH)j zC||CBR9WT=aGQfGC~QFs&NJa<_g2u(bImzFFp-`&au*F4V@;LhHe57n7mahWCgcb3 zpsBm4NmpyCqWJKvUG%q)HC0s{m$r*E?W_s;0ggA`wu^2zwx()|zntAgr#@Rzb;T*C zcG1)GR#Zdr^nzWKGRBI~`_8ZD$S&IX(~{7;1*`wapFhEpIQx+9-#v>mtSkxd1^a&v z%c6xZEC}297ZWSj+nHfObrf4AWl_I!bE>P@U#`z{WsN!2Q~Y6m7I_XZCsV~W)@D(! z2IlmS;?-I5`R|%heZ~1Fvgq1OGiso?fm{#hk%JjER2*A5n?h@tQ6t5ghS@awaC>U3 z_;l-RN?p~SnkY{0noS>Pwx_0wI}gaFrMmXiOmT~#Z0g*rJvCR{XjV3LsNJ4gDE_@D znZG{tvutXxO+_|}8@|papA9NfD^4lSmi3y7Y!%Ouj~_1gcUGK#C7Y%fs;Gir*Gw%k^ee)J^f;T)CdjDHYi%{%?Oa^?#_M?urNP$|k38D(a#5^4e^g{a!^q z6*pa#P5Ym!2>np_ygf3q$?CX@dMoZYN50?xRMbcD=+W8qO&)Kr_D%ehZ54$mzAE7i|e5&EI<`WJSU z`**7-Qt{MJTj-wr|3g0%_CMLYg+8895%L4LcGwoOkk2DcB-i78+m2=^Ub9lJH+#Mv$%Mtr`8lR}ozws0dpU&9V^ zzlp06pReJR8B6G%nGv6_;px#!Xpp@TpReH!NlVDV#E8$=@a4rzDClQZK3~HL=}TyH zc2z!K!!@NdU8?f=8rCmgLNRBm@cA0Pc5(?-8eE0X*Kl6dG}3>O_c)Z>a7L>%s&=_D zpReJu{nO}^rZS(e;bH!1WLZ#&&)4vw&@^hNsl?}N_@vx_sA(lWU&AI-(#YmkMLu7{ z&*IWZy`&6}hR4%rQF#SEU&GfPr_rvW3VgnX%YLU(;rI%CzJ_0v zr%@Bn3VgnXoBv~=?zR>9d=2-qHBh*`{}9gCu!XaM+FdN?ydSP9>#dTl<(&7!CNTy& zlu*ujKm0*{-)=d!ob!Hob%KGK)+!gRc+;@+GX3P6!;(QIq-8IO( zrHu1_xc)T*HJ(()c|V+R+aT-dGS2&9%~b>am|DhpKdd`%pdmZTIPZsFNyi>7jUB-DooFe`7 zaT(|Ru$I0V+{8z?#KkR&6etuWVIPZrm$^FTv$~f*vN&imo?4F<|-UCwzwyl|O;dQ0Pc4ZF+#&(Id-ocF`$ryA%_wQ|n; zVP9FldApQz-Vg7Uzdwdn<-$R3!*@CwXt-NB=l$@rmIj*My`1xYxT%SOT!xi%-Va}? zVxW~C<(&7!_dlf37r7tjYxr_;8qKmV=e(cy7p2h-c|Ta3uVIrjX;dm7kMlJ=Rl3vA za?bnVn)jsJlylw>yT6iuzZJ_l?}t~GrcsQlob!IT!u2#7PUW2U!Xqo)|9wfKn zcf-=CcAs+2`{BCkG>Y$A&Urt)x=k9H$j9S+4d+)%qux>FocF_x|1P1OUCKG{=i}ck zAz!a@&immCx0X=2b2;bzaHTs-Xs`Tz#Q7TTe0>RNuaaePe z^L{ueIgN~WmT}$>>(`~x^ATktNN&S<`_m}Usf_b}c=wSsDt9U4ydPfwAdNOzm2ut= zhyRr0Tca}0`{Bq|23oZHFX#PmVSNLo@BGVoKYYKIfyNK`%XvSnuVbL?<$pNuhv&=R zx0}U(IPZrq_A-#e@jsmR!<{@0lqBzmit{x*Y?guQ#{S{FAKov=uZB^71kTsIKSz!S z^8Q^oU&FBv4Rlf7Piu_gXYJCdTJt}g_hbK;iRpAp-meSiYxvXpba}r0&3Qlkr#PK% z5Bkk{Kitc9Dd~^@;=CVD8NZYkdi>(NA2vC;ls+~2#d$ycq-zEpwfx0-Kin`OgA#PV zIPZteK4;Kh>tCGr!`B8bBZI>)&imn+@yp1h?Jv&z;VNsF5t;ttydPehw~XBW`NerZ z+-LtXY9=2)OK!ulNy{iw^^5aMC>hy#2emHVK29-Yh&Urulqj?6!MttyL&0UDEh{EKm1|L zQtB1@jq_euy*HK8qDwjNh4l+k$$LyG=e=;19;x&)rIhntcyDT|t>^Iq6Z%%`CVC7k!d(GBL)LzfcHd*N&M=8>*%3Fp1A zDq|jb%KNh(lH0Jc=RC?z|IB$W{GsYR>U#V$=e_X$ykv4J{mgkUY#NtL&b3Q8?}eKV zOr~>nN;vO@bzkRFT=x>rd*Q8z=F&EG3Fp1=>bSX7*Stg=mD}*IzH_O8+<#25yYXE5 z*SCc8UhJR$Dv3(RlyKe)KRTC0r~OJe?}c^Cljugv63% zA%;GlD&f2rwsMQ10a+!S_rg=R%%tg)OE~X^)9%h7?d%fHd*RUTGiY~s3Fp1A{n+WW zd0GkQy>Q%`X%zmbg!5i_)4x-xUj0(ed*OmwQ>n>?63%;J(~eVUUd2-JNN&T87EPuL z^6`%qANVwhYMn3PychdB+fO2m>_L30?C%&ik+v6>aNdjk7cNa8!+{dcd*O5SCQ#2? zC7k#2^RFLI{<$Tb_rgi_$5Z;863%E*BI+%E~cyc$cHh0nQP5*{&T92NUN=YC0e zt7<$|uJoMyCE=SjC(zuSXWTCd$F!SB#ZJ$-UlM-XXA=E5{*?PA;a`0w%k$M!?w5qE z>r9~*iBGs+5?)z6g_;*U=6*@|)!V7m>-i(@mxQ!{gQB})^TKfu$cQL;gH>N zw4i%2_e;Y0-Qvme*F)}?gnylkr>JVh+%E|qcTb?p?TWcy5;m$Ruiq|v$e$-N*$Q*r zGzk;>6Xw&yzI#V%p8NDCtWN|#YZ0S~Z`_}-J`p^x_k2zDTW*B)iC}qt)QA&qg!PHw zci%Q@u3m8?^q<0|b#`m6$GQ>LCxW}#=WEiNxe?~m!`;uFm1|qN5!NSyC-uFhx%XZx z@A>dQkADADW2bT>tWSjf`OiOTf}Uv!>l4AIqslZJrfLc66Tw66jKqE?EwxrWe2uYi zx7AV`#cu25+TCVaYOAVSOSz{?0B3aW}`6us#voC(~K1KIlqVp9l_EJ3#!( zb0w@#1lNohB1$K@64obz`+XTEZj5jxtWN~5z33;#C%6*UCxXu&2^8-0T?zB);pDx; z#gAB5!umvT`&!{bH^G&#J`ubyELv0@?Mhgm2zK`$BjTN03F{NVvr5K^nbxj^^@-r# zS0;*wEnErf6Twy!r--xvxDxtL;STesiN)_-2X^*rY?jF zGI)ILiSeR!O&3Do1AnL$FNS?}CMU)JJd6`V&pVT|;-;qZ`A#~Mi{j%m<3##JXTthK zc>IQ!b40;UXF~re{AkP^QRR&@q5l-_5;aGZd~qhMPXy0#nj?-pa3-uz1YaqfBfed8 zCag~c_Zt;2+}=A=E$MpFzTsaS=Z_mj#)?;!*4Fr$jiTC$Z;ouEIaL%*SkDZ{oB!#e z>7Eu%SbqaPY3Zh^s*NVBX9nA9himNKM-kTFfUg$M)a*@)BCKZy-%OmZDd-Z#;{}|( zAVahIZzPWw@O_tmHT}*+@^}GfE!(NtyE&4_3pj4#Apk20YBPa zq?sgpm@r7{1zvj`q9;DhH%H7Tznc)Wnycdj7z*NEit0^a0f zBpN)9;PC?Pf6!Q5UJ$|K1>CmVKVpAW1dkVR!_+3iHa>#K3%GD=E3t5D1dkVRi~RQD z#-IouFW|99ti|%q5j>0u11$=EpfGDmW!Q%z| z1MwUi|zT z&f^9AMV%n-J`3mZf^C%`o;(fb@dEC9G+u1F8_weeynI!>=py%Hynr)5#tSF;c#Ict zM2`ef!@>2c2_J(WkKgdA+s0zo za6cZu;Vn+4;)=B&kKgdfrj13Uu^*4$u_qQ?(k9>4kcOYOwSU%otk!`{;^Md=w| z9>3vh?QO)FvA#Th!)+^e6M1gFJbuIX19}SwS6?2#;cr_VMdnmr9>3uodtF3WKVKfd zVV@p@M93Q-9>3v?-8x}@$%n^pIPtBoP(SzK@f-fpI#~34;KSoL9Md#RRL}9@@f)7p zYLw`)*oVh&_@d(kQMA^F$8Y%M@@XPqvk#Bo@S&{PqQBga?|bl?+lR+*cv15O;(#>1@4=ro$hk-I@%X+6fBCRTtQg_L<2Ss_JWaSS z@Zs?ro>DJesIz={{DzIIW{3&7K0JQIE+)&x9r=3keGgVYTp`xW*MskSuyemvA~C~< z$8Y#o$ZAo4whxcr@cFDYB73S2kKgdvziZ|EOdlS<;qG77iTNQuJbuH^Zmt*I`uOnp z&Au(?_Nsk&{D$9D+bBNt^x^RvPPN)3I$8Pf_zgdNvq?O#_Tljxo~Pd|(w%&G{Dy6B zY!FUGdH{53CCNX`G50Brl!DEvc@9)FoH(Y(E$$ z-|*9UnId7n4_}Y|M|xHNTv2Ui2w#tepBChb&}kujJsQ64kSE4Y58><4@a%ngqHsnC zUyp|WR*-AsM27J7Xn5d&!=is+2nEY+cvG@m%Vt;zUyp`koG>-hD#& zdNiE1BVT-R3*qb0uxYgdvDY(%uSdg~kp<$Ee0{hc4S)WpP`sAUhkP4$-B2hZdWG=y zXn3sth`47F!q=nWZwro!i0&bLJsLi~;h0!#AHvt8Ve|dRMbr8rd_5Yr-E~5&ejUu$ zqha-rlVb1MV7?v=@2z@ThzY@bJsRE^cSgJ(5X{%3;r-js32&!hz8(#qp$o#oJD9IW z!+M!^Yv)Bea|9sC@q+;N5fYdUlFt_n6F2}+bgkfYbA>YRSl+jm2x;B_*D-I|x5+Rj>DORy{mm=|Lbr8)_Jksv6s604`;uKf6 zza);g38Hw#M;BZabt(r@f@0O<3!?A+KuT1sb-y6u_Xkpv;<{tci*L&VX|Cc4gU$(c zNFXIEuBSgM#&!;*d5WD*oDr341k!xP5yQ@iyN?5Cf#QoBPm6c*{FsQCNXUBX9xK06e@UbIv68{8Ro%wkyOE`Ff5i?vb!uSe(|=am6k@ zmy6Dq^|A-;f3J6?Tr2q8DLtK3yhJP$Z4T?{l;W8~GeqM9dOEH6TgFn6c0^BS6d!t$ zE@BSp3D-C9{(t8f#IlomI;Xh0Q<`u%ucz~h2kcrbY%c2Qg5oO&7K+{v^>k73LWdMF z=82vzDgIn%zStu_|I3P3Kb|Yj7U`)-amDwEqConJVxtBLVxv6%s^ZQ6#)+x&{asVM zz*??_cver>6^9$m79R5T+)(^;%uHb;kH_^5yq^tm(}h;qdYWs^*^5;EPTxpB1aIWf4PZZaW z@)p@;dU~pOara?jnVduXO!0!>9wP3&Uf%QlfA7Ebl_A3OmY!ZH-uGazI4(b*mx=@S z4-~3gJ-t%Atyg~$ApiegE52=_6-M&^|Bd1k<6Xp?96h~NY-Q~%Nd7*(Q!JPF7j^UW z^j`77{z9CRzuzAecX{C`thejwqvBnU9Yn1Bd-bYKqPn~oSMK*e_m*H=3 z97K6rJ=e={OoD@`&_vJmGCXpygV@zt&-F6=u$zO}W31 zUF660GMx6TuXuFakLzW)`t**UNCSQ;4WMbr{#na9Pt(al>^O*URvYGZErKgJE1R!vRl5i8UWQxn71pe;X$j zKK0~!8NOO~vM74)$@MZ^t!$d`+vUmiGJN(`jQB9zlj~);W#u{Is+}j-%kX=xT%Wjy zC)dmHuQ7?DnvW;f%ka?jxuR8PPp+5Y@6YCmHaB!!FT)Sz+6(r%Ie#iH2-9oNh7rj==8!xkOa%dqBPx|p1-<9eBWBSUmuq~m%Su3)x8++3^UdKoSr zxJuX=bX+gPRr;?Hwy8R%@QZcw8TWH#z((s>`2;>m%^kRvSg~zdEj$;ov8m zgw-q^*UNC_@JumVr{j7V{&QoCI2fbjdKuQ%-X?bJ&~d#C@9w)@)HbPEpvkraeY@``t$sQRIUDS?q7oU?m0-YHHUNm z68!zqLGo@hocotxlNveHtnF~_UxJ5N=Fq+uAtFd_!`ZGm@_xi2B3NR zQ;xq{^ALr%2_6A>5OsbU#QjUKm-ivEcpSw2OYrh!-0vue`)K$6y=iFO5%UxIH=EhO`3U+!Omqjwk5 zy?VafzXUIMT}a-hzTCeA8&y9-7kc}0{}SBvPa*Ap=EMCZmEoaV3drO10G_W5?~5&<^y~e3 zzB0TavVhuAf1a-ltEUx^=B69ZSB9%67La2DH=eHyM^7!FfgxI+uMFSxE1>w}t~_5E z-rui)vfI1zd}Y|DZ2@iH=EC!p;Q>_&$mF>*&sT=sf8^7LWM`hQ3>SaQr|a&{JYN~! z{yLvhyEyZFWw^?%eERMruMx{_xMFrbl;4NxOPmwWSH^y;8;2>;*NNvV!zJ?f{aUmW&sT=0 zM;)e5|2pw}WjIHDm~8ty@qA^t+1EUJ_KkSHGW_>m9&M=M#Qkfq`SU!o3~}QAHF%A5 z#ZV{iUxV*m$)nLfiTl^!M>%=qx`4QU4fb7|NBag4_piYZX6Dgc8{+;o_-pSxYHdy2 zzXq3<=TgW=!ToFS;Nn~|KQ6d`jURt1m-_4#+`k5AtJmUW9S| z^*`H^$}F7gFZk928#-qn&h;0pdEAlujt}Sh3l2VSO+8kJbNvO!?Y5-Y5#d~a!P_^O z)A1|eTz|py1KX3IH0m#SYg}8J`7oU8FW9b5YpN)(-=Y43FGaSXOKl^#{(^V3Xhy~_ z!@2%~^BXmxGbRySf5FRJH6q(85nO-4cbhh#{7MmAf5D#5O(|aPzah8bgJM{xc1Ki43=ygr8d>wm7sM*RgR-L6XE zT_U*tf<5$AXyV`quD{r;E78P75nO-4NB^xr?!ggUf5C=Je?;}b2(G{2Lx+Bfx4scv zf5E-ad=*pV_1(vE8`fr*h|cnQAnGqTXYogoFR!nn{(|e&c_$vp>z$~-{^!@?QD!*T zU$F6l=VIM|;aq>gss)e5Olj0#aFeKq;)LnKbGz z*olsbZok91{(^HHkBHIo`f-V}|Jkv8;U`_Hc(cr_@5}f5MRDnoT+vxxzx}G1dgX{S z^7r?f;u#?Rm*0eO{RLb0S}m&I3*-8WkKeyiG+Z6V^%uON-*T~JWEj_9u;ZDf;?C<( zuD{?4gVTlevrw+T*hOi=dQ&LZU;pzGVXX?~Jhq`c+}g^Cw6W2g$HHcP1%*zD<~)`? z%aKC6M{^zv|IY450Z!4J$HHy%?a9P3n)BHIxi@>E+y_5D+mlw-iRL_(?b?G@7DaI$ z`#;;!%0*F}$Fh^VveW+W@yVUp2F2@-sVQ=36s7-v?nIHMQM6R?y+s{pY_BNJWAS`< zgca?qAH{hrJhrC={k|H>c`WQ*!;BXGjO09)eXboFc`V%HTpKbz70G!l{P{>LntmaY z^H_LqYzrE9ERyqB_?2Tb+Iu~c^H_GpCT!%f@SQ6Ssp9!aTCcd>?E3WNZ6xQh*gwh1 zlrEf%zULdGn**RW8sPg)v4Glit||bkgpMK ztro?3EW2qHHu6~bWv@!qqi+=FvGA`N6=->#D9&Ty>_xxD-^E4gopKv~ zAbU@{l}B^$$2b%fBb8)qk9zRvGC5cXChi1#d$2e^=q*(wU6RF7B(4m zU+k|K#d$3I{cSehe#JEBit#W_a`ahff?UrP1>E zEpi(USyw{SLcKYUhHck>rctxJ`TfJ&Q$Epx3Euqv;axr-$=Si1-#^^P=L1!)>&@>U zPHg&~{t9n?|8VuMZ)v{0H@|(3`&x!AZl;P*hcK{yqdZwmnUwt-bmC z5Ul=llD;^3^Yu=GXy2t z@qAQxKc03;yZai?N@QbtK`Ka*Q-!sMbk#;;E72X~YBhozO znx!~a{>ycV5wmRVcs?qeKQKmIxY&*7qrzKO$B3KSZag0q9@b^HxOk>3&qsxu&W#mW zle+SJR5(GdpZ}(7SDudwXY8LNypMF@`Ka)aPjke-E?sy&D*XDLym!%q&O9F#?rt0> z2Fr7TsoaM3!EqwfwKLC0g_q~YiGIeNc|I!qsa3r2&$s3IsPMqdc=3IPEzd`Vw|15H z0&}$G`KWMyVuHLkkuA?hg_Dmbh|TBJJRcR#t(Pe3Y*F)kRQT`kM6oAH&Fe?Nq0gm* z)VzKKd?GYSJa$v_`VsJ!%SmER4>hkJ0S|wWBvg&mynY1Syd+7C|6xO|`vM6`VrWFr$w@uc)*6&kAP#`<-OLjZFv0%IL{?nl(C5z=RYEc(B+;q@cnQwhn!Nba{$j-Qi~EUwA@ zYQ?=`l10Ef8(u#G$Cr#w7GvJp@cI#OKvc5m{LO~fkAUxwNER1ssCoSexUPJCh4t0E zegs@@lPqGIsd@bf*rj8#IIU9i`VsJM^JKBaM$PL-z&olXi$9&zynX~c`Tbncv#pxf zkAR0fm@7K8R`dE1aOm#2;+1^9K5`pwJ8rHpvrzN;5wNADygt=Y&Fe?Njwh4E+-_=K zKLS1xmL%MSnjGXd+~S`k;pC_$N5#D_CW^GaYFXFv6#F!4UOxgJGA~icw3FA5 zfNP6HVJ-JNDUbhFJyA@Mk9SsFRGJ{F_EYov5jei;`vh^Jmzvj)fIpffikR+dUOxhk zbx9Oo<>%q1Jl;4nQEahN^ZF6k|E6k^INL$Z>qo%%Pb7*_mTDTP9Pj)gLA;Qk&mhG; zt0ago^79$2*i80gUY3t{SNw8Zym-?^&Fe?t`KtTH3w>8LuO9(d85}QslF8D7cUz2RP*`~IKF{#yyzg`&oE{G_|EYnRjuarBd}k!CSJ^!|G(bK{ucHL z!mf>)*N?#d+-iy9a7#6>9|6ZalYj3fYR+@vZ~K!(_v&iy*MX-e%@zO1-$#GB4KJ6! z|9xw#xnBp)37IEa)KPQ44!pkOd@-uBnu6puy!h*UF~7`)`*q;>%L_z1IX;9a`}5DH zh>bsOxL*hR|9g@u;=kH(zYg5~)Iwn*|Gq{l$6x5TNDTU9!~HtgU$$|PSS%c!Q zt`$>!Y`9+so|Lg(v~Fg@{W>rm-XK~%>cssz@Z|%W#FmYnxL*ezP;ZNPHKP;v>%f7} zwuw^{J8{1bJZ8d95iLDcZo`gMvc>huow#2I9zJuAunzCU{W@^nn)}3{?wz<_2cDe1 zUtI6liTicnu$l+O5%W&muLBR8mm{*ebmD#;*#B{kNNU-M`*q;{Z*xS)2OTL^Zo@}T z=ZMNF9l2iz?zbaHxb^AC{W|cPl{}HM&zkE)_}!8`Q8vq(>qB@s z9Ts(bthqjfUmrd!iu+r0eF%HXdznR%HP?r*Rc5|8*UFmvb>QdS3xuy+uWFIphR-}I z5Iu{mxITn0Z7mdSa;&&MggxdQ5kpp3ala017<5!r8f8VO58=$BqoPAEE3OaW-qntY zb@i;cK7>c>kI8;)OUh7=|GWB_2tQ#-%M@>VeoX9JVoA#t=T1E?zRj}a`Vf!b+Vq4- z8fVG zCHL#VjeDLFB`%g+AHogCoD$J?mRujgZii2aWj!ppK7?2OI3*m+ExA5~1M8d?+oU(i zZ9e{|ytkpPCD%vrnBr3+yM-m!NARHYr-Wq{ORkULlfC5qS1Ma_eFO)n&xjk1EV({{ z>lvRFKBksjAHj_mofTU@T5x>?8~r*f+80@HeFV1-Jtqbpu;BU#Uccv@IJez`>mz>r zl5@g$y#?1taANQ|k(FY>^$|Qh^PG4!$%5-6IKbq*@Qt$I`Uv)r_gksuYr*wG6X}p~ zAvC9>mg@!han)cNVWs7I0sb#CkRCSFa=ierEb=EC>C{@hPbL)&S&UVz_h_9d0M zmg@z0>>F=#mh;QdzXBhv=S4M0%k=`hslF#2@2ll{0ald{CG!DVt{31bhutZBn3n4W zxOmzi3fF15UVuOP4j|1?E!PWhk)s<47cJKd@Vj7Fx+#xG{|Y>Do-^&&YPnv3N1q|m zxN12+h5vlf&`x(P=cn+nK8|!*`lj557v}e)-kw^{PvMpA`qHB)E$653ph@!n01LI8 zpTgtz_oA;$w49&9TU+;}#?r`7;qavHRFbac{1k5btQ)=Espb3>zU=Z44gw49&9_HR1U$K_hiPhr#O4zw^+%lRq%P>v-F zS8F*xg~MmdzlD`r&QIaAGIJ`EulKp!hL>+JBj0!}=cn+Pe(kBjcrE9raK2m%Xn(kt z^HVrxXj@t|R?GP*T=KLvIm!8m$WQt4|F)v%^6}_jfq%!hB(n)x?q7i`Xj)L5d_4MB z;I5UMQ+}A1^HVtWc2mmq(Q`t-4qmh)5ieuet9@0%;rvP=t1}bL;$Xz8?H-v=JpAbK?FL zI3mV~YDGA4{|fvf(TKjOoVb4lUOCT*HhduNUxAy+pZ9bfasLXu*rFQU&=U8rz_Zh< zQQmvO{VVYD@@mv~i{Snh*v!2;&6+5OL^*mhV=+PhxE{VQ;OW=-lmMZ^6oaLYEe$S+C5 z{VVXS1-0nFY7O_Vz!RR5QqoqlWue;1@;4bg`a>`&ZzgZna5crQ!Y+ zc=Y1hG@zx1`&Zx=pKH^>zmD9$0$&_rLXTcLa{mgvJ=cV?zBqFK3T$FihdTUpvBi#U%~#AwRI`5j)wbJ`1tpANmXCN{VQ;9 zt9sP6)RFsF;2Ht-DEN#c_piVelIqdow~pMu0@vSAj|%H*xPJw9yjqXuH`H+d3S3;n zlzvv#aQ_Ny+R>C^emipi3S89Il)lT?i}}5k>`8BFKgDJCi3-Tz6Tt;#)JkPcjWmV@WwE?T9P#8 t_rezjnovfOBhUAMe|nlwwTq5C-vb`D%7k`2apd_P@U7u>h(0^g{{!c4lbiqm literal 0 HcmV?d00001 diff --git a/data/libmv-ba-problems/problem_02.bin b/data/libmv-ba-problems/problem_02.bin new file mode 100644 index 0000000000000000000000000000000000000000..21bfade8acab68c408b00a2858033f2d6db0c97d GIT binary patch literal 291550 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

T|qL<6E~i!)bYSIo>Bb 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∋MRFWiou=`-srIXjaM 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 1.0 + +.. member:: int GradientProblemSolver::Options::max_num_iterations + + Default: ``50`` + + Maximum number of iterations for which the solver should run. + +.. member:: double GradientProblemSolver::Options::max_solver_time_in_seconds + + Default: ``1e6`` + Maximum amount of time for which the solver should run. + +.. member:: double GradientProblemSolver::Options::function_tolerance + + Default: ``1e-6`` + + Solver terminates if + + .. math:: \frac{|\Delta \text{cost}|}{\text{cost}} \leq \text{function_tolerance} + + where, :math:`\Delta \text{cost}` is the change in objective + function value (up or down) in the current iteration of the line search. + +.. member:: double GradientProblemSolver::Options::gradient_tolerance + + Default: ``1e-10`` + + Solver terminates if + + .. math:: \|x - \Pi \boxplus(x, -g(x))\|_\infty \leq \text{gradient_tolerance} + + where :math:`\|\cdot\|_\infty` refers to the max norm, :math:`\Pi` + is projection onto the bounds constraints and :math:`\boxplus` is + Plus operation for the overall local parameterization associated + with the parameter vector. + +.. member:: double GradientProblemSolver::Options::parameter_tolerance + + Default: ``1e-8`` + + Solver terminates if + + .. math:: \|\Delta x\| \leq (\|x\| + \text{parameter_tolerance}) * \text{parameter_tolerance} + + where :math:`\Delta x` is the step computed by the linear solver in + the current iteration of the line search. + +.. member:: LoggingType GradientProblemSolver::Options::logging_type + + Default: ``PER_MINIMIZER_ITERATION`` + +.. member:: bool GradientProblemSolver::Options::minimizer_progress_to_stdout + + Default: ``false`` + + By default the :class:`Minimizer` progress is logged to ``STDERR`` + depending on the ``vlog`` level. If this flag is set to true, and + :member:`GradientProblemSolver::Options::logging_type` is not + ``SILENT``, the logging output is sent to ``STDOUT``. + + The progress display looks like + + .. code-block:: bash + + 0: f: 2.317806e+05 d: 0.00e+00 g: 3.19e-01 h: 0.00e+00 s: 0.00e+00 e: 0 it: 2.98e-02 tt: 8.50e-02 + 1: f: 2.312019e+05 d: 5.79e+02 g: 3.18e-01 h: 2.41e+01 s: 1.00e+00 e: 1 it: 4.54e-02 tt: 1.31e-01 + 2: f: 2.300462e+05 d: 1.16e+03 g: 3.17e-01 h: 4.90e+01 s: 2.54e-03 e: 1 it: 4.96e-02 tt: 1.81e-01 + + Here + + #. ``f`` is the value of the objective function. + #. ``d`` is the change in the value of the objective function if + the step computed in this iteration is accepted. + #. ``g`` is the max norm of the gradient. + #. ``h`` is the change in the parameter vector. + #. ``s`` is the optimal step length computed by the line search. + #. ``it`` is the time take by the current iteration. + #. ``tt`` is the total time taken by the minimizer. + +.. member:: vector GradientProblemSolver::Options::callbacks + + Callbacks that are executed at the end of each iteration of the + :class:`Minimizer`. They are executed in the order that they are + specified in this vector. See the documentation for + :class:`IterationCallback` for more details. + + The solver does NOT take ownership of these pointers. + + +:class:`GradientProblemSolver::Summary` +--------------------------------------- + +.. class:: GradientProblemSolver::Summary + + Summary of the various stages of the solver after termination. + +.. function:: string GradientProblemSolver::Summary::BriefReport() const + + A brief one line description of the state of the solver after + termination. + +.. function:: string GradientProblemSolver::Summary::FullReport() const + + A full multiline description of the state of the solver after + termination. + +.. function:: bool GradientProblemSolver::Summary::IsSolutionUsable() const + + Whether the solution returned by the optimization algorithm can be + relied on to be numerically sane. This will be the case if + `GradientProblemSolver::Summary:termination_type` is set to `CONVERGENCE`, + `USER_SUCCESS` or `NO_CONVERGENCE`, i.e., either the solver + converged by meeting one of the convergence tolerances or because + the user indicated that it had converged or it ran to the maximum + number of iterations or time. + +.. member:: TerminationType GradientProblemSolver::Summary::termination_type + + The cause of the minimizer terminating. + +.. member:: string GradientProblemSolver::Summary::message + + Reason why the solver terminated. + +.. member:: double GradientProblemSolver::Summary::initial_cost + + Cost of the problem (value of the objective function) before the + optimization. + +.. member:: double GradientProblemSolver::Summary::final_cost + + Cost of the problem (value of the objective function) after the + optimization. + +.. member:: vector GradientProblemSolver::Summary::iterations + + :class:`IterationSummary` for each minimizer iteration in order. + +.. member:: int num_cost_evaluations + + Number of times the cost (and not the gradient) was evaluated. + +.. member:: int num_gradient_evaluations + + Number of times the gradient (and the cost) were evaluated. + +.. member:: double GradientProblemSolver::Summary::total_time_in_seconds + + Time (in seconds) spent in the solver. + +.. member:: double GradientProblemSolver::Summary::cost_evaluation_time_in_seconds + + Time (in seconds) spent evaluating the cost vector. + +.. member:: double GradientProblemSolver::Summary::gradient_evaluation_time_in_seconds + + Time (in seconds) spent evaluating the gradient vector. + +.. member:: int GradientProblemSolver::Summary::num_parameters + + Number of parameters in the problem. + +.. member:: int GradientProblemSolver::Summary::num_local_parameters + + Dimension of the tangent space of the problem. This is different + from :member:`GradientProblemSolver::Summary::num_parameters` if a + :class:`LocalParameterization` object is used. + +.. member:: LineSearchDirectionType GradientProblemSolver::Summary::line_search_direction_type + + Type of line search direction used. + +.. member:: LineSearchType GradientProblemSolver::Summary::line_search_type + + Type of the line search algorithm used. + +.. member:: LineSearchInterpolationType GradientProblemSolver::Summary::line_search_interpolation_type + + When performing line search, the degree of the polynomial used to + approximate the objective function. + +.. member:: NonlinearConjugateGradientType GradientProblemSolver::Summary::nonlinear_conjugate_gradient_type + + If the line search direction is `NONLINEAR_CONJUGATE_GRADIENT`, + then this indicates the particular variant of non-linear conjugate + gradient used. + +.. member:: int GradientProblemSolver::Summary::max_lbfgs_rank + + If the type of the line search direction is `LBFGS`, then this + indicates the rank of the Hessian approximation. diff --git a/docs/source/gradient_tutorial.rst b/docs/source/gradient_tutorial.rst new file mode 100644 index 0000000..0bbdee4 --- /dev/null +++ b/docs/source/gradient_tutorial.rst @@ -0,0 +1,138 @@ +.. highlight:: c++ + +.. default-domain:: cpp + +.. _chapter-gradient_tutorial: + +================================== +General Unconstrained Minimization +================================== + +While much of Ceres Solver is devoted to solving non-linear least +squares problems, internally it contains a solver that can solve +general unconstrained optimization problems using just their objective +function value and gradients. The ``GradientProblem`` and +``GradientProblemSolver`` objects give the user access to this solver. + +So without much further ado, let us look at how one goes about using +them. + +Rosenbrock's Function +===================== + +We consider the minimization of the famous `Rosenbrock's function +`_ [#f1]_. + +We begin by defining an instance of the ``FirstOrderFunction`` +interface. This is the object that is responsible for computing the +objective function value and the gradient (if required). This is the +analog of the :class:`CostFunction` when defining non-linear least +squares problems in Ceres. + +.. code:: + + class Rosenbrock : public ceres::FirstOrderFunction { + public: + virtual bool Evaluate(const double* parameters, + double* cost, + double* gradient) const { + const double x = parameters[0]; + const double y = parameters[1]; + + cost[0] = (1.0 - x) * (1.0 - x) + 100.0 * (y - x * x) * (y - x * x); + if (gradient != NULL) { + gradient[0] = -2.0 * (1.0 - x) - 200.0 * (y - x * x) * 2.0 * x; + gradient[1] = 200.0 * (y - x * x); + } + return true; + } + + virtual int NumParameters() const { return 2; } + }; + + +Minimizing it then is a straightforward matter of constructing a +:class:`GradientProblem` object and calling :func:`Solve` on it. + +.. code:: + + double parameters[2] = {-1.2, 1.0}; + + ceres::GradientProblem problem(new Rosenbrock()); + + ceres::GradientProblemSolver::Options options; + options.minimizer_progress_to_stdout = true; + ceres::GradientProblemSolver::Summary summary; + ceres::Solve(options, problem, parameters, &summary); + + std::cout << summary.FullReport() << "\n"; + +Executing this code results, solve the problem using limited memory +`BFGS +`_ +algorithm. + +.. code-block:: bash + + 0: f: 2.420000e+01 d: 0.00e+00 g: 2.16e+02 h: 0.00e+00 s: 0.00e+00 e: 0 it: 2.00e-05 tt: 2.00e-05 + 1: f: 4.280493e+00 d: 1.99e+01 g: 1.52e+01 h: 2.01e-01 s: 8.62e-04 e: 2 it: 7.32e-05 tt: 2.19e-04 + 2: f: 3.571154e+00 d: 7.09e-01 g: 1.35e+01 h: 3.78e-01 s: 1.34e-01 e: 3 it: 2.50e-05 tt: 2.68e-04 + 3: f: 3.440869e+00 d: 1.30e-01 g: 1.73e+01 h: 1.36e-01 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 2.92e-04 + 4: f: 3.213597e+00 d: 2.27e-01 g: 1.55e+01 h: 1.06e-01 s: 4.59e-01 e: 1 it: 2.86e-06 tt: 3.14e-04 + 5: f: 2.839723e+00 d: 3.74e-01 g: 1.05e+01 h: 1.34e-01 s: 5.24e-01 e: 1 it: 2.86e-06 tt: 3.36e-04 + 6: f: 2.448490e+00 d: 3.91e-01 g: 1.29e+01 h: 3.04e-01 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 3.58e-04 + 7: f: 1.943019e+00 d: 5.05e-01 g: 4.00e+00 h: 8.81e-02 s: 7.43e-01 e: 1 it: 4.05e-06 tt: 3.79e-04 + 8: f: 1.731469e+00 d: 2.12e-01 g: 7.36e+00 h: 1.71e-01 s: 4.60e-01 e: 2 it: 9.06e-06 tt: 4.06e-04 + 9: f: 1.503267e+00 d: 2.28e-01 g: 6.47e+00 h: 8.66e-02 s: 1.00e+00 e: 1 it: 3.81e-06 tt: 4.33e-04 + 10: f: 1.228331e+00 d: 2.75e-01 g: 2.00e+00 h: 7.70e-02 s: 7.90e-01 e: 1 it: 3.81e-06 tt: 4.54e-04 + 11: f: 1.016523e+00 d: 2.12e-01 g: 5.15e+00 h: 1.39e-01 s: 3.76e-01 e: 2 it: 1.00e-05 tt: 4.82e-04 + 12: f: 9.145773e-01 d: 1.02e-01 g: 6.74e+00 h: 7.98e-02 s: 1.00e+00 e: 1 it: 3.10e-06 tt: 5.03e-04 + 13: f: 7.508302e-01 d: 1.64e-01 g: 3.88e+00 h: 5.76e-02 s: 4.93e-01 e: 1 it: 2.86e-06 tt: 5.25e-04 + 14: f: 5.832378e-01 d: 1.68e-01 g: 5.56e+00 h: 1.42e-01 s: 1.00e+00 e: 1 it: 3.81e-06 tt: 5.47e-04 + 15: f: 3.969581e-01 d: 1.86e-01 g: 1.64e+00 h: 1.17e-01 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 5.68e-04 + 16: f: 3.171557e-01 d: 7.98e-02 g: 3.84e+00 h: 1.18e-01 s: 3.97e-01 e: 2 it: 9.06e-06 tt: 5.94e-04 + 17: f: 2.641257e-01 d: 5.30e-02 g: 3.27e+00 h: 6.14e-02 s: 1.00e+00 e: 1 it: 3.10e-06 tt: 6.16e-04 + 18: f: 1.909730e-01 d: 7.32e-02 g: 5.29e-01 h: 8.55e-02 s: 6.82e-01 e: 1 it: 4.05e-06 tt: 6.42e-04 + 19: f: 1.472012e-01 d: 4.38e-02 g: 3.11e+00 h: 1.20e-01 s: 3.47e-01 e: 2 it: 1.00e-05 tt: 6.69e-04 + 20: f: 1.093558e-01 d: 3.78e-02 g: 2.97e+00 h: 8.43e-02 s: 1.00e+00 e: 1 it: 3.81e-06 tt: 6.91e-04 + 21: f: 6.710346e-02 d: 4.23e-02 g: 1.42e+00 h: 9.64e-02 s: 8.85e-01 e: 1 it: 3.81e-06 tt: 7.12e-04 + 22: f: 3.993377e-02 d: 2.72e-02 g: 2.30e+00 h: 1.29e-01 s: 4.63e-01 e: 2 it: 9.06e-06 tt: 7.39e-04 + 23: f: 2.911794e-02 d: 1.08e-02 g: 2.55e+00 h: 6.55e-02 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 7.62e-04 + 24: f: 1.457683e-02 d: 1.45e-02 g: 2.77e-01 h: 6.37e-02 s: 6.14e-01 e: 1 it: 3.81e-06 tt: 7.84e-04 + 25: f: 8.577515e-03 d: 6.00e-03 g: 2.86e+00 h: 1.40e-01 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 8.05e-04 + 26: f: 3.486574e-03 d: 5.09e-03 g: 1.76e-01 h: 1.23e-02 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 8.27e-04 + 27: f: 1.257570e-03 d: 2.23e-03 g: 1.39e-01 h: 5.08e-02 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 8.48e-04 + 28: f: 2.783568e-04 d: 9.79e-04 g: 6.20e-01 h: 6.47e-02 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 8.69e-04 + 29: f: 2.533399e-05 d: 2.53e-04 g: 1.68e-02 h: 1.98e-03 s: 1.00e+00 e: 1 it: 3.81e-06 tt: 8.91e-04 + 30: f: 7.591572e-07 d: 2.46e-05 g: 5.40e-03 h: 9.27e-03 s: 1.00e+00 e: 1 it: 3.81e-06 tt: 9.12e-04 + 31: f: 1.902460e-09 d: 7.57e-07 g: 1.62e-03 h: 1.89e-03 s: 1.00e+00 e: 1 it: 2.86e-06 tt: 9.33e-04 + 32: f: 1.003030e-12 d: 1.90e-09 g: 3.50e-05 h: 3.52e-05 s: 1.00e+00 e: 1 it: 3.10e-06 tt: 9.54e-04 + 33: f: 4.835994e-17 d: 1.00e-12 g: 1.05e-07 h: 1.13e-06 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 9.81e-04 + 34: f: 1.885250e-22 d: 4.84e-17 g: 2.69e-10 h: 1.45e-08 s: 1.00e+00 e: 1 it: 4.05e-06 tt: 1.00e-03 + + Solver Summary (v 1.12.0-lapack-suitesparse-cxsparse-no_openmp) + + Parameters 2 + Line search direction LBFGS (20) + Line search type CUBIC WOLFE + + + Cost: + Initial 2.420000e+01 + Final 1.885250e-22 + Change 2.420000e+01 + + Minimizer iterations 35 + + Time (in seconds): + + Cost evaluation 0.000 + Gradient evaluation 0.000 + Total 0.003 + + Termination: CONVERGENCE (Gradient tolerance reached. Gradient max norm: 9.032775e-13 <= 1.000000e-10) + +.. rubric:: Footnotes + +.. [#f1] `examples/rosenbrock.cc + `_ diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d72368f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,67 @@ +============ +Ceres Solver +============ + +Ceres Solver [#f1]_ is an open source C++ library for modeling and +solving large, complicated optimization problems. It can be used to +solve `Non-linear Least Squares`_ problems with bounds constraints and +general unconstrained optimization problems. It is a mature, feature +rich, and performant library that has been used in production at +Google since 2010. For more, see :doc:`features`. + +`ceres-solver@googlegroups.com +`_ is +the place for discussions and questions about Ceres Solver. We use the +`GitHub Issue Tracker +`_ to manage bug +reports and feature requests. + + +.. toctree:: + :maxdepth: 1 + :hidden: + + features + installation + tutorial + derivatives + nnls_modeling + nnls_solving + nnls_covariance + gradient_solver + faqs + users + contributing + version_history + bibliography + license + +.. _Non-linear Least Squares: http://en.wikipedia.org/wiki/Non-linear_least_squares + + +Cite Us +======= + +If you use Ceres Solver for a publication, please cite it as:: + + @misc{ceres-solver, + author = "Sameer Agarwal and Keir Mierle and Others", + title = "Ceres Solver", + howpublished = "\url{http://ceres-solver.org}", + } + + +.. rubric:: Footnotes + +.. [#f1] While there is some debate as to who invented the method of + Least Squares [Stigler]_, there is no questioning the fact + that it was `Carl Friedrich Gauss + `_ + who brought it to the attention of the world. Using just 22 + observations of the newly discovered asteroid `Ceres + `_, Gauss + used the method of least squares to correctly predict when + and where the asteroid will emerge from behind the Sun + [TenenbaumDirector]_. We named our solver after Ceres to + celebrate this seminal event in the history of astronomy, + statistics and optimization. diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..53c557c --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,1052 @@ +.. _chapter-installation: + +============ +Installation +============ + +Getting the source code +======================= +.. _section-source: + +You can start with the `latest stable release +`_ . Or if you want +the latest version, you can clone the git repository + +.. code-block:: bash + + git clone https://ceres-solver.googlesource.com/ceres-solver + +.. _section-dependencies: + +Dependencies +============ + +Ceres relies on a number of open source libraries, some of which are +optional. For details on customizing the build process, see +:ref:`section-customizing` . + +- `Eigen `_ + 3.2.2 or later **strongly** recommended, 3.1.0 or later **required**. + + .. NOTE :: + + Ceres can also use Eigen as a sparse linear algebra + library. Please see the documentation for ``EIGENSPARSE`` for + more details. + +- `CMake `_ 2.8.0 or later. + **Required on all platforms except for Android.** + +- `glog `_ 0.3.1 or + later. **Recommended** + + ``glog`` is used extensively throughout Ceres for logging detailed + information about memory allocations and time consumed in various + parts of the solve, internal error conditions etc. The Ceres + developers use it extensively to observe and analyze Ceres's + performance. `glog `_ allows you to + control its behaviour from the command line. Starting with + ``-logtostderr`` you can add ``-v=N`` for increasing values of ``N`` + to get more and more verbose and detailed information about Ceres + internals. + + Unfortunately, the current version of `google-glog + `_ does not build using the Android + NDK. So, Ceres also ships with a minimal replacement of ``glog`` + called ``miniglog`` that can be enabled with the ``MINIGLOG`` build + option. + + So, in an attempt to reduce dependencies, it is tempting to use + `miniglog` on platforms other than Android. While there is nothing + preventing the user from doing so, we strongly recommend against + it. ``miniglog`` has worse performance than ``glog`` and is much + harder to control and use. + + .. NOTE :: + + If you are compiling ``glog`` from source, please note that + currently, the unit tests for ``glog`` (which are enabled by + default) do not compile against a default build of ``gflags`` 2.1 + as the gflags namespace changed from ``google::`` to + ``gflags::``. A patch to fix this is available from `here + `_. + +- `gflags `_. Needed to build + examples and tests. + +- `SuiteSparse + `_. Needed for + solving large sparse linear systems. **Optional; strongly recomended + for large scale bundle adjustment** + +- `CXSparse `_. + Similar to ``SuiteSparse`` but simpler and slower. CXSparse has + no dependencies on ``LAPACK`` and ``BLAS``. This makes for a simpler + build process and a smaller binary. **Optional** + +- `BLAS `_ and `LAPACK + `_ routines are needed by + ``SuiteSparse``, and optionally used by Ceres directly for some + operations. + + On ``UNIX`` OSes other than Mac OS X we recommend `ATLAS + `_, which includes ``BLAS`` and + ``LAPACK`` routines. It is also possible to use `OpenBLAS + `_ . However, one needs to be + careful to `turn off the threading + `_ + inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. + + Mac OS X ships with an optimized ``LAPACK`` and ``BLAS`` + implementation as part of the ``Accelerate`` framework. The Ceres + build system will automatically detect and use it. + + For Windows things are much more complicated. `LAPACK For + Windows `_ + has detailed instructions.. + + **Optional but required for** ``SuiteSparse``. + +.. _section-linux: + +Linux +===== + +We will use `Ubuntu `_ as our example linux +distribution. + +.. NOTE:: + + Up to at least Ubuntu 14.04, the SuiteSparse package in the official + package repository (built from SuiteSparse v3.4.0) **cannot** be used + to build Ceres as a *shared* library. Thus if you want to build + Ceres as a shared library using SuiteSparse, you must perform a + source install of SuiteSparse or use an external PPA (see `bug report + here + `_). + It is recommended that you use the current version of SuiteSparse + (4.2.1 at the time of writing). + + +Start by installing all the dependencies. + +.. code-block:: bash + + # CMake + sudo apt-get install cmake + # google-glog + gflags + sudo apt-get install libgoogle-glog-dev + # BLAS & LAPACK + sudo apt-get install libatlas-base-dev + # Eigen3 + sudo apt-get install libeigen3-dev + # SuiteSparse and CXSparse (optional) + # - If you want to build Ceres as a *static* library (the default) + # you can use the SuiteSparse package in the main Ubuntu package + # repository: + sudo apt-get install libsuitesparse-dev + # - However, if you want to build Ceres as a *shared* library, you must + # add the following PPA: + sudo add-apt-repository ppa:bzindovic/suitesparse-bugfix-1319687 + sudo apt-get update + sudo apt-get install libsuitesparse-dev + +We are now ready to build, test, and install Ceres. + +.. code-block:: bash + + tar zxf ceres-solver-1.13.0.tar.gz + mkdir ceres-bin + cd ceres-bin + cmake ../ceres-solver-1.13.0 + make -j3 + make test + # Optionally install Ceres, it can also be exported using CMake which + # allows Ceres to be used without requiring installation, see the documentation + # for the EXPORT_BUILD_DIR option for more information. + make install + +You can also try running the command line bundling application with one of the +included problems, which comes from the University of Washington's BAL +dataset [Agarwal]_. + +.. code-block:: bash + + bin/simple_bundle_adjuster ../ceres-solver-1.13.0/data/problem-16-22106-pre.txt + +This runs Ceres for a maximum of 10 iterations using the +``DENSE_SCHUR`` linear solver. The output should look something like +this. + +.. code-block:: bash + + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 7.59e-02 3.37e-01 + 1 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 1 1.65e-01 5.03e-01 + 2 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 1 1.45e-01 6.48e-01 + 3 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 1 1.43e-01 7.92e-01 + 4 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 1 1.45e-01 9.36e-01 + 5 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 1 1.45e-01 1.08e+00 + 6 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 1 1.50e-01 1.23e+00 + + Ceres Solver v1.13.0 Solve Report + ---------------------------------- + Original Reduced + Parameter blocks 22122 22122 + Parameters 66462 66462 + Residual blocks 83718 83718 + Residual 167436 167436 + + Minimizer TRUST_REGION + + Dense linear algebra library EIGEN + Trust region strategy LEVENBERG_MARQUARDT + + Given Used + Linear solver DENSE_SCHUR DENSE_SCHUR + Threads 1 1 + Linear solver threads 1 1 + Linear solver ordering AUTOMATIC 22106, 16 + + Cost: + Initial 4.185660e+06 + Final 1.803390e+04 + Change 4.167626e+06 + + Minimizer iterations 6 + Successful steps 6 + Unsuccessful steps 0 + + Time (in seconds): + Preprocessor 0.261 + + Residual evaluation 0.082 + Jacobian evaluation 0.412 + Linear solver 0.442 + Minimizer 1.051 + + Postprocessor 0.002 + Total 1.357 + + Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769766e-09 <= 1.000000e-06) + +.. section-osx: + +Mac OS X +======== +.. NOTE:: + + Ceres will not compile using Xcode 4.5.x (Clang version 4.1) due to a + bug in that version of Clang. If you are running Xcode 4.5.x, please + update to Xcode >= 4.6.x before attempting to build Ceres. + + +On OS X, you can either use `MacPorts `_ or +`Homebrew `_ to install Ceres Solver. + +If using `MacPorts `_, then + +.. code-block:: bash + + sudo port install ceres-solver + +will install the latest version. + +If using `Homebrew `_ and assuming +that you have the ``homebrew/science`` [#f1]_ tap enabled, then + +.. code-block:: bash + + brew install ceres-solver + +will install the latest stable version along with all the required +dependencies and + +.. code-block:: bash + + brew install ceres-solver --HEAD + +will install the latest version in the git repo. + +You can also install each of the dependencies by hand using `Homebrew +`_. There is no need to install +``BLAS`` or ``LAPACK`` separately as OS X ships with optimized +``BLAS`` and ``LAPACK`` routines as part of the `vecLib +`_ +framework. + +.. code-block:: bash + + # CMake + brew install cmake + # google-glog and gflags + brew install glog + # Eigen3 + brew install eigen + # SuiteSparse and CXSparse + brew install suite-sparse + +We are now ready to build, test, and install Ceres. + +.. code-block:: bash + + tar zxf ceres-solver-1.13.0.tar.gz + mkdir ceres-bin + cd ceres-bin + cmake ../ceres-solver-1.13.0 + make -j3 + make test + # Optionally install Ceres, it can also be exported using CMake which + # allows Ceres to be used without requiring installation, see the + # documentation for the EXPORT_BUILD_DIR option for more information. + make install + +Like the Linux build, you should now be able to run +``bin/simple_bundle_adjuster``. + + +.. rubric:: Footnotes + +.. [#f1] Ceres and many of its dependencies are in `homebrew/science + `_ tap. So, if you + don't have this tap enabled, then you will need to enable it as + follows before executing any of the commands in this section. + + .. code-block:: bash + + brew tap homebrew/science + + +.. _section-windows: + +Windows +======= + +.. NOTE:: + + If you find the following CMake difficult to set up, then you may + be interested in a `Microsoft Visual Studio wrapper + `_ for Ceres Solver by Tal + Ben-Nun. + +On Windows, we support building with Visual Studio 2010 or newer. Note +that the Windows port is less featureful and less tested than the +Linux or Mac OS X versions due to the lack of an officially supported +way of building SuiteSparse and CXSparse. There are however a number +of unofficial ways of building these libraries. Building on Windows +also a bit more involved since there is no automated way to install +dependencies. + +.. NOTE:: Using ``google-glog`` & ``miniglog`` with windows.h. + + The windows.h header if used with GDI (Graphics Device Interface) + defines ``ERROR``, which conflicts with the definition of ``ERROR`` + as a LogSeverity level in ``google-glog`` and ``miniglog``. There + are at least two possible fixes to this problem: + + #. Use ``google-glog`` and define ``GLOG_NO_ABBREVIATED_SEVERITIES`` + when building Ceres and your own project, as documented `here + `__. + Note that this fix will not work for ``miniglog``, but use of + ``miniglog`` is strongly discouraged on any platform for which + ``google-glog`` is available (which includes Windows). + #. If you do not require GDI, then define ``NOGDI`` **before** + including windows.h. This solution should work for both + ``google-glog`` and ``miniglog`` and is documented for + ``google-glog`` `here + `__. + +#. Make a toplevel directory for deps & build & src somewhere: ``ceres/`` +#. Get dependencies; unpack them as subdirectories in ``ceres/`` + (``ceres/eigen``, ``ceres/glog``, etc) + + #. ``Eigen`` 3.1 (needed on Windows; 3.0.x will not work). There is + no need to build anything; just unpack the source tarball. + + #. ``google-glog`` Open up the Visual Studio solution and build it. + #. ``gflags`` Open up the Visual Studio solution and build it. + + #. (Experimental) ``SuiteSparse`` Previously SuiteSparse was not + available on Windows, recently it has become possible to build + it on Windows using the `suitesparse-metis-for-windows + `_ + project. If you wish to use ``SuiteSparse``, follow their + instructions for obtaining and building it. + + #. (Experimental) ``CXSparse`` Previously CXSparse was not + available on Windows, there are now several ports that enable it + to be, including: `[1] `_ + and `[2] `_. If you + wish to use ``CXSparse``, follow their instructions for + obtaining and building it. + +#. Unpack the Ceres tarball into ``ceres``. For the tarball, you + should get a directory inside ``ceres`` similar to + ``ceres-solver-1.3.0``. Alternately, checkout Ceres via ``git`` to + get ``ceres-solver.git`` inside ``ceres``. + +#. Install ``CMake``, + +#. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build) + +#. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or + ``ceres-solver.git`` directory for the CMake file. Then select the + ``ceres-bin`` for the build dir. + +#. Try running ``Configure``. It won't work. It'll show a bunch of options. + You'll need to set: + + #. ``EIGEN_INCLUDE_DIR_HINTS`` + #. ``GLOG_INCLUDE_DIR_HINTS`` + #. ``GLOG_LIBRARY_DIR_HINTS`` + #. ``GFLAGS_INCLUDE_DIR_HINTS`` + #. ``GFLAGS_LIBRARY_DIR_HINTS`` + #. (Optional) ``SUITESPARSE_INCLUDE_DIR_HINTS`` + #. (Optional) ``SUITESPARSE_LIBRARY_DIR_HINTS`` + #. (Optional) ``CXSPARSE_INCLUDE_DIR_HINTS`` + #. (Optional) ``CXSPARSE_LIBRARY_DIR_HINTS`` + + to the appropriate directories where you unpacked/built them. If + any of the variables are not visible in the ``CMake`` GUI, create a + new entry for them. We recommend using the + ``_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than + setting the ``_INCLUDE_DIR`` & ``_LIBRARY`` variables + directly to keep all of the validity checking, and to avoid having + to specify the library files manually. + +#. You may have to tweak some more settings to generate a MSVC + project. After each adjustment, try pressing Configure & Generate + until it generates successfully. + +#. Open the solution and build it in MSVC + + +To run the tests, select the ``RUN_TESTS`` target and hit **Build +RUN_TESTS** from the build menu. + +Like the Linux build, you should now be able to run +``bin/simple_bundle_adjuster``. + +Notes: + +#. The default build is Debug; consider switching it to release mode. +#. Currently ``system_test`` is not working properly. +#. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` + by default. +#. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``, + ``CGNR``, and ``ITERATIVE_SCHUR``. +#. We're looking for someone to work with upstream ``SuiteSparse`` to + port their build system to something sane like ``CMake``, and get a + fully supported Windows port. + + +.. _section-android: + +Android +======= + +Download the ``Android NDK`` version ``r9d`` or later. Run +``ndk-build`` from inside the ``jni`` directory. Use the +``libceres.a`` that gets created. + +.. _section-ios: + +iOS +=== + +.. NOTE:: + + You need iOS version 7.0 or higher to build Ceres Solver. + +To build Ceres for iOS, we need to force ``CMake`` to find the +toolchains from the iOS SDK instead of using the standard ones. For +example: + +.. code-block:: bash + + cmake \ + -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \ + -DEIGEN_INCLUDE_DIR=/path/to/eigen/header \ + -DIOS_PLATFORM= \ + + +``PLATFORM`` can be: ``OS``, ``SIMULATOR`` or ``SIMULATOR64``. You can +build for ``OS`` (``armv7``, ``armv7s``, ``arm64``), ``SIMULATOR`` +(``i386``) or ``SIMULATOR64`` (``x86_64``) separately and use ``lipo`` +to merge them into one static library. See ``cmake/iOS.cmake`` for +more options. + +After building, you will get a ``libceres.a`` library, which you will +need to add to your Xcode project. + +The default CMake configuration builds a bare bones version of Ceres +Solver that only depends on Eigen (``MINIGLOG`` is compiled into Ceres +if it is used), this should be sufficient for solving small to +moderate sized problems (No ``SPARSE_SCHUR``, +``SPARSE_NORMAL_CHOLESKY`` linear solvers and no ``CLUSTER_JACOBI`` +and ``CLUSTER_TRIDIAGONAL`` preconditioners). + +If you decide to use ``LAPACK`` and ``BLAS``, then you also need to +add ``Accelerate.framework`` to your Xcode project's linking +dependency. + +.. _section-customizing: + +Customizing the build +===================== + +It is possible to reduce the libraries needed to build Ceres and +customize the build process by setting the appropriate options in +``CMake``. These options can either be set in the ``CMake`` GUI, or +via ``-D

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 literal 0 HcmV?d00001 diff --git a/docs/source/manhattan_olson_3500_result.png b/docs/source/manhattan_olson_3500_result.png new file mode 100644 index 0000000000000000000000000000000000000000..5631dfa0103b017aebe39f6b2bf6b145ed284d0e GIT binary patch literal 109029 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 N5f_mb&KA;k|1U0Bl*|AC literal 0 HcmV?d00001 diff --git a/docs/source/modeling_faqs.rst b/docs/source/modeling_faqs.rst new file mode 100644 index 0000000..ee4e62c --- /dev/null +++ b/docs/source/modeling_faqs.rst @@ -0,0 +1,134 @@ +.. _chapter-modeling_faqs: + +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +======== +Modeling +======== + +#. Use analytical/automatic derivatives. + + This is the single most important piece of advice we can give to + you. It is tempting to take the easy way out and use numeric + differentiation. This is a bad idea. Numeric differentiation is + slow, ill-behaved, hard to get right, and results in poor + convergence behaviour. + + Ceres allows the user to define templated functors which will + be automatically differentiated. For most situations this is enough + and we recommend using this facility. In some cases the derivatives + are simple enough or the performance considerations are such that + the overhead of automatic differentiation is too much. In such + cases, analytic derivatives are recommended. + + The use of numerical derivatives should be a measure of last + resort, where it is simply not possible to write a templated + implementation of the cost function. + + In many cases it is not possible to do analytic or automatic + differentiation of the entire cost function, but it is generally + the case that it is possible to decompose the cost function into + parts that need to be numerically differentiated and parts that can + be automatically or analytically differentiated. + + To this end, Ceres has extensive support for mixing analytic, + automatic and numeric differentiation. See + :class:`CostFunctionToFunctor`. + +#. When using Quaternions, consider using :class:`QuaternionParameterization`. + + `Quaternions `_ are a + four dimensional parameterization of the space of three dimensional + rotations :math:`SO(3)`. However, the :math:`SO(3)` is a three + dimensional set, and so is the tangent space of a + Quaternion. Therefore, it is sometimes (not always) benefecial to + associate a local parameterization with parameter blocks + representing a Quaternion. Assuming that the order of entries in + your parameter block is :math:`w,x,y,z`, you can use + :class:`QuaternionParameterization`. + + .. NOTE:: + + If you are using `Eigen's Quaternion + `_ + object, whose layout is :math:`x,y,z,w`, then you should use + :class:`EigenQuaternionParameterization`. + + +#. How do I solve problems with general linear & non-linear + **inequality** constraints with Ceres Solver? + + Currently, Ceres Solver only supports upper and lower bounds + constraints on the parameter blocks. + + A crude way of dealing with inequality constraints is have one or + more of your cost functions check if the inequalities you are + interested in are satisfied, and if not return false instead of + true. This will prevent the solver from ever stepping into an + infeasible region. + + This requires that the starting point for the optimization be a + feasible point. You also risk pre-mature convergence using this + method. + +#. How do I solve problems with general linear & non-linear **equality** + constraints with Ceres Solver? + + There is no built in support in ceres for solving problems with + equality constraints. Currently, Ceres Solver only supports upper + and lower bounds constraints on the parameter blocks. + + The trick described above for dealing with inequality + constraints will **not** work for equality constraints. + +#. How do I set one or more components of a parameter block constant? + + Using :class:`SubsetParameterization`. + +#. Putting `Inverse Function Theorem + `_ to use. + + Every now and then we have to deal with functions which cannot be + evaluated analytically. Computing the Jacobian in such cases is + tricky. A particularly interesting case is where the inverse of the + function is easy to compute analytically. An example of such a + function is the Coordinate transformation between the `ECEF + `_ and the `WGS84 + `_ where the + conversion from WGS84 to ECEF is analytic, but the conversion + back to WGS84 uses an iterative algorithm. So how do you compute the + derivative of the ECEF to WGS84 transformation? + + One obvious approach would be to numerically + differentiate the conversion function. This is not a good idea. For + one, it will be slow, but it will also be numerically quite + bad. + + Turns out you can use the `Inverse Function Theorem + `_ in this + case to compute the derivatives more or less analytically. + + The key result here is. If :math:`x = f^{-1}(y)`, and :math:`Df(x)` + is the invertible Jacobian of :math:`f` at :math:`x`. Then the + Jacobian :math:`Df^{-1}(y) = [Df(x)]^{-1}`, i.e., the Jacobian of + the :math:`f^{-1}` is the inverse of the Jacobian of :math:`f`. + + Algorithmically this means that given :math:`y`, compute :math:`x = + f^{-1}(y)` by whatever means you can. Evaluate the Jacobian of + :math:`f` at :math:`x`. If the Jacobian matrix is invertible, then + its inverse is the Jacobian of :math:`f^{-1}(y)` at :math:`y`. + + One can put this into practice with the following code fragment. + + .. code-block:: c++ + + Eigen::Vector3d ecef; // Fill some values + // Iterative computation. + Eigen::Vector3d lla = ECEFToLLA(ecef); + // Analytic derivatives + Eigen::Matrix3d lla_to_ecef_jacobian = LLAToECEFJacobian(lla); + bool invertible; + Eigen::Matrix3d ecef_to_lla_jacobian; + lla_to_ecef_jacobian.computeInverseWithCheck(ecef_to_lla_jacobian, invertible); diff --git a/docs/source/nnls_covariance.rst b/docs/source/nnls_covariance.rst new file mode 100644 index 0000000..60f15a0 --- /dev/null +++ b/docs/source/nnls_covariance.rst @@ -0,0 +1,376 @@ + +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-nnls_covariance: + +===================== +Covariance Estimation +===================== + +Introduction +============ + +One way to assess the quality of the solution returned by a non-linear +least squares solver is to analyze the covariance of the solution. + +Let us consider the non-linear regression problem + +.. math:: y = f(x) + N(0, I) + +i.e., the observation :math:`y` is a random non-linear function of the +independent variable :math:`x` with mean :math:`f(x)` and identity +covariance. Then the maximum likelihood estimate of :math:`x` given +observations :math:`y` is the solution to the non-linear least squares +problem: + +.. math:: x^* = \arg \min_x \|f(x)\|^2 + +And the covariance of :math:`x^*` is given by + +.. math:: C(x^*) = \left(J'(x^*)J(x^*)\right)^{-1} + +Here :math:`J(x^*)` is the Jacobian of :math:`f` at :math:`x^*`. The +above formula assumes that :math:`J(x^*)` has full column rank. + +If :math:`J(x^*)` is rank deficient, then the covariance matrix :math:`C(x^*)` +is also rank deficient and is given by the Moore-Penrose pseudo inverse. + +.. math:: C(x^*) = \left(J'(x^*)J(x^*)\right)^{\dagger} + +Note that in the above, we assumed that the covariance matrix for +:math:`y` was identity. This is an important assumption. If this is +not the case and we have + +.. math:: y = f(x) + N(0, S) + +Where :math:`S` is a positive semi-definite matrix denoting the +covariance of :math:`y`, then the maximum likelihood problem to be +solved is + +.. math:: x^* = \arg \min_x f'(x) S^{-1} f(x) + +and the corresponding covariance estimate of :math:`x^*` is given by + +.. math:: C(x^*) = \left(J'(x^*) S^{-1} J(x^*)\right)^{-1} + +So, if it is the case that the observations being fitted to have a +covariance matrix not equal to identity, then it is the user's +responsibility that the corresponding cost functions are correctly +scaled, e.g. in the above case the cost function for this problem +should evaluate :math:`S^{-1/2} f(x)` instead of just :math:`f(x)`, +where :math:`S^{-1/2}` is the inverse square root of the covariance +matrix :math:`S`. + +Gauge Invariance +================ + +In structure from motion (3D reconstruction) problems, the +reconstruction is ambiguous upto a similarity transform. This is +known as a *Gauge Ambiguity*. Handling Gauges correctly requires the +use of SVD or custom inversion algorithms. For small problems the +user can use the dense algorithm. For more details see the work of +Kanatani & Morris [KanataniMorris]_. + + +:class:`Covariance` +=================== + +:class:`Covariance` allows the user to evaluate the covariance for a +non-linear least squares problem and provides random access to its +blocks. The computation assumes that the cost functions compute +residuals such that their covariance is identity. + +Since the computation of the covariance matrix requires computing the +inverse of a potentially large matrix, this can involve a rather large +amount of time and memory. However, it is usually the case that the +user is only interested in a small part of the covariance +matrix. Quite often just the block diagonal. :class:`Covariance` +allows the user to specify the parts of the covariance matrix that she +is interested in and then uses this information to only compute and +store those parts of the covariance matrix. + +Rank of the Jacobian +==================== + +As we noted above, if the Jacobian is rank deficient, then the inverse +of :math:`J'J` is not defined and instead a pseudo inverse needs to be +computed. + +The rank deficiency in :math:`J` can be *structural* -- columns +which are always known to be zero or *numerical* -- depending on the +exact values in the Jacobian. + +Structural rank deficiency occurs when the problem contains parameter +blocks that are constant. This class correctly handles structural rank +deficiency like that. + +Numerical rank deficiency, where the rank of the matrix cannot be +predicted by its sparsity structure and requires looking at its +numerical values is more complicated. Here again there are two +cases. + + a. The rank deficiency arises from overparameterization. e.g., a + four dimensional quaternion used to parameterize :math:`SO(3)`, + which is a three dimensional manifold. In cases like this, the + user should use an appropriate + :class:`LocalParameterization`. Not only will this lead to better + numerical behaviour of the Solver, it will also expose the rank + deficiency to the :class:`Covariance` object so that it can + handle it correctly. + + b. More general numerical rank deficiency in the Jacobian requires + the computation of the so called Singular Value Decomposition + (SVD) of :math:`J'J`. We do not know how to do this for large + sparse matrices efficiently. For small and moderate sized + problems this is done using dense linear algebra. + + +:class:`Covariance::Options` + +.. class:: Covariance::Options + +.. member:: int Covariance::Options::num_threads + + Default: ``1`` + + Number of threads to be used for evaluating the Jacobian and + estimation of covariance. + +.. member:: SparseLinearAlgebraLibraryType Covariance::Options::sparse_linear_algebra_library_type + + Default: ``SUITE_SPARSE`` Ceres Solver is built with support for + `SuiteSparse `_ + and ``EIGEN_SPARSE`` otherwise. Note that ``EIGEN_SPARSE`` is + always available. + +.. member:: CovarianceAlgorithmType Covariance::Options::algorithm_type + + Default: ``SPARSE_QR`` + + Ceres supports two different algorithms for covariance estimation, + which represent different tradeoffs in speed, accuracy and + reliability. + + 1. ``SPARSE_QR`` uses the sparse QR factorization algorithm to + compute the decomposition + + .. math:: + + QR &= J\\ + \left(J^\top J\right)^{-1} &= \left(R^\top R\right)^{-1} + + The speed of this algorithm depends on the sparse linear algebra + library being used. ``Eigen``'s sparse QR factorization is a + moderately fast algorithm suitable for small to medium sized + matrices. For best performance we recommend using + ``SuiteSparseQR`` which is enabled by setting + :member:`Covaraince::Options::sparse_linear_algebra_library_type` + to ``SUITE_SPARSE``. + + Neither ``SPARSE_QR`` cannot compute the covariance if the + Jacobian is rank deficient. + + + 2. ``DENSE_SVD`` uses ``Eigen``'s ``JacobiSVD`` to perform the + computations. It computes the singular value decomposition + + .. math:: U S V^\top = J + + and then uses it to compute the pseudo inverse of J'J as + + .. math:: (J'J)^{\dagger} = V S^{\dagger} V^\top + + It is an accurate but slow method and should only be used for + small to moderate sized problems. It can handle full-rank as + well as rank deficient Jacobians. + + +.. member:: int Covariance::Options::min_reciprocal_condition_number + + Default: :math:`10^{-14}` + + If the Jacobian matrix is near singular, then inverting :math:`J'J` + will result in unreliable results, e.g, if + + .. math:: + + J = \begin{bmatrix} + 1.0& 1.0 \\ + 1.0& 1.0000001 + \end{bmatrix} + + which is essentially a rank deficient matrix, we have + + .. math:: + + (J'J)^{-1} = \begin{bmatrix} + 2.0471e+14& -2.0471e+14 \\ + -2.0471e+14 2.0471e+14 + \end{bmatrix} + + + This is not a useful result. Therefore, by default + :func:`Covariance::Compute` will return ``false`` if a rank + deficient Jacobian is encountered. How rank deficiency is detected + depends on the algorithm being used. + + 1. ``DENSE_SVD`` + + .. math:: \frac{\sigma_{\text{min}}}{\sigma_{\text{max}}} < \sqrt{\text{min_reciprocal_condition_number}} + + where :math:`\sigma_{\text{min}}` and + :math:`\sigma_{\text{max}}` are the minimum and maxiumum + singular values of :math:`J` respectively. + + 2. ``SPARSE_QR`` + + .. math:: \operatorname{rank}(J) < \operatorname{num\_col}(J) + + Here :math:`\operatorname{rank}(J)` is the estimate of the rank + of :math:`J` returned by the sparse QR factorization + algorithm. It is a fairly reliable indication of rank + deficiency. + +.. member:: int Covariance::Options::null_space_rank + + When using ``DENSE_SVD``, the user has more control in dealing + with singular and near singular covariance matrices. + + As mentioned above, when the covariance matrix is near singular, + instead of computing the inverse of :math:`J'J`, the Moore-Penrose + pseudoinverse of :math:`J'J` should be computed. + + If :math:`J'J` has the eigen decomposition :math:`(\lambda_i, + e_i)`, where :math:`\lambda_i` is the :math:`i^\textrm{th}` + eigenvalue and :math:`e_i` is the corresponding eigenvector, then + the inverse of :math:`J'J` is + + .. math:: (J'J)^{-1} = \sum_i \frac{1}{\lambda_i} e_i e_i' + + and computing the pseudo inverse involves dropping terms from this + sum that correspond to small eigenvalues. + + How terms are dropped is controlled by + `min_reciprocal_condition_number` and `null_space_rank`. + + If `null_space_rank` is non-negative, then the smallest + `null_space_rank` eigenvalue/eigenvectors are dropped irrespective + of the magnitude of :math:`\lambda_i`. If the ratio of the + smallest non-zero eigenvalue to the largest eigenvalue in the + truncated matrix is still below min_reciprocal_condition_number, + then the `Covariance::Compute()` will fail and return `false`. + + Setting `null_space_rank = -1` drops all terms for which + + .. math:: \frac{\lambda_i}{\lambda_{\textrm{max}}} < \textrm{min_reciprocal_condition_number} + + This option has no effect on ``SPARSE_QR``. + +.. member:: bool Covariance::Options::apply_loss_function + + Default: `true` + + Even though the residual blocks in the problem may contain loss + functions, setting ``apply_loss_function`` to false will turn off + the application of the loss function to the output of the cost + function and in turn its effect on the covariance. + +.. class:: Covariance + + :class:`Covariance::Options` as the name implies is used to control + the covariance estimation algorithm. Covariance estimation is a + complicated and numerically sensitive procedure. Please read the + entire documentation for :class:`Covariance::Options` before using + :class:`Covariance`. + +.. function:: bool Covariance::Compute(const vector >& covariance_blocks, Problem* problem) + + Compute a part of the covariance matrix. + + The vector ``covariance_blocks``, indexes into the covariance + matrix block-wise using pairs of parameter blocks. This allows the + covariance estimation algorithm to only compute and store these + blocks. + + Since the covariance matrix is symmetric, if the user passes + ````, then ``GetCovarianceBlock`` can be called with + ``block1``, ``block2`` as well as ``block2``, ``block1``. + + ``covariance_blocks`` cannot contain duplicates. Bad things will + happen if they do. + + Note that the list of ``covariance_blocks`` is only used to + determine what parts of the covariance matrix are computed. The + full Jacobian is used to do the computation, i.e. they do not have + an impact on what part of the Jacobian is used for computation. + + The return value indicates the success or failure of the covariance + computation. Please see the documentation for + :class:`Covariance::Options` for more on the conditions under which + this function returns ``false``. + +.. function:: bool GetCovarianceBlock(const double* parameter_block1, const double* parameter_block2, double* covariance_block) const + + Return the block of the cross-covariance matrix corresponding to + ``parameter_block1`` and ``parameter_block2``. + + Compute must be called before the first call to ``GetCovarianceBlock`` + and the pair ```` OR the pair + ```` must have been present in the + vector covariance_blocks when ``Compute`` was called. Otherwise + ``GetCovarianceBlock`` will return false. + + ``covariance_block`` must point to a memory location that can store + a ``parameter_block1_size x parameter_block2_size`` matrix. The + returned covariance will be a row-major matrix. + +.. function:: bool GetCovarianceBlockInTangentSpace(const double* parameter_block1, const double* parameter_block2, double* covariance_block) const + + Return the block of the cross-covariance matrix corresponding to + ``parameter_block1`` and ``parameter_block2``. + Returns cross-covariance in the tangent space if a local + parameterization is associated with either parameter block; + else returns cross-covariance in the ambient space. + + Compute must be called before the first call to ``GetCovarianceBlock`` + and the pair ```` OR the pair + ```` must have been present in the + vector covariance_blocks when ``Compute`` was called. Otherwise + ``GetCovarianceBlock`` will return false. + + ``covariance_block`` must point to a memory location that can store + a ``parameter_block1_local_size x parameter_block2_local_size`` matrix. The + returned covariance will be a row-major matrix. + +Example Usage +============= + +.. code-block:: c++ + + double x[3]; + double y[2]; + + Problem problem; + problem.AddParameterBlock(x, 3); + problem.AddParameterBlock(y, 2); + + + + Covariance::Options options; + Covariance covariance(options); + + vector > covariance_blocks; + covariance_blocks.push_back(make_pair(x, x)); + covariance_blocks.push_back(make_pair(y, y)); + covariance_blocks.push_back(make_pair(x, y)); + + CHECK(covariance.Compute(covariance_blocks, &problem)); + + double covariance_xx[3 * 3]; + double covariance_yy[2 * 2]; + double covariance_xy[3 * 2]; + covariance.GetCovarianceBlock(x, x, covariance_xx) + covariance.GetCovarianceBlock(y, y, covariance_yy) + covariance.GetCovarianceBlock(x, y, covariance_xy) diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst new file mode 100644 index 0000000..abc1ccc --- /dev/null +++ b/docs/source/nnls_modeling.rst @@ -0,0 +1,2041 @@ +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _`chapter-nnls_modeling`: + +================================= +Modeling Non-linear Least Squares +================================= + +Introduction +============ + +Ceres solver consists of two distinct parts. A modeling API which +provides a rich set of tools to construct an optimization problem one +term at a time and a solver API that controls the minimization +algorithm. This chapter is devoted to the task of modeling +optimization problems using Ceres. :ref:`chapter-nnls_solving` discusses +the various ways in which an optimization problem can be solved using +Ceres. + +Ceres solves robustified bounds constrained non-linear least squares +problems of the form: + +.. math:: :label: ceresproblem + + \min_{\mathbf{x}} &\quad \frac{1}{2}\sum_{i} + \rho_i\left(\left\|f_i\left(x_{i_1}, + ... ,x_{i_k}\right)\right\|^2\right) \\ + \text{s.t.} &\quad l_j \le x_j \le u_j + +In Ceres parlance, the expression +:math:`\rho_i\left(\left\|f_i\left(x_{i_1},...,x_{i_k}\right)\right\|^2\right)` +is known as a **residual block**, where :math:`f_i(\cdot)` is a +:class:`CostFunction` that depends on the **parameter blocks** +:math:`\left\{x_{i_1},... , x_{i_k}\right\}`. + +In most optimization problems small groups of scalars occur +together. For example the three components of a translation vector and +the four components of the quaternion that define the pose of a +camera. We refer to such a group of scalars as a **parameter block**. Of +course a parameter block can be just a single scalar too. + +:math:`\rho_i` is a :class:`LossFunction`. A :class:`LossFunction` is +a scalar valued function that is used to reduce the influence of +outliers on the solution of non-linear least squares problems. + +:math:`l_j` and :math:`u_j` are lower and upper bounds on the +parameter block :math:`x_j`. + +As a special case, when :math:`\rho_i(x) = x`, i.e., the identity +function, and :math:`l_j = -\infty` and :math:`u_j = \infty` we get +the more familiar unconstrained `non-linear least squares problem +`_. + +.. math:: :label: ceresproblemunconstrained + + \frac{1}{2}\sum_{i} \left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2. + +:class:`CostFunction` +===================== + +For each term in the objective function, a :class:`CostFunction` is +responsible for computing a vector of residuals and if asked a vector +of Jacobian matrices, i.e., given :math:`\left[x_{i_1}, ... , +x_{i_k}\right]`, compute the vector +:math:`f_i\left(x_{i_1},...,x_{i_k}\right)` and the matrices + + .. math:: J_{ij} = \frac{\partial}{\partial + x_{i_j}}f_i\left(x_{i_1},...,x_{i_k}\right),\quad \forall j + \in \{1, \ldots, k\} + +.. class:: CostFunction + + .. code-block:: c++ + + class CostFunction { + public: + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) = 0; + const vector& parameter_block_sizes(); + int num_residuals() const; + + protected: + vector* mutable_parameter_block_sizes(); + void set_num_residuals(int num_residuals); + }; + + +The signature of the :class:`CostFunction` (number and sizes of input +parameter blocks and number of outputs) is stored in +:member:`CostFunction::parameter_block_sizes_` and +:member:`CostFunction::num_residuals_` respectively. User code +inheriting from this class is expected to set these two members with +the corresponding accessors. This information will be verified by the +:class:`Problem` when added with :func:`Problem::AddResidualBlock`. + +.. function:: bool CostFunction::Evaluate(double const* const* parameters, double* residuals, double** jacobians) + + Compute the residual vector and the Jacobian matrices. + + ``parameters`` is an array of pointers to arrays containing the + various parameter blocks. ``parameters`` has the same number of + elements as :member:`CostFunction::parameter_block_sizes_` and the + parameter blocks are in the same order as + :member:`CostFunction::parameter_block_sizes_`. + + ``residuals`` is an array of size ``num_residuals_``. + + ``jacobians`` is an array of size + :member:`CostFunction::parameter_block_sizes_` containing pointers + to storage for Jacobian matrices corresponding to each parameter + block. The Jacobian matrices are in the same order as + :member:`CostFunction::parameter_block_sizes_`. ``jacobians[i]`` is + an array that contains :member:`CostFunction::num_residuals_` x + :member:`CostFunction::parameter_block_sizes_` ``[i]`` + elements. Each Jacobian matrix is stored in row-major order, i.e., + ``jacobians[i][r * parameter_block_size_[i] + c]`` = + :math:`\frac{\partial residual[r]}{\partial parameters[i][c]}` + + + If ``jacobians`` is ``NULL``, then no derivatives are returned; + this is the case when computing cost only. If ``jacobians[i]`` is + ``NULL``, then the Jacobian matrix corresponding to the + :math:`i^{\textrm{th}}` parameter block must not be returned, this + is the case when a parameter block is marked constant. + + **NOTE** The return value indicates whether the computation of the + residuals and/or jacobians was successful or not. + + This can be used to communicate numerical failures in Jacobian + computations for instance. + +:class:`SizedCostFunction` +========================== + +.. class:: SizedCostFunction + + If the size of the parameter blocks and the size of the residual + vector is known at compile time (this is the common case), + :class:`SizeCostFunction` can be used where these values can be + specified as template parameters and the user only needs to + implement :func:`CostFunction::Evaluate`. + + .. code-block:: c++ + + template + class SizedCostFunction : public CostFunction { + public: + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const = 0; + }; + + +:class:`AutoDiffCostFunction` +============================= + +.. class:: AutoDiffCostFunction + + Defining a :class:`CostFunction` or a :class:`SizedCostFunction` + can be a tedious and error prone especially when computing + derivatives. To this end Ceres provides `automatic differentiation + `_. + + .. code-block:: c++ + + template // Number of parameters in block 9. + class AutoDiffCostFunction : public + SizedCostFunction { + public: + explicit AutoDiffCostFunction(CostFunctor* functor); + // Ignore the template parameter kNumResiduals and use + // num_residuals instead. + AutoDiffCostFunction(CostFunctor* functor, int num_residuals); + }; + + To get an auto differentiated cost function, you must define a + class with a templated ``operator()`` (a functor) that computes the + cost function in terms of the template parameter ``T``. The + autodiff framework substitutes appropriate ``Jet`` objects for + ``T`` in order to compute the derivative when necessary, but this + is hidden, and you should write the function as if ``T`` were a + scalar type (e.g. a double-precision floating point number). + + The function must write the computed value in the last argument + (the only non-``const`` one) and return true to indicate success. + + For example, consider a scalar error :math:`e = k - x^\top y`, + where both :math:`x` and :math:`y` are two-dimensional vector + parameters and :math:`k` is a constant. The form of this error, + which is the difference between a constant and an expression, is a + common pattern in least squares problems. For example, the value + :math:`x^\top y` might be the model expectation for a series of + measurements, where there is an instance of the cost function for + each measurement :math:`k`. + + The actual cost added to the total problem is :math:`e^2`, or + :math:`(k - x^\top y)^2`; however, the squaring is implicitly done + by the optimization framework. + + To write an auto-differentiable cost function for the above model, + first define the object + + .. code-block:: c++ + + class MyScalarCostFunctor { + MyScalarCostFunctor(double k): k_(k) {} + + template + bool operator()(const T* const x , const T* const y, T* e) const { + e[0] = k_ - x[0] * y[0] - x[1] * y[1]; + return true; + } + + private: + double k_; + }; + + + Note that in the declaration of ``operator()`` the input parameters + ``x`` and ``y`` come first, and are passed as const pointers to arrays + of ``T``. If there were three input parameters, then the third input + parameter would come after ``y``. The output is always the last + parameter, and is also a pointer to an array. In the example above, + ``e`` is a scalar, so only ``e[0]`` is set. + + Then given this class definition, the auto differentiated cost + function for it can be constructed as follows. + + .. code-block:: c++ + + CostFunction* cost_function + = new AutoDiffCostFunction( + new MyScalarCostFunctor(1.0)); ^ ^ ^ + | | | + Dimension of residual ------+ | | + Dimension of x ----------------+ | + Dimension of y -------------------+ + + + In this example, there is usually an instance for each measurement + of ``k``. + + In the instantiation above, the template parameters following + ``MyScalarCostFunction``, ``<1, 2, 2>`` describe the functor as + computing a 1-dimensional output from two arguments, both + 2-dimensional. + + :class:`AutoDiffCostFunction` also supports cost functions with a + runtime-determined number of residuals. For example: + + .. code-block:: c++ + + CostFunction* cost_function + = new AutoDiffCostFunction( + new CostFunctorWithDynamicNumResiduals(1.0), ^ ^ ^ + runtime_number_of_residuals); <----+ | | | + | | | | + | | | | + Actual number of residuals ------+ | | | + Indicate dynamic number of residuals --------+ | | + Dimension of x ------------------------------------+ | + Dimension of y ---------------------------------------+ + + The framework can currently accommodate cost functions of up to 10 + independent variables, and there is no limit on the dimensionality + of each of them. + + **WARNING 1** A common beginner's error when first using + :class:`AutoDiffCostFunction` is to get the sizing wrong. In particular, + there is a tendency to set the template parameters to (dimension of + residual, number of parameters) instead of passing a dimension + parameter for *every parameter block*. In the example above, that + would be ````, which is missing the 2 + as the last template argument. + + +:class:`DynamicAutoDiffCostFunction` +==================================== + +.. class:: DynamicAutoDiffCostFunction + + :class:`AutoDiffCostFunction` requires that the number of parameter + blocks and their sizes be known at compile time. It also has an + upper limit of 10 parameter blocks. In a number of applications, + this is not enough e.g., Bezier curve fitting, Neural Network + training etc. + + .. code-block:: c++ + + template + class DynamicAutoDiffCostFunction : public CostFunction { + }; + + In such cases :class:`DynamicAutoDiffCostFunction` can be + used. Like :class:`AutoDiffCostFunction` the user must define a + templated functor, but the signature of the functor differs + slightly. The expected interface for the cost functors is: + + .. code-block:: c++ + + struct MyCostFunctor { + template + bool operator()(T const* const* parameters, T* residuals) const { + } + } + + Since the sizing of the parameters is done at runtime, you must + also specify the sizes after creating the dynamic autodiff cost + function. For example: + + .. code-block:: c++ + + DynamicAutoDiffCostFunction* cost_function = + new DynamicAutoDiffCostFunction( + new MyCostFunctor()); + cost_function->AddParameterBlock(5); + cost_function->AddParameterBlock(10); + cost_function->SetNumResiduals(21); + + Under the hood, the implementation evaluates the cost function + multiple times, computing a small set of the derivatives (four by + default, controlled by the ``Stride`` template parameter) with each + pass. There is a performance tradeoff with the size of the passes; + Smaller sizes are more cache efficient but result in larger number + of passes, and larger stride lengths can destroy cache-locality + while reducing the number of passes over the cost function. The + optimal value depends on the number and sizes of the various + parameter blocks. + + As a rule of thumb, try using :class:`AutoDiffCostFunction` before + you use :class:`DynamicAutoDiffCostFunction`. + +:class:`NumericDiffCostFunction` +================================ + +.. class:: NumericDiffCostFunction + + In some cases, its not possible to define a templated cost functor, + for example when the evaluation of the residual involves a call to a + library function that you do not have control over. In such a + situation, `numerical differentiation + `_ can be + used. + + .. NOTE :: + + TODO(sameeragarwal): Add documentation for the constructor and for + NumericDiffOptions. Update DynamicNumericDiffOptions in a similar + manner. + + .. code-block:: c++ + + template // Number of parameters in block 9. + class NumericDiffCostFunction : public + SizedCostFunction { + }; + + To get a numerically differentiated :class:`CostFunction`, you must + define a class with a ``operator()`` (a functor) that computes the + residuals. The functor must write the computed value in the last + argument (the only non-``const`` one) and return ``true`` to + indicate success. Please see :class:`CostFunction` for details on + how the return value may be used to impose simple constraints on the + parameter block. e.g., an object of the form + + .. code-block:: c++ + + struct ScalarFunctor { + public: + bool operator()(const double* const x1, + const double* const x2, + double* residuals) const; + } + + For example, consider a scalar error :math:`e = k - x'y`, where both + :math:`x` and :math:`y` are two-dimensional column vector + parameters, the prime sign indicates transposition, and :math:`k` is + a constant. The form of this error, which is the difference between + a constant and an expression, is a common pattern in least squares + problems. For example, the value :math:`x'y` might be the model + expectation for a series of measurements, where there is an instance + of the cost function for each measurement :math:`k`. + + To write an numerically-differentiable class:`CostFunction` for the + above model, first define the object + + .. code-block:: c++ + + class MyScalarCostFunctor { + MyScalarCostFunctor(double k): k_(k) {} + + bool operator()(const double* const x, + const double* const y, + double* residuals) const { + residuals[0] = k_ - x[0] * y[0] + x[1] * y[1]; + return true; + } + + private: + double k_; + }; + + Note that in the declaration of ``operator()`` the input parameters + ``x`` and ``y`` come first, and are passed as const pointers to + arrays of ``double`` s. If there were three input parameters, then + the third input parameter would come after ``y``. The output is + always the last parameter, and is also a pointer to an array. In the + example above, the residual is a scalar, so only ``residuals[0]`` is + set. + + Then given this class definition, the numerically differentiated + :class:`CostFunction` with central differences used for computing + the derivative can be constructed as follows. + + .. code-block:: c++ + + CostFunction* cost_function + = new NumericDiffCostFunction( + new MyScalarCostFunctor(1.0)); ^ ^ ^ ^ + | | | | + Finite Differencing Scheme -+ | | | + Dimension of residual ------------+ | | + Dimension of x ----------------------+ | + Dimension of y -------------------------+ + + In this example, there is usually an instance for each measurement + of `k`. + + In the instantiation above, the template parameters following + ``MyScalarCostFunctor``, ``1, 2, 2``, describe the functor as + computing a 1-dimensional output from two arguments, both + 2-dimensional. + + NumericDiffCostFunction also supports cost functions with a + runtime-determined number of residuals. For example: + + .. code-block:: c++ + + CostFunction* cost_function + = new NumericDiffCostFunction( + new CostFunctorWithDynamicNumResiduals(1.0), ^ ^ ^ + TAKE_OWNERSHIP, | | | + runtime_number_of_residuals); <----+ | | | + | | | | + | | | | + Actual number of residuals ------+ | | | + Indicate dynamic number of residuals --------------------+ | | + Dimension of x ------------------------------------------------+ | + Dimension of y ---------------------------------------------------+ + + + The framework can currently accommodate cost functions of up to 10 + independent variables, and there is no limit on the dimensionality + of each of them. + + There are three available numeric differentiation schemes in ceres-solver: + + The ``FORWARD`` difference method, which approximates :math:`f'(x)` + by computing :math:`\frac{f(x+h)-f(x)}{h}`, computes the cost + function one additional time at :math:`x+h`. It is the fastest but + least accurate method. + + The ``CENTRAL`` difference method is more accurate at the cost of + twice as many function evaluations than forward difference, + estimating :math:`f'(x)` by computing + :math:`\frac{f(x+h)-f(x-h)}{2h}`. + + The ``RIDDERS`` difference method[Ridders]_ is an adaptive scheme + that estimates derivatives by performing multiple central + differences at varying scales. Specifically, the algorithm starts at + a certain :math:`h` and as the derivative is estimated, this step + size decreases. To conserve function evaluations and estimate the + derivative error, the method performs Richardson extrapolations + between the tested step sizes. The algorithm exhibits considerably + higher accuracy, but does so by additional evaluations of the cost + function. + + Consider using ``CENTRAL`` differences to begin with. Based on the + results, either try forward difference to improve performance or + Ridders' method to improve accuracy. + + **WARNING** A common beginner's error when first using + :class:`NumericDiffCostFunction` is to get the sizing wrong. In + particular, there is a tendency to set the template parameters to + (dimension of residual, number of parameters) instead of passing a + dimension parameter for *every parameter*. In the example above, + that would be ````, which is missing the + last ``2`` argument. Please be careful when setting the size + parameters. + + +Numeric Differentiation & LocalParameterization +----------------------------------------------- + + If your cost function depends on a parameter block that must lie on + a manifold and the functor cannot be evaluated for values of that + parameter block not on the manifold then you may have problems + numerically differentiating such functors. + + This is because numeric differentiation in Ceres is performed by + perturbing the individual coordinates of the parameter blocks that + a cost functor depends on. In doing so, we assume that the + parameter blocks live in an Euclidean space and ignore the + structure of manifold that they live As a result some of the + perturbations may not lie on the manifold corresponding to the + parameter block. + + For example consider a four dimensional parameter block that is + interpreted as a unit Quaternion. Perturbing the coordinates of + this parameter block will violate the unit norm property of the + parameter block. + + Fixing this problem requires that :class:`NumericDiffCostFunction` + be aware of the :class:`LocalParameterization` associated with each + parameter block and only generate perturbations in the local + tangent space of each parameter block. + + For now this is not considered to be a serious enough problem to + warrant changing the :class:`NumericDiffCostFunction` API. Further, + in most cases it is relatively straightforward to project a point + off the manifold back onto the manifold before using it in the + functor. For example in case of the Quaternion, normalizing the + 4-vector before using it does the trick. + + **Alternate Interface** + + For a variety of reasons, including compatibility with legacy code, + :class:`NumericDiffCostFunction` can also take + :class:`CostFunction` objects as input. The following describes + how. + + To get a numerically differentiated cost function, define a + subclass of :class:`CostFunction` such that the + :func:`CostFunction::Evaluate` function ignores the ``jacobians`` + parameter. The numeric differentiation wrapper will fill in the + jacobian parameter if necessary by repeatedly calling the + :func:`CostFunction::Evaluate` with small changes to the + appropriate parameters, and computing the slope. For performance, + the numeric differentiation wrapper class is templated on the + concrete cost function, even though it could be implemented only in + terms of the :class:`CostFunction` interface. + + The numerically differentiated version of a cost function for a + cost function can be constructed as follows: + + .. code-block:: c++ + + CostFunction* cost_function + = new NumericDiffCostFunction( + new MyCostFunction(...), TAKE_OWNERSHIP); + + where ``MyCostFunction`` has 1 residual and 2 parameter blocks with + sizes 4 and 8 respectively. Look at the tests for a more detailed + example. + +:class:`DynamicNumericDiffCostFunction` +======================================= + +.. class:: DynamicNumericDiffCostFunction + + Like :class:`AutoDiffCostFunction` :class:`NumericDiffCostFunction` + requires that the number of parameter blocks and their sizes be + known at compile time. It also has an upper limit of 10 parameter + blocks. In a number of applications, this is not enough. + + .. code-block:: c++ + + template + class DynamicNumericDiffCostFunction : public CostFunction { + }; + + In such cases when numeric differentiation is desired, + :class:`DynamicNumericDiffCostFunction` can be used. + + Like :class:`NumericDiffCostFunction` the user must define a + functor, but the signature of the functor differs slightly. The + expected interface for the cost functors is: + + .. code-block:: c++ + + struct MyCostFunctor { + bool operator()(double const* const* parameters, double* residuals) const { + } + } + + Since the sizing of the parameters is done at runtime, you must + also specify the sizes after creating the dynamic numeric diff cost + function. For example: + + .. code-block:: c++ + + DynamicNumericDiffCostFunction* cost_function = + new DynamicNumericDiffCostFunction(new MyCostFunctor); + cost_function->AddParameterBlock(5); + cost_function->AddParameterBlock(10); + cost_function->SetNumResiduals(21); + + As a rule of thumb, try using :class:`NumericDiffCostFunction` before + you use :class:`DynamicNumericDiffCostFunction`. + + **WARNING** The same caution about mixing local parameterizations + with numeric differentiation applies as is the case with + :class:`NumericDiffCostFunction`. + +:class:`CostFunctionToFunctor` +============================== + +.. class:: CostFunctionToFunctor + + :class:`CostFunctionToFunctor` is an adapter class that allows + users to use :class:`CostFunction` objects in templated functors + which are to be used for automatic differentiation. This allows + the user to seamlessly mix analytic, numeric and automatic + differentiation. + + For example, let us assume that + + .. code-block:: c++ + + class IntrinsicProjection : public SizedCostFunction<2, 5, 3> { + public: + IntrinsicProjection(const double* observation); + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + }; + + is a :class:`CostFunction` that implements the projection of a + point in its local coordinate system onto its image plane and + subtracts it from the observed point projection. It can compute its + residual and either via analytic or numerical differentiation can + compute its jacobians. + + Now we would like to compose the action of this + :class:`CostFunction` with the action of camera extrinsics, i.e., + rotation and translation. Say we have a templated function + + .. code-block:: c++ + + template + void RotateAndTranslatePoint(const T* rotation, + const T* translation, + const T* point, + T* result); + + + Then we can now do the following, + + .. code-block:: c++ + + struct CameraProjection { + CameraProjection(double* observation) + : intrinsic_projection_(new IntrinsicProjection(observation)) { + } + + template + bool operator()(const T* rotation, + const T* translation, + const T* intrinsics, + const T* point, + T* residual) const { + T transformed_point[3]; + RotateAndTranslatePoint(rotation, translation, point, transformed_point); + + // Note that we call intrinsic_projection_, just like it was + // any other templated functor. + return intrinsic_projection_(intrinsics, transformed_point, residual); + } + + private: + CostFunctionToFunctor<2,5,3> intrinsic_projection_; + }; + + Note that :class:`CostFunctionToFunctor` takes ownership of the + :class:`CostFunction` that was passed in to the constructor. + + In the above example, we assumed that ``IntrinsicProjection`` is a + ``CostFunction`` capable of evaluating its value and its + derivatives. Suppose, if that were not the case and + ``IntrinsicProjection`` was defined as follows: + + .. code-block:: c++ + + struct IntrinsicProjection + IntrinsicProjection(const double* observation) { + observation_[0] = observation[0]; + observation_[1] = observation[1]; + } + + bool operator()(const double* calibration, + const double* point, + double* residuals) { + double projection[2]; + ThirdPartyProjectionFunction(calibration, point, projection); + residuals[0] = observation_[0] - projection[0]; + residuals[1] = observation_[1] - projection[1]; + return true; + } + double observation_[2]; + }; + + + Here ``ThirdPartyProjectionFunction`` is some third party library + function that we have no control over. So this function can compute + its value and we would like to use numeric differentiation to + compute its derivatives. In this case we can use a combination of + ``NumericDiffCostFunction`` and ``CostFunctionToFunctor`` to get the + job done. + + .. code-block:: c++ + + struct CameraProjection { + CameraProjection(double* observation) + intrinsic_projection_( + new NumericDiffCostFunction( + new IntrinsicProjection(observation)) { + } + + template + bool operator()(const T* rotation, + const T* translation, + const T* intrinsics, + const T* point, + T* residuals) const { + T transformed_point[3]; + RotateAndTranslatePoint(rotation, translation, point, transformed_point); + return intrinsic_projection_(intrinsics, transformed_point, residual); + } + + private: + CostFunctionToFunctor<2,5,3> intrinsic_projection_; + }; + +:class:`DynamicCostFunctionToFunctor` +===================================== + +.. class:: DynamicCostFunctionToFunctor + + :class:`DynamicCostFunctionToFunctor` provides the same functionality as + :class:`CostFunctionToFunctor` for cases where the number and size of the + parameter vectors and residuals are not known at compile-time. The API + provided by :class:`DynamicCostFunctionToFunctor` matches what would be + expected by :class:`DynamicAutoDiffCostFunction`, i.e. it provides a + templated functor of this form: + + .. code-block:: c++ + + template + bool operator()(T const* const* parameters, T* residuals) const; + + Similar to the example given for :class:`CostFunctionToFunctor`, let us + assume that + + .. code-block:: c++ + + class IntrinsicProjection : public CostFunction { + public: + IntrinsicProjection(const double* observation); + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + }; + + is a :class:`CostFunction` that projects a point in its local coordinate + system onto its image plane and subtracts it from the observed point + projection. + + Using this :class:`CostFunction` in a templated functor would then look like + this: + + .. code-block:: c++ + + struct CameraProjection { + CameraProjection(double* observation) + : intrinsic_projection_(new IntrinsicProjection(observation)) { + } + + template + bool operator()(T const* const* parameters, + T* residual) const { + const T* rotation = parameters[0]; + const T* translation = parameters[1]; + const T* intrinsics = parameters[2]; + const T* point = parameters[3]; + + T transformed_point[3]; + RotateAndTranslatePoint(rotation, translation, point, transformed_point); + + const T* projection_parameters[2]; + projection_parameters[0] = intrinsics; + projection_parameters[1] = transformed_point; + return intrinsic_projection_(projection_parameters, residual); + } + + private: + DynamicCostFunctionToFunctor intrinsic_projection_; + }; + + Like :class:`CostFunctionToFunctor`, :class:`DynamicCostFunctionToFunctor` + takes ownership of the :class:`CostFunction` that was passed in to the + constructor. + +:class:`ConditionedCostFunction` +================================ + +.. class:: ConditionedCostFunction + + This class allows you to apply different conditioning to the residual + values of a wrapped cost function. An example where this is useful is + where you have an existing cost function that produces N values, but you + want the total cost to be something other than just the sum of these + squared values - maybe you want to apply a different scaling to some + values, to change their contribution to the cost. + + Usage: + + .. code-block:: c++ + + // my_cost_function produces N residuals + CostFunction* my_cost_function = ... + CHECK_EQ(N, my_cost_function->num_residuals()); + vector conditioners; + + // Make N 1x1 cost functions (1 parameter, 1 residual) + CostFunction* f_1 = ... + conditioners.push_back(f_1); + + CostFunction* f_N = ... + conditioners.push_back(f_N); + ConditionedCostFunction* ccf = + new ConditionedCostFunction(my_cost_function, conditioners); + + + Now ``ccf`` 's ``residual[i]`` (i=0..N-1) will be passed though the + :math:`i^{\text{th}}` conditioner. + + .. code-block:: c++ + + ccf_residual[i] = f_i(my_cost_function_residual[i]) + + and the Jacobian will be affected appropriately. + + +:class:`GradientChecker` +================================ + +.. class:: GradientChecker + + This class compares the Jacobians returned by a cost function against + derivatives estimated using finite differencing. It is meant as a tool for + unit testing, giving you more fine-grained control than the check_gradients + option in the solver options. + + The condition enforced is that + + .. math:: \forall{i,j}: \frac{J_{ij} - J'_{ij}}{max_{ij}(J_{ij} - J'_{ij})} < r + + where :math:`J_{ij}` is the jacobian as computed by the supplied cost + function (by the user) multiplied by the local parameterization Jacobian, + :math:`J'_{ij}` is the jacobian as computed by finite differences, + multiplied by the local parameterization Jacobian as well, and :math:`r` + is the relative precision. + + Usage: + + .. code-block:: c++ + + // my_cost_function takes two parameter blocks. The first has a local + // parameterization associated with it. + CostFunction* my_cost_function = ... + LocalParameterization* my_parameterization = ... + NumericDiffOptions numeric_diff_options; + + std::vector local_parameterizations; + local_parameterizations.push_back(my_parameterization); + local_parameterizations.push_back(NULL); + + std::vector parameter1; + std::vector parameter2; + // Fill parameter 1 & 2 with test data... + + std::vector parameter_blocks; + parameter_blocks.push_back(parameter1.data()); + parameter_blocks.push_back(parameter2.data()); + + GradientChecker gradient_checker(my_cost_function, + local_parameterizations, numeric_diff_options); + GradientCheckResults results; + if (!gradient_checker.Probe(parameter_blocks.data(), 1e-9, &results) { + LOG(ERROR) << "An error has occurred:\n" << results.error_log; + } + + +:class:`NormalPrior` +==================== + +.. class:: NormalPrior + + .. code-block:: c++ + + class NormalPrior: public CostFunction { + public: + // Check that the number of rows in the vector b are the same as the + // number of columns in the matrix A, crash otherwise. + NormalPrior(const Matrix& A, const Vector& b); + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + }; + + Implements a cost function of the form + + .. math:: cost(x) = ||A(x - b)||^2 + + where, the matrix :math:`A` and the vector :math:`b` are fixed and :math:`x` + is the variable. In case the user is interested in implementing a cost + function of the form + + .. math:: cost(x) = (x - \mu)^T S^{-1} (x - \mu) + + where, :math:`\mu` is a vector and :math:`S` is a covariance matrix, + then, :math:`A = S^{-1/2}`, i.e the matrix :math:`A` is the square + root of the inverse of the covariance, also known as the stiffness + matrix. There are however no restrictions on the shape of + :math:`A`. It is free to be rectangular, which would be the case if + the covariance matrix :math:`S` is rank deficient. + + + +.. _`section-loss_function`: + +:class:`LossFunction` +===================== + +.. class:: LossFunction + + For least squares problems where the minimization may encounter + input terms that contain outliers, that is, completely bogus + measurements, it is important to use a loss function that reduces + their influence. + + Consider a structure from motion problem. The unknowns are 3D + points and camera parameters, and the measurements are image + coordinates describing the expected reprojected position for a + point in a camera. For example, we want to model the geometry of a + street scene with fire hydrants and cars, observed by a moving + camera with unknown parameters, and the only 3D points we care + about are the pointy tippy-tops of the fire hydrants. Our magic + image processing algorithm, which is responsible for producing the + measurements that are input to Ceres, has found and matched all + such tippy-tops in all image frames, except that in one of the + frame it mistook a car's headlight for a hydrant. If we didn't do + anything special the residual for the erroneous measurement will + result in the entire solution getting pulled away from the optimum + to reduce the large error that would otherwise be attributed to the + wrong measurement. + + Using a robust loss function, the cost for large residuals is + reduced. In the example above, this leads to outlier terms getting + down-weighted so they do not overly influence the final solution. + + .. code-block:: c++ + + class LossFunction { + public: + virtual void Evaluate(double s, double out[3]) const = 0; + }; + + + The key method is :func:`LossFunction::Evaluate`, which given a + non-negative scalar ``s``, computes + + .. math:: out = \begin{bmatrix}\rho(s), & \rho'(s), & \rho''(s)\end{bmatrix} + + Here the convention is that the contribution of a term to the cost + function is given by :math:`\frac{1}{2}\rho(s)`, where :math:`s + =\|f_i\|^2`. Calling the method with a negative value of :math:`s` + is an error and the implementations are not required to handle that + case. + + Most sane choices of :math:`\rho` satisfy: + + .. math:: + + \rho(0) &= 0\\ + \rho'(0) &= 1\\ + \rho'(s) &< 1 \text{ in the outlier region}\\ + \rho''(s) &< 0 \text{ in the outlier region} + + so that they mimic the squared cost for small residuals. + + **Scaling** + + Given one robustifier :math:`\rho(s)` one can change the length + scale at which robustification takes place, by adding a scale + factor :math:`a > 0` which gives us :math:`\rho(s,a) = a^2 \rho(s / + a^2)` and the first and second derivatives as :math:`\rho'(s / + a^2)` and :math:`(1 / a^2) \rho''(s / a^2)` respectively. + + + The reason for the appearance of squaring is that :math:`a` is in + the units of the residual vector norm whereas :math:`s` is a squared + norm. For applications it is more convenient to specify :math:`a` than + its square. + +Instances +--------- + +Ceres includes a number of predefined loss functions. For simplicity +we described their unscaled versions. The figure below illustrates +their shape graphically. More details can be found in +``include/ceres/loss_function.h``. + +.. figure:: loss.png + :figwidth: 500px + :height: 400px + :align: center + + Shape of the various common loss functions. + +.. class:: TrivialLoss + + .. math:: \rho(s) = s + +.. class:: HuberLoss + + .. math:: \rho(s) = \begin{cases} s & s \le 1\\ 2 \sqrt{s} - 1 & s > 1 \end{cases} + +.. class:: SoftLOneLoss + + .. math:: \rho(s) = 2 (\sqrt{1+s} - 1) + +.. class:: CauchyLoss + + .. math:: \rho(s) = \log(1 + s) + +.. class:: ArctanLoss + + .. math:: \rho(s) = \arctan(s) + +.. class:: TolerantLoss + + .. math:: \rho(s,a,b) = b \log(1 + e^{(s - a) / b}) - b \log(1 + e^{-a / b}) + +.. class:: ComposedLoss + + Given two loss functions ``f`` and ``g``, implements the loss + function ``h(s) = f(g(s))``. + + .. code-block:: c++ + + class ComposedLoss : public LossFunction { + public: + explicit ComposedLoss(const LossFunction* f, + Ownership ownership_f, + const LossFunction* g, + Ownership ownership_g); + }; + +.. class:: ScaledLoss + + Sometimes you want to simply scale the output value of the + robustifier. For example, you might want to weight different error + terms differently (e.g., weight pixel reprojection errors + differently from terrain errors). + + Given a loss function :math:`\rho(s)` and a scalar :math:`a`, :class:`ScaledLoss` + implements the function :math:`a \rho(s)`. + + Since we treat a ``NULL`` Loss function as the Identity loss + function, :math:`rho` = ``NULL``: is a valid input and will result + in the input being scaled by :math:`a`. This provides a simple way + of implementing a scaled ResidualBlock. + +.. class:: LossFunctionWrapper + + Sometimes after the optimization problem has been constructed, we + wish to mutate the scale of the loss function. For example, when + performing estimation from data which has substantial outliers, + convergence can be improved by starting out with a large scale, + optimizing the problem and then reducing the scale. This can have + better convergence behavior than just using a loss function with a + small scale. + + This templated class allows the user to implement a loss function + whose scale can be mutated after an optimization problem has been + constructed, e.g, + + .. code-block:: c++ + + Problem problem; + + // Add parameter blocks + + CostFunction* cost_function = + new AutoDiffCostFunction < UW_Camera_Mapper, 2, 9, 3>( + new UW_Camera_Mapper(feature_x, feature_y)); + + LossFunctionWrapper* loss_function(new HuberLoss(1.0), TAKE_OWNERSHIP); + problem.AddResidualBlock(cost_function, loss_function, parameters); + + Solver::Options options; + Solver::Summary summary; + Solve(options, &problem, &summary); + + loss_function->Reset(new HuberLoss(1.0), TAKE_OWNERSHIP); + Solve(options, &problem, &summary); + + +Theory +------ + +Let us consider a problem with a single problem and a single parameter +block. + +.. math:: + + \min_x \frac{1}{2}\rho(f^2(x)) + + +Then, the robustified gradient and the Gauss-Newton Hessian are + +.. math:: + + g(x) &= \rho'J^\top(x)f(x)\\ + H(x) &= J^\top(x)\left(\rho' + 2 \rho''f(x)f^\top(x)\right)J(x) + +where the terms involving the second derivatives of :math:`f(x)` have +been ignored. Note that :math:`H(x)` is indefinite if +:math:`\rho''f(x)^\top f(x) + \frac{1}{2}\rho' < 0`. If this is not +the case, then its possible to re-weight the residual and the Jacobian +matrix such that the corresponding linear least squares problem for +the robustified Gauss-Newton step. + + +Let :math:`\alpha` be a root of + +.. math:: \frac{1}{2}\alpha^2 - \alpha - \frac{\rho''}{\rho'}\|f(x)\|^2 = 0. + + +Then, define the rescaled residual and Jacobian as + +.. math:: + + \tilde{f}(x) &= \frac{\sqrt{\rho'}}{1 - \alpha} f(x)\\ + \tilde{J}(x) &= \sqrt{\rho'}\left(1 - \alpha + \frac{f(x)f^\top(x)}{\left\|f(x)\right\|^2} \right)J(x) + + +In the case :math:`2 \rho''\left\|f(x)\right\|^2 + \rho' \lesssim 0`, +we limit :math:`\alpha \le 1- \epsilon` for some small +:math:`\epsilon`. For more details see [Triggs]_. + +With this simple rescaling, one can use any Jacobian based non-linear +least squares algorithm to robustified non-linear least squares +problems. + + +:class:`LocalParameterization` +============================== + +.. class:: LocalParameterization + + .. code-block:: c++ + + class LocalParameterization { + public: + virtual ~LocalParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const = 0; + virtual bool ComputeJacobian(const double* x, double* jacobian) const = 0; + virtual bool MultiplyByJacobian(const double* x, + const int num_rows, + const double* global_matrix, + double* local_matrix) const; + virtual int GlobalSize() const = 0; + virtual int LocalSize() const = 0; + }; + + Sometimes the parameters :math:`x` can overparameterize a + problem. In that case it is desirable to choose a parameterization + to remove the null directions of the cost. More generally, if + :math:`x` lies on a manifold of a smaller dimension than the + ambient space that it is embedded in, then it is numerically and + computationally more effective to optimize it using a + parameterization that lives in the tangent space of that manifold + at each point. + + For example, a sphere in three dimensions is a two dimensional + manifold, embedded in a three dimensional space. At each point on + the sphere, the plane tangent to it defines a two dimensional + tangent space. For a cost function defined on this sphere, given a + point :math:`x`, moving in the direction normal to the sphere at + that point is not useful. Thus a better way to parameterize a point + on a sphere is to optimize over two dimensional vector + :math:`\Delta x` in the tangent space at the point on the sphere + point and then "move" to the point :math:`x + \Delta x`, where the + move operation involves projecting back onto the sphere. Doing so + removes a redundant dimension from the optimization, making it + numerically more robust and efficient. + + More generally we can define a function + + .. math:: x' = \boxplus(x, \Delta x), + + where :math:`x'` has the same size as :math:`x`, and :math:`\Delta + x` is of size less than or equal to :math:`x`. The function + :math:`\boxplus`, generalizes the definition of vector + addition. Thus it satisfies the identity + + .. math:: \boxplus(x, 0) = x,\quad \forall x. + + Instances of :class:`LocalParameterization` implement the + :math:`\boxplus` operation and its derivative with respect to + :math:`\Delta x` at :math:`\Delta x = 0`. + + +.. function:: int LocalParameterization::GlobalSize() + + The dimension of the ambient space in which the parameter block + :math:`x` lives. + +.. function:: int LocalParameterization::LocalSize() + + The size of the tangent space + that :math:`\Delta x` lives in. + +.. function:: bool LocalParameterization::Plus(const double* x, const double* delta, double* x_plus_delta) const + + :func:`LocalParameterization::Plus` implements :math:`\boxplus(x,\Delta x)`. + +.. function:: bool LocalParameterization::ComputeJacobian(const double* x, double* jacobian) const + + Computes the Jacobian matrix + + .. math:: J = \left . \frac{\partial }{\partial \Delta x} \boxplus(x,\Delta x)\right|_{\Delta x = 0} + + in row major form. + +.. function:: bool MultiplyByJacobian(const double* x, const int num_rows, const double* global_matrix, double* local_matrix) const + + local_matrix = global_matrix * jacobian + + global_matrix is a num_rows x GlobalSize row major matrix. + local_matrix is a num_rows x LocalSize row major matrix. + jacobian is the matrix returned by :func:`LocalParameterization::ComputeJacobian` at :math:`x`. + + This is only used by GradientProblem. For most normal uses, it is + okay to use the default implementation. + +Instances +--------- + +.. class:: IdentityParameterization + + A trivial version of :math:`\boxplus` is when :math:`\Delta x` is + of the same size as :math:`x` and + + .. math:: \boxplus(x, \Delta x) = x + \Delta x + +.. class:: SubsetParameterization + + A more interesting case if :math:`x` is a two dimensional vector, + and the user wishes to hold the first coordinate constant. Then, + :math:`\Delta x` is a scalar and :math:`\boxplus` is defined as + + .. math:: + + \boxplus(x, \Delta x) = x + \left[ \begin{array}{c} 0 \\ 1 + \end{array} \right] \Delta x + + :class:`SubsetParameterization` generalizes this construction to + hold any part of a parameter block constant. + +.. class:: QuaternionParameterization + + Another example that occurs commonly in Structure from Motion + problems is when camera rotations are parameterized using a + quaternion. There, it is useful only to make updates orthogonal to + that 4-vector defining the quaternion. One way to do this is to let + :math:`\Delta x` be a 3 dimensional vector and define + :math:`\boxplus` to be + + .. math:: \boxplus(x, \Delta x) = \left[ \cos(|\Delta x|), \frac{\sin\left(|\Delta x|\right)}{|\Delta x|} \Delta x \right] * x + :label: quaternion + + The multiplication between the two 4-vectors on the right hand side + is the standard quaternion + product. :class:`QuaternionParameterization` is an implementation + of :eq:`quaternion`. + +.. class:: EigenQuaternionParameterization + + Eigen uses a different internal memory layout for the elements of the + quaternion than what is commonly used. Specifically, Eigen stores the + elements in memory as [x, y, z, w] where the real part is last + whereas it is typically stored first. Note, when creating an Eigen + quaternion through the constructor the elements are accepted in w, x, + y, z order. Since Ceres operates on parameter blocks which are raw + double pointers this difference is important and requires a different + parameterization. :class:`EigenQuaternionParameterization` uses the + same update as :class:`QuaternionParameterization` but takes into + account Eigen's internal memory element ordering. + +.. class:: HomogeneousVectorParameterization + + In computer vision, homogeneous vectors are commonly used to + represent entities in projective geometry such as points in + projective space. One example where it is useful to use this + over-parameterization is in representing points whose triangulation + is ill-conditioned. Here it is advantageous to use homogeneous + vectors, instead of an Euclidean vector, because it can represent + points at infinity. + + When using homogeneous vectors it is useful to only make updates + orthogonal to that :math:`n`-vector defining the homogeneous + vector [HartleyZisserman]_. One way to do this is to let :math:`\Delta x` + be a :math:`n-1` dimensional vector and define :math:`\boxplus` to be + + .. math:: \boxplus(x, \Delta x) = \left[ \frac{\sin\left(0.5 |\Delta x|\right)}{|\Delta x|} \Delta x, \cos(0.5 |\Delta x|) \right] * x + + The multiplication between the two vectors on the right hand side + is defined as an operator which applies the update orthogonal to + :math:`x` to remain on the sphere. Note, it is assumed that + last element of :math:`x` is the scalar component of the homogeneous + vector. + + +.. class:: ProductParameterization + + Consider an optimization problem over the space of rigid + transformations :math:`SE(3)`, which is the Cartesian product of + :math:`SO(3)` and :math:`\mathbb{R}^3`. Suppose you are using + Quaternions to represent the rotation, Ceres ships with a local + parameterization for that and :math:`\mathbb{R}^3` requires no, or + :class:`IdentityParameterization` parameterization. So how do we + construct a local parameterization for a parameter block a rigid + transformation? + + In cases, where a parameter block is the Cartesian product of a + number of manifolds and you have the local parameterization of the + individual manifolds available, :class:`ProductParameterization` + can be used to construct a local parameterization of the cartesian + product. For the case of the rigid transformation, where say you + have a parameter block of size 7, where the first four entries + represent the rotation as a quaternion, a local parameterization + can be constructed as + + .. code-block:: c++ + + ProductParameterization se3_param(new QuaternionParameterization(), + new IdentityTransformation(3)); + + +:class:`AutoDiffLocalParameterization` +====================================== + +.. class:: AutoDiffLocalParameterization + + :class:`AutoDiffLocalParameterization` does for + :class:`LocalParameterization` what :class:`AutoDiffCostFunction` + does for :class:`CostFunction`. It allows the user to define a + templated functor that implements the + :func:`LocalParameterization::Plus` operation and it uses automatic + differentiation to implement the computation of the Jacobian. + + To get an auto differentiated local parameterization, you must + define a class with a templated operator() (a functor) that computes + + .. math:: x' = \boxplus(x, \Delta x), + + For example, Quaternions have a three dimensional local + parameterization. Its plus operation can be implemented as (taken + from `internal/ceres/autodiff_local_parameterization_test.cc + `_ + ) + + .. code-block:: c++ + + struct QuaternionPlus { + template + bool operator()(const T* x, const T* delta, T* x_plus_delta) const { + const T squared_norm_delta = + delta[0] * delta[0] + delta[1] * delta[1] + delta[2] * delta[2]; + + T q_delta[4]; + if (squared_norm_delta > 0.0) { + T norm_delta = sqrt(squared_norm_delta); + const T sin_delta_by_delta = sin(norm_delta) / norm_delta; + q_delta[0] = cos(norm_delta); + q_delta[1] = sin_delta_by_delta * delta[0]; + q_delta[2] = sin_delta_by_delta * delta[1]; + q_delta[3] = sin_delta_by_delta * delta[2]; + } else { + // We do not just use q_delta = [1,0,0,0] here because that is a + // constant and when used for automatic differentiation will + // lead to a zero derivative. Instead we take a first order + // approximation and evaluate it at zero. + q_delta[0] = T(1.0); + q_delta[1] = delta[0]; + q_delta[2] = delta[1]; + q_delta[3] = delta[2]; + } + + Quaternionproduct(q_delta, x, x_plus_delta); + return true; + } + }; + + Given this struct, the auto differentiated local + parameterization can now be constructed as + + .. code-block:: c++ + + LocalParameterization* local_parameterization = + new AutoDiffLocalParameterization; + | | + Global Size ---------------+ | + Local Size -------------------+ + + +:class:`Problem` +================ + +.. class:: Problem + + :class:`Problem` holds the robustified bounds constrained + non-linear least squares problem :eq:`ceresproblem`. To create a + least squares problem, use the :func:`Problem::AddResidualBlock` + and :func:`Problem::AddParameterBlock` methods. + + For example a problem containing 3 parameter blocks of sizes 3, 4 + and 5 respectively and two residual blocks of size 2 and 6: + + .. code-block:: c++ + + double x1[] = { 1.0, 2.0, 3.0 }; + double x2[] = { 1.0, 2.0, 3.0, 5.0 }; + double x3[] = { 1.0, 2.0, 3.0, 6.0, 7.0 }; + + Problem problem; + problem.AddResidualBlock(new MyUnaryCostFunction(...), x1); + problem.AddResidualBlock(new MyBinaryCostFunction(...), x2, x3); + + :func:`Problem::AddResidualBlock` as the name implies, adds a + residual block to the problem. It adds a :class:`CostFunction`, an + optional :class:`LossFunction` and connects the + :class:`CostFunction` to a set of parameter block. + + The cost function carries with it information about the sizes of + the parameter blocks it expects. The function checks that these + match the sizes of the parameter blocks listed in + ``parameter_blocks``. The program aborts if a mismatch is + detected. ``loss_function`` can be ``NULL``, in which case the cost + of the term is just the squared norm of the residuals. + + The user has the option of explicitly adding the parameter blocks + using :func:`Problem::AddParameterBlock`. This causes additional + correctness checking; however, :func:`Problem::AddResidualBlock` + implicitly adds the parameter blocks if they are not present, so + calling :func:`Problem::AddParameterBlock` explicitly is not + required. + + :func:`Problem::AddParameterBlock` explicitly adds a parameter + block to the :class:`Problem`. Optionally it allows the user to + associate a :class:`LocalParameterization` object with the + parameter block too. Repeated calls with the same arguments are + ignored. Repeated calls with the same double pointer but a + different size results in undefined behavior. + + You can set any parameter block to be constant using + :func:`Problem::SetParameterBlockConstant` and undo this using + :func:`SetParameterBlockVariable`. + + In fact you can set any number of parameter blocks to be constant, + and Ceres is smart enough to figure out what part of the problem + you have constructed depends on the parameter blocks that are free + to change and only spends time solving it. So for example if you + constructed a problem with a million parameter blocks and 2 million + residual blocks, but then set all but one parameter blocks to be + constant and say only 10 residual blocks depend on this one + non-constant parameter block. Then the computational effort Ceres + spends in solving this problem will be the same if you had defined + a problem with one parameter block and 10 residual blocks. + + **Ownership** + + :class:`Problem` by default takes ownership of the + ``cost_function``, ``loss_function`` and ``local_parameterization`` + pointers. These objects remain live for the life of the + :class:`Problem`. If the user wishes to keep control over the + destruction of these objects, then they can do this by setting the + corresponding enums in the :class:`Problem::Options` struct. + + Note that even though the Problem takes ownership of ``cost_function`` + and ``loss_function``, it does not preclude the user from re-using + them in another residual block. The destructor takes care to call + delete on each ``cost_function`` or ``loss_function`` pointer only + once, regardless of how many residual blocks refer to them. + +.. function:: ResidualBlockId Problem::AddResidualBlock(CostFunction* cost_function, LossFunction* loss_function, const vector parameter_blocks) + + Add a residual block to the overall cost function. The cost + function carries with it information about the sizes of the + parameter blocks it expects. The function checks that these match + the sizes of the parameter blocks listed in parameter_blocks. The + program aborts if a mismatch is detected. loss_function can be + NULL, in which case the cost of the term is just the squared norm + of the residuals. + + The user has the option of explicitly adding the parameter blocks + using AddParameterBlock. This causes additional correctness + checking; however, AddResidualBlock implicitly adds the parameter + blocks if they are not present, so calling AddParameterBlock + explicitly is not required. + + The Problem object by default takes ownership of the + cost_function and loss_function pointers. These objects remain + live for the life of the Problem object. If the user wishes to + keep control over the destruction of these objects, then they can + do this by setting the corresponding enums in the Options struct. + + Note: Even though the Problem takes ownership of cost_function + and loss_function, it does not preclude the user from re-using + them in another residual block. The destructor takes care to call + delete on each cost_function or loss_function pointer only once, + regardless of how many residual blocks refer to them. + + Example usage: + + .. code-block:: c++ + + double x1[] = {1.0, 2.0, 3.0}; + double x2[] = {1.0, 2.0, 5.0, 6.0}; + double x3[] = {3.0, 6.0, 2.0, 5.0, 1.0}; + + Problem problem; + + problem.AddResidualBlock(new MyUnaryCostFunction(...), NULL, x1); + problem.AddResidualBlock(new MyBinaryCostFunction(...), NULL, x2, x1); + + +.. function:: void Problem::AddParameterBlock(double* values, int size, LocalParameterization* local_parameterization) + + Add a parameter block with appropriate size to the problem. + Repeated calls with the same arguments are ignored. Repeated calls + with the same double pointer but a different size results in + undefined behavior. + +.. function:: void Problem::AddParameterBlock(double* values, int size) + + Add a parameter block with appropriate size and parameterization to + the problem. Repeated calls with the same arguments are + ignored. Repeated calls with the same double pointer but a + different size results in undefined behavior. + +.. function:: void Problem::RemoveResidualBlock(ResidualBlockId residual_block) + + Remove a residual block from the problem. Any parameters that the residual + block depends on are not removed. The cost and loss functions for the + residual block will not get deleted immediately; won't happen until the + problem itself is deleted. If Problem::Options::enable_fast_removal is + true, then the removal is fast (almost constant time). Otherwise, removing a + residual block will incur a scan of the entire Problem object to verify that + the residual_block represents a valid residual in the problem. + + **WARNING:** Removing a residual or parameter block will destroy + the implicit ordering, rendering the jacobian or residuals returned + from the solver uninterpretable. If you depend on the evaluated + jacobian, do not use remove! This may change in a future release. + Hold the indicated parameter block constant during optimization. + +.. function:: void Problem::RemoveParameterBlock(double* values) + + Remove a parameter block from the problem. The parameterization of + the parameter block, if it exists, will persist until the deletion + of the problem (similar to cost/loss functions in residual block + removal). Any residual blocks that depend on the parameter are also + removed, as described above in RemoveResidualBlock(). If + Problem::Options::enable_fast_removal is true, then + the removal is fast (almost constant time). Otherwise, removing a + parameter block will incur a scan of the entire Problem object. + + **WARNING:** Removing a residual or parameter block will destroy + the implicit ordering, rendering the jacobian or residuals returned + from the solver uninterpretable. If you depend on the evaluated + jacobian, do not use remove! This may change in a future release. + +.. function:: void Problem::SetParameterBlockConstant(double* values) + + Hold the indicated parameter block constant during optimization. + +.. function:: void Problem::SetParameterBlockVariable(double* values) + + Allow the indicated parameter to vary during optimization. + +.. function:: void Problem::SetParameterization(double* values, LocalParameterization* local_parameterization) + + Set the local parameterization for one of the parameter blocks. + The local_parameterization is owned by the Problem by default. It + is acceptable to set the same parameterization for multiple + parameters; the destructor is careful to delete local + parameterizations only once. The local parameterization can only be + set once per parameter, and cannot be changed once set. + +.. function:: LocalParameterization* Problem::GetParameterization(double* values) const + + Get the local parameterization object associated with this + parameter block. If there is no parameterization object associated + then `NULL` is returned + +.. function:: void Problem::SetParameterLowerBound(double* values, int index, double lower_bound) + + Set the lower bound for the parameter at position `index` in the + parameter block corresponding to `values`. By default the lower + bound is :math:`-\infty`. + +.. function:: void Problem::SetParameterUpperBound(double* values, int index, double upper_bound) + + Set the upper bound for the parameter at position `index` in the + parameter block corresponding to `values`. By default the value is + :math:`\infty`. + +.. function:: int Problem::NumParameterBlocks() const + + Number of parameter blocks in the problem. Always equals + parameter_blocks().size() and parameter_block_sizes().size(). + +.. function:: int Problem::NumParameters() const + + The size of the parameter vector obtained by summing over the sizes + of all the parameter blocks. + +.. function:: int Problem::NumResidualBlocks() const + + Number of residual blocks in the problem. Always equals + residual_blocks().size(). + +.. function:: int Problem::NumResiduals() const + + The size of the residual vector obtained by summing over the sizes + of all of the residual blocks. + +.. function:: int Problem::ParameterBlockSize(const double* values) const + + The size of the parameter block. + +.. function:: int Problem::ParameterBlockLocalSize(const double* values) const + + The size of local parameterization for the parameter block. If + there is no local parameterization associated with this parameter + block, then ``ParameterBlockLocalSize`` = ``ParameterBlockSize``. + +.. function:: bool Problem::HasParameterBlock(const double* values) const + + Is the given parameter block present in the problem or not? + +.. function:: void Problem::GetParameterBlocks(vector* parameter_blocks) const + + Fills the passed ``parameter_blocks`` vector with pointers to the + parameter blocks currently in the problem. After this call, + ``parameter_block.size() == NumParameterBlocks``. + +.. function:: void Problem::GetResidualBlocks(vector* residual_blocks) const + + Fills the passed `residual_blocks` vector with pointers to the + residual blocks currently in the problem. After this call, + `residual_blocks.size() == NumResidualBlocks`. + +.. function:: void Problem::GetParameterBlocksForResidualBlock(const ResidualBlockId residual_block, vector* parameter_blocks) const + + Get all the parameter blocks that depend on the given residual + block. + +.. function:: void Problem::GetResidualBlocksForParameterBlock(const double* values, vector* residual_blocks) const + + Get all the residual blocks that depend on the given parameter + block. + + If `Problem::Options::enable_fast_removal` is + `true`, then getting the residual blocks is fast and depends only + on the number of residual blocks. Otherwise, getting the residual + blocks for a parameter block will incur a scan of the entire + :class:`Problem` object. + +.. function:: const CostFunction* GetCostFunctionForResidualBlock(const ResidualBlockId residual_block) const + + Get the :class:`CostFunction` for the given residual block. + +.. function:: const LossFunction* GetLossFunctionForResidualBlock(const ResidualBlockId residual_block) const + + Get the :class:`LossFunction` for the given residual block. + +.. function:: bool Problem::Evaluate(const Problem::EvaluateOptions& options, double* cost, vector* residuals, vector* gradient, CRSMatrix* jacobian) + + Evaluate a :class:`Problem`. Any of the output pointers can be + `NULL`. Which residual blocks and parameter blocks are used is + controlled by the :class:`Problem::EvaluateOptions` struct below. + + .. NOTE:: + + The evaluation will use the values stored in the memory + locations pointed to by the parameter block pointers used at the + time of the construction of the problem, for example in the + following code: + + .. code-block:: c++ + + Problem problem; + double x = 1; + problem.Add(new MyCostFunction, NULL, &x); + + double cost = 0.0; + problem.Evaluate(Problem::EvaluateOptions(), &cost, NULL, NULL, NULL); + + The cost is evaluated at `x = 1`. If you wish to evaluate the + problem at `x = 2`, then + + .. code-block:: c++ + + x = 2; + problem.Evaluate(Problem::EvaluateOptions(), &cost, NULL, NULL, NULL); + + is the way to do so. + + .. NOTE:: + + If no local parameterizations are used, then the size of + the gradient vector is the sum of the sizes of all the parameter + blocks. If a parameter block has a local parameterization, then + it contributes "LocalSize" entries to the gradient vector. + + .. NOTE:: + + This function cannot be called while the problem is being + solved, for example it cannot be called from an + :class:`IterationCallback` at the end of an iteration during a + solve. + +.. class:: Problem::EvaluateOptions + + Options struct that is used to control :func:`Problem::Evaluate`. + +.. member:: vector Problem::EvaluateOptions::parameter_blocks + + The set of parameter blocks for which evaluation should be + performed. This vector determines the order in which parameter + blocks occur in the gradient vector and in the columns of the + jacobian matrix. If parameter_blocks is empty, then it is assumed + to be equal to a vector containing ALL the parameter + blocks. Generally speaking the ordering of the parameter blocks in + this case depends on the order in which they were added to the + problem and whether or not the user removed any parameter blocks. + + **NOTE** This vector should contain the same pointers as the ones + used to add parameter blocks to the Problem. These parameter block + should NOT point to new memory locations. Bad things will happen if + you do. + +.. member:: vector Problem::EvaluateOptions::residual_blocks + + The set of residual blocks for which evaluation should be + performed. This vector determines the order in which the residuals + occur, and how the rows of the jacobian are ordered. If + residual_blocks is empty, then it is assumed to be equal to the + vector containing all the parameter blocks. + +.. member:: bool Problem::EvaluateOptions::apply_loss_function + + Even though the residual blocks in the problem may contain loss + functions, setting apply_loss_function to false will turn off the + application of the loss function to the output of the cost + function. This is of use for example if the user wishes to analyse + the solution quality by studying the distribution of residuals + before and after the solve. + +.. member:: int Problem::EvaluateOptions::num_threads + + Number of threads to use. (Requires OpenMP). + +``rotation.h`` +============== + +Many applications of Ceres Solver involve optimization problems where +some of the variables correspond to rotations. To ease the pain of +work with the various representations of rotations (angle-axis, +quaternion and matrix) we provide a handy set of templated +functions. These functions are templated so that the user can use them +within Ceres Solver's automatic differentiation framework. + +.. function:: template void AngleAxisToQuaternion(T const* angle_axis, T* quaternion) + + Convert a value in combined axis-angle representation to a + quaternion. + + The value ``angle_axis`` is a triple whose norm is an angle in radians, + and whose direction is aligned with the axis of rotation, and + ``quaternion`` is a 4-tuple that will contain the resulting quaternion. + +.. function:: template void QuaternionToAngleAxis(T const* quaternion, T* angle_axis) + + Convert a quaternion to the equivalent combined axis-angle + representation. + + The value ``quaternion`` must be a unit quaternion - it is not + normalized first, and ``angle_axis`` will be filled with a value + whose norm is the angle of rotation in radians, and whose direction + is the axis of rotation. + +.. function:: template void RotationMatrixToAngleAxis(const MatrixAdapter& R, T * angle_axis) +.. function:: template void AngleAxisToRotationMatrix(T const * angle_axis, const MatrixAdapter& R) +.. function:: template void RotationMatrixToAngleAxis(T const * R, T * angle_axis) +.. function:: template void AngleAxisToRotationMatrix(T const * angle_axis, T * R) + + Conversions between 3x3 rotation matrix with given column and row strides and + axis-angle rotation representations. The functions that take a pointer to T instead + of a MatrixAdapter assume a column major representation with unit row stride and a column stride of 3. + +.. function:: template void EulerAnglesToRotationMatrix(const T* euler, const MatrixAdapter& R) +.. function:: template void EulerAnglesToRotationMatrix(const T* euler, int row_stride, T* R) + + Conversions between 3x3 rotation matrix with given column and row strides and + Euler angle (in degrees) rotation representations. + + The {pitch,roll,yaw} Euler angles are rotations around the {x,y,z} + axes, respectively. They are applied in that same order, so the + total rotation R is Rz * Ry * Rx. + + The function that takes a pointer to T as the rotation matrix assumes a row + major representation with unit column stride and a row stride of 3. + The additional parameter row_stride is required to be 3. + +.. function:: template void QuaternionToScaledRotation(const T q[4], const MatrixAdapter& R) +.. function:: template void QuaternionToScaledRotation(const T q[4], T R[3 * 3]) + + Convert a 4-vector to a 3x3 scaled rotation matrix. + + The choice of rotation is such that the quaternion + :math:`\begin{bmatrix} 1 &0 &0 &0\end{bmatrix}` goes to an identity + matrix and for small :math:`a, b, c` the quaternion + :math:`\begin{bmatrix}1 &a &b &c\end{bmatrix}` goes to the matrix + + .. math:: + + I + 2 \begin{bmatrix} 0 & -c & b \\ c & 0 & -a\\ -b & a & 0 + \end{bmatrix} + O(q^2) + + which corresponds to a Rodrigues approximation, the last matrix + being the cross-product matrix of :math:`\begin{bmatrix} a& b& + c\end{bmatrix}`. Together with the property that :math:`R(q1 * q2) + = R(q1) * R(q2)` this uniquely defines the mapping from :math:`q` to + :math:`R`. + + In the function that accepts a pointer to T instead of a MatrixAdapter, + the rotation matrix ``R`` is a row-major matrix with unit column stride + and a row stride of 3. + + No normalization of the quaternion is performed, i.e. + :math:`R = \|q\|^2 Q`, where :math:`Q` is an orthonormal matrix + such that :math:`\det(Q) = 1` and :math:`Q*Q' = I`. + + +.. function:: template void QuaternionToRotation(const T q[4], const MatrixAdapter& R) +.. function:: template void QuaternionToRotation(const T q[4], T R[3 * 3]) + + Same as above except that the rotation matrix is normalized by the + Frobenius norm, so that :math:`R R' = I` (and :math:`\det(R) = 1`). + +.. function:: template void UnitQuaternionRotatePoint(const T q[4], const T pt[3], T result[3]) + + Rotates a point pt by a quaternion q: + + .. math:: \text{result} = R(q) \text{pt} + + Assumes the quaternion is unit norm. If you pass in a quaternion + with :math:`|q|^2 = 2` then you WILL NOT get back 2 times the + result you get for a unit quaternion. + + +.. function:: template void QuaternionRotatePoint(const T q[4], const T pt[3], T result[3]) + + With this function you do not need to assume that :math:`q` has unit norm. + It does assume that the norm is non-zero. + +.. function:: template void QuaternionProduct(const T z[4], const T w[4], T zw[4]) + + .. math:: zw = z * w + + where :math:`*` is the Quaternion product between 4-vectors. + + +.. function:: template void CrossProduct(const T x[3], const T y[3], T x_cross_y[3]) + + .. math:: \text{x_cross_y} = x \times y + +.. function:: template void AngleAxisRotatePoint(const T angle_axis[3], const T pt[3], T result[3]) + + .. math:: y = R(\text{angle_axis}) x + + +Cubic Interpolation +=================== + +Optimization problems often involve functions that are given in the +form of a table of values, for example an image. Evaluating these +functions and their derivatives requires interpolating these +values. Interpolating tabulated functions is a vast area of research +and there are a lot of libraries which implement a variety of +interpolation schemes. However, using them within the automatic +differentiation framework in Ceres is quite painful. To this end, +Ceres provides the ability to interpolate one dimensional and two +dimensional tabular functions. + +The one dimensional interpolation is based on the Cubic Hermite +Spline, also known as the Catmull-Rom Spline. This produces a first +order differentiable interpolating function. The two dimensional +interpolation scheme is a generalization of the one dimensional scheme +where the interpolating function is assumed to be separable in the two +dimensions, + +More details of the construction can be found `Linear Methods for +Image Interpolation `_ by +Pascal Getreuer. + +.. class:: CubicInterpolator + +Given as input an infinite one dimensional grid, which provides the +following interface. + +.. code:: + + struct Grid1D { + enum { DATA_DIMENSION = 2; }; + void GetValue(int n, double* f) const; + }; + +Where, ``GetValue`` gives us the value of a function :math:`f` +(possibly vector valued) for any integer :math:`n` and the enum +``DATA_DIMENSION`` indicates the dimensionality of the function being +interpolated. For example if you are interpolating rotations in +axis-angle format over time, then ``DATA_DIMENSION = 3``. + +:class:`CubicInterpolator` uses Cubic Hermite splines to produce a +smooth approximation to it that can be used to evaluate the +:math:`f(x)` and :math:`f'(x)` at any point on the real number +line. For example, the following code interpolates an array of four +numbers. + +.. code:: + + const double data[] = {1.0, 2.0, 5.0, 6.0}; + Grid1D array(x, 0, 4); + CubicInterpolator interpolator(array); + double f, dfdx; + interpolator.Evaluate(1.5, &f, &dfdx); + + +In the above code we use ``Grid1D`` a templated helper class that +allows easy interfacing between ``C++`` arrays and +:class:`CubicInterpolator`. + +``Grid1D`` supports vector valued functions where the various +coordinates of the function can be interleaved or stacked. It also +allows the use of any numeric type as input, as long as it can be +safely cast to a double. + +.. class:: BiCubicInterpolator + +Given as input an infinite two dimensional grid, which provides the +following interface: + +.. code:: + + struct Grid2D { + enum { DATA_DIMENSION = 2 }; + void GetValue(int row, int col, double* f) const; + }; + +Where, ``GetValue`` gives us the value of a function :math:`f` +(possibly vector valued) for any pair of integers :code:`row` and +:code:`col` and the enum ``DATA_DIMENSION`` indicates the +dimensionality of the function being interpolated. For example if you +are interpolating a color image with three channels (Red, Green & +Blue), then ``DATA_DIMENSION = 3``. + +:class:`BiCubicInterpolator` uses the cubic convolution interpolation +algorithm of R. Keys [Keys]_, to produce a smooth approximation to it +that can be used to evaluate the :math:`f(r,c)`, :math:`\frac{\partial +f(r,c)}{\partial r}` and :math:`\frac{\partial f(r,c)}{\partial c}` at +any any point in the real plane. + +For example the following code interpolates a two dimensional array. + +.. code:: + + const double data[] = {1.0, 3.0, -1.0, 4.0, + 3.6, 2.1, 4.2, 2.0, + 2.0, 1.0, 3.1, 5.2}; + Grid2D array(data, 0, 3, 0, 4); + BiCubicInterpolator interpolator(array); + double f, dfdr, dfdc; + interpolator.Evaluate(1.2, 2.5, &f, &dfdr, &dfdc); + +In the above code, the templated helper class ``Grid2D`` is used to +make a ``C++`` array look like a two dimensional table to +:class:`BiCubicInterpolator`. + +``Grid2D`` supports row or column major layouts. It also supports +vector valued functions where the individual coordinates of the +function may be interleaved or stacked. It also allows the use of any +numeric type as input, as long as it can be safely cast to double. diff --git a/docs/source/nnls_solving.rst b/docs/source/nnls_solving.rst new file mode 100644 index 0000000..fed0b3e --- /dev/null +++ b/docs/source/nnls_solving.rst @@ -0,0 +1,2257 @@ + +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-nnls_solving: + +================================ +Solving Non-linear Least Squares +================================ + +Introduction +============ + +Effective use of Ceres requires some familiarity with the basic +components of a non-linear least squares solver, so before we describe +how to configure and use the solver, we will take a brief look at how +some of the core optimization algorithms in Ceres work. + +Let :math:`x \in \mathbb{R}^n` be an :math:`n`-dimensional vector of +variables, and +:math:`F(x) = \left[f_1(x), ... , f_{m}(x) \right]^{\top}` be a +:math:`m`-dimensional function of :math:`x`. We are interested in +solving the optimization problem [#f1]_ + +.. math:: \arg \min_x \frac{1}{2}\|F(x)\|^2\ . \\ + L \le x \le U + :label: nonlinsq + +Where, :math:`L` and :math:`U` are lower and upper bounds on the +parameter vector :math:`x`. + +Since the efficient global minimization of :eq:`nonlinsq` for +general :math:`F(x)` is an intractable problem, we will have to settle +for finding a local minimum. + +In the following, the Jacobian :math:`J(x)` of :math:`F(x)` is an +:math:`m\times n` matrix, where :math:`J_{ij}(x) = \partial_j f_i(x)` +and the gradient vector is :math:`g(x) = \nabla \frac{1}{2}\|F(x)\|^2 += J(x)^\top F(x)`. + +The general strategy when solving non-linear optimization problems is +to solve a sequence of approximations to the original problem +[NocedalWright]_. At each iteration, the approximation is solved to +determine a correction :math:`\Delta x` to the vector :math:`x`. For +non-linear least squares, an approximation can be constructed by using +the linearization :math:`F(x+\Delta x) \approx F(x) + J(x)\Delta x`, +which leads to the following linear least squares problem: + +.. math:: \min_{\Delta x} \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 + :label: linearapprox + +Unfortunately, naively solving a sequence of these problems and +updating :math:`x \leftarrow x+ \Delta x` leads to an algorithm that +may not converge. To get a convergent algorithm, we need to control +the size of the step :math:`\Delta x`. Depending on how the size of +the step :math:`\Delta x` is controlled, non-linear optimization +algorithms can be divided into two major categories [NocedalWright]_. + +1. **Trust Region** The trust region approach approximates the + objective function using using a model function (often a quadratic) + over a subset of the search space known as the trust region. If the + model function succeeds in minimizing the true objective function + the trust region is expanded; conversely, otherwise it is + contracted and the model optimization problem is solved again. + +2. **Line Search** The line search approach first finds a descent + direction along which the objective function will be reduced and + then computes a step size that decides how far should move along + that direction. The descent direction can be computed by various + methods, such as gradient descent, Newton's method and Quasi-Newton + method. The step size can be determined either exactly or + inexactly. + +Trust region methods are in some sense dual to line search methods: +trust region methods first choose a step size (the size of the trust +region) and then a step direction while line search methods first +choose a step direction and then a step size. Ceres implements +multiple algorithms in both categories. + +.. _section-trust-region-methods: + +Trust Region Methods +==================== + +The basic trust region algorithm looks something like this. + + 1. Given an initial point :math:`x` and a trust region radius :math:`\mu`. + 2. Solve + + .. math:: + \arg \min_{\Delta x}& \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 \\ + \text{such that} &\|D(x)\Delta x\|^2 \le \mu\\ + &L \le x + \Delta x \le U. + + 3. :math:`\rho = \frac{\displaystyle \|F(x + \Delta x)\|^2 - + \|F(x)\|^2}{\displaystyle \|J(x)\Delta x + F(x)\|^2 - + \|F(x)\|^2}` + 4. if :math:`\rho > \epsilon` then :math:`x = x + \Delta x`. + 5. if :math:`\rho > \eta_1` then :math:`\mu = 2 \mu` + 6. else if :math:`\rho < \eta_2` then :math:`\mu = 0.5 * \mu` + 7. Go to 2. + +Here, :math:`\mu` is the trust region radius, :math:`D(x)` is some +matrix used to define a metric on the domain of :math:`F(x)` and +:math:`\rho` measures the quality of the step :math:`\Delta x`, i.e., +how well did the linear model predict the decrease in the value of the +non-linear objective. The idea is to increase or decrease the radius +of the trust region depending on how well the linearization predicts +the behavior of the non-linear objective, which in turn is reflected +in the value of :math:`\rho`. + +The key computational step in a trust-region algorithm is the solution +of the constrained optimization problem + +.. math:: + \arg \min_{\Delta x}&\quad \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 \\ + \text{such that} &\quad \|D(x)\Delta x\|^2 \le \mu\\ + &\quad L \le x + \Delta x \le U. + :label: trp + +There are a number of different ways of solving this problem, each +giving rise to a different concrete trust-region algorithm. Currently, +Ceres implements two trust-region algorithms - Levenberg-Marquardt +and Dogleg, each of which is augmented with a line search if bounds +constraints are present [Kanzow]_. The user can choose between them by +setting :member:`Solver::Options::trust_region_strategy_type`. + +.. rubric:: Footnotes + +.. [#f1] At the level of the non-linear solver, the block structure is + not relevant, therefore our discussion here is in terms of an + optimization problem defined over a state vector of size + :math:`n`. Similarly the presence of loss functions is also + ignored as the problem is internally converted into a pure + non-linear least squares problem. + + +.. _section-levenberg-marquardt: + +Levenberg-Marquardt +------------------- + +The Levenberg-Marquardt algorithm [Levenberg]_ [Marquardt]_ is the +most popular algorithm for solving non-linear least squares problems. +It was also the first trust region algorithm to be developed +[Levenberg]_ [Marquardt]_. Ceres implements an exact step [Madsen]_ +and an inexact step variant of the Levenberg-Marquardt algorithm +[WrightHolt]_ [NashSofer]_. + +It can be shown, that the solution to :eq:`trp` can be obtained by +solving an unconstrained optimization of the form + +.. math:: \arg\min_{\Delta x} \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 +\lambda \|D(x)\Delta x\|^2 + +Where, :math:`\lambda` is a Lagrange multiplier that is inverse +related to :math:`\mu`. In Ceres, we solve for + +.. math:: \arg\min_{\Delta x} \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 + \frac{1}{\mu} \|D(x)\Delta x\|^2 + :label: lsqr + +The matrix :math:`D(x)` is a non-negative diagonal matrix, typically +the square root of the diagonal of the matrix :math:`J(x)^\top J(x)`. + +Before going further, let us make some notational simplifications. We +will assume that the matrix :math:`\sqrt{\mu} D` has been concatenated +at the bottom of the matrix :math:`J` and similarly a vector of zeros +has been added to the bottom of the vector :math:`f` and the rest of +our discussion will be in terms of :math:`J` and :math:`f`, i.e, the +linear least squares problem. + +.. math:: \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + f(x)\|^2 . + :label: simple + +For all but the smallest problems the solution of :eq:`simple` in +each iteration of the Levenberg-Marquardt algorithm is the dominant +computational cost in Ceres. Ceres provides a number of different +options for solving :eq:`simple`. There are two major classes of +methods - factorization and iterative. + +The factorization methods are based on computing an exact solution of +:eq:`lsqr` using a Cholesky or a QR factorization and lead to an exact +step Levenberg-Marquardt algorithm. But it is not clear if an exact +solution of :eq:`lsqr` is necessary at each step of the LM algorithm +to solve :eq:`nonlinsq`. In fact, we have already seen evidence +that this may not be the case, as :eq:`lsqr` is itself a regularized +version of :eq:`linearapprox`. Indeed, it is possible to +construct non-linear optimization algorithms in which the linearized +problem is solved approximately. These algorithms are known as inexact +Newton or truncated Newton methods [NocedalWright]_. + +An inexact Newton method requires two ingredients. First, a cheap +method for approximately solving systems of linear +equations. Typically an iterative linear solver like the Conjugate +Gradients method is used for this +purpose [NocedalWright]_. Second, a termination rule for +the iterative solver. A typical termination rule is of the form + +.. math:: \|H(x) \Delta x + g(x)\| \leq \eta_k \|g(x)\|. + :label: inexact + +Here, :math:`k` indicates the Levenberg-Marquardt iteration number and +:math:`0 < \eta_k <1` is known as the forcing sequence. [WrightHolt]_ +prove that a truncated Levenberg-Marquardt algorithm that uses an +inexact Newton step based on :eq:`inexact` converges for any +sequence :math:`\eta_k \leq \eta_0 < 1` and the rate of convergence +depends on the choice of the forcing sequence :math:`\eta_k`. + +Ceres supports both exact and inexact step solution strategies. When +the user chooses a factorization based linear solver, the exact step +Levenberg-Marquardt algorithm is used. When the user chooses an +iterative linear solver, the inexact step Levenberg-Marquardt +algorithm is used. + +.. _section-dogleg: + +Dogleg +------ + +Another strategy for solving the trust region problem :eq:`trp` was +introduced by M. J. D. Powell. The key idea there is to compute two +vectors + +.. math:: + + \Delta x^{\text{Gauss-Newton}} &= \arg \min_{\Delta x}\frac{1}{2} \|J(x)\Delta x + f(x)\|^2.\\ + \Delta x^{\text{Cauchy}} &= -\frac{\|g(x)\|^2}{\|J(x)g(x)\|^2}g(x). + +Note that the vector :math:`\Delta x^{\text{Gauss-Newton}}` is the +solution to :eq:`linearapprox` and :math:`\Delta +x^{\text{Cauchy}}` is the vector that minimizes the linear +approximation if we restrict ourselves to moving along the direction +of the gradient. Dogleg methods finds a vector :math:`\Delta x` +defined by :math:`\Delta x^{\text{Gauss-Newton}}` and :math:`\Delta +x^{\text{Cauchy}}` that solves the trust region problem. Ceres +supports two variants that can be chose by setting +:member:`Solver::Options::dogleg_type`. + +``TRADITIONAL_DOGLEG`` as described by Powell, constructs two line +segments using the Gauss-Newton and Cauchy vectors and finds the point +farthest along this line shaped like a dogleg (hence the name) that is +contained in the trust-region. For more details on the exact reasoning +and computations, please see Madsen et al [Madsen]_. + +``SUBSPACE_DOGLEG`` is a more sophisticated method that considers the +entire two dimensional subspace spanned by these two vectors and finds +the point that minimizes the trust region problem in this subspace +[ByrdSchnabel]_. + +The key advantage of the Dogleg over Levenberg-Marquardt is that if +the step computation for a particular choice of :math:`\mu` does not +result in sufficient decrease in the value of the objective function, +Levenberg-Marquardt solves the linear approximation from scratch with +a smaller value of :math:`\mu`. Dogleg on the other hand, only needs +to compute the interpolation between the Gauss-Newton and the Cauchy +vectors, as neither of them depend on the value of :math:`\mu`. + +The Dogleg method can only be used with the exact factorization based +linear solvers. + +.. _section-inner-iterations: + +Inner Iterations +---------------- + +Some non-linear least squares problems have additional structure in +the way the parameter blocks interact that it is beneficial to modify +the way the trust region step is computed. For example, consider the +following regression problem + +.. math:: y = a_1 e^{b_1 x} + a_2 e^{b_3 x^2 + c_1} + + +Given a set of pairs :math:`\{(x_i, y_i)\}`, the user wishes to estimate +:math:`a_1, a_2, b_1, b_2`, and :math:`c_1`. + +Notice that the expression on the left is linear in :math:`a_1` and +:math:`a_2`, and given any value for :math:`b_1, b_2` and :math:`c_1`, +it is possible to use linear regression to estimate the optimal values +of :math:`a_1` and :math:`a_2`. It's possible to analytically +eliminate the variables :math:`a_1` and :math:`a_2` from the problem +entirely. Problems like these are known as separable least squares +problem and the most famous algorithm for solving them is the Variable +Projection algorithm invented by Golub & Pereyra [GolubPereyra]_. + +Similar structure can be found in the matrix factorization with +missing data problem. There the corresponding algorithm is known as +Wiberg's algorithm [Wiberg]_. + +Ruhe & Wedin present an analysis of various algorithms for solving +separable non-linear least squares problems and refer to *Variable +Projection* as Algorithm I in their paper [RuheWedin]_. + +Implementing Variable Projection is tedious and expensive. Ruhe & +Wedin present a simpler algorithm with comparable convergence +properties, which they call Algorithm II. Algorithm II performs an +additional optimization step to estimate :math:`a_1` and :math:`a_2` +exactly after computing a successful Newton step. + + +This idea can be generalized to cases where the residual is not +linear in :math:`a_1` and :math:`a_2`, i.e., + +.. math:: y = f_1(a_1, e^{b_1 x}) + f_2(a_2, e^{b_3 x^2 + c_1}) + +In this case, we solve for the trust region step for the full problem, +and then use it as the starting point to further optimize just `a_1` +and `a_2`. For the linear case, this amounts to doing a single linear +least squares solve. For non-linear problems, any method for solving +the :math:`a_1` and :math:`a_2` optimization problems will do. The +only constraint on :math:`a_1` and :math:`a_2` (if they are two +different parameter block) is that they do not co-occur in a residual +block. + +This idea can be further generalized, by not just optimizing +:math:`(a_1, a_2)`, but decomposing the graph corresponding to the +Hessian matrix's sparsity structure into a collection of +non-overlapping independent sets and optimizing each of them. + +Setting :member:`Solver::Options::use_inner_iterations` to ``true`` +enables the use of this non-linear generalization of Ruhe & Wedin's +Algorithm II. This version of Ceres has a higher iteration +complexity, but also displays better convergence behavior per +iteration. + +Setting :member:`Solver::Options::num_threads` to the maximum number +possible is highly recommended. + +.. _section-non-monotonic-steps: + +Non-monotonic Steps +------------------- + +Note that the basic trust-region algorithm described in +:ref:`section-trust-region-methods` is a descent algorithm in that it +only accepts a point if it strictly reduces the value of the objective +function. + +Relaxing this requirement allows the algorithm to be more efficient in +the long term at the cost of some local increase in the value of the +objective function. + +This is because allowing for non-decreasing objective function values +in a principled manner allows the algorithm to *jump over boulders* as +the method is not restricted to move into narrow valleys while +preserving its convergence properties. + +Setting :member:`Solver::Options::use_nonmonotonic_steps` to ``true`` +enables the non-monotonic trust region algorithm as described by Conn, +Gould & Toint in [Conn]_. + +Even though the value of the objective function may be larger +than the minimum value encountered over the course of the +optimization, the final parameters returned to the user are the +ones corresponding to the minimum cost over all iterations. + +The option to take non-monotonic steps is available for all trust +region strategies. + + +.. _section-line-search-methods: + +Line Search Methods +=================== + +The line search method in Ceres Solver cannot handle bounds +constraints right now, so it can only be used for solving +unconstrained problems. + +Line search algorithms + + 1. Given an initial point :math:`x` + 2. :math:`\Delta x = -H^{-1}(x) g(x)` + 3. :math:`\arg \min_\mu \frac{1}{2} \| F(x + \mu \Delta x) \|^2` + 4. :math:`x = x + \mu \Delta x` + 5. Goto 2. + +Here :math:`H(x)` is some approximation to the Hessian of the +objective function, and :math:`g(x)` is the gradient at +:math:`x`. Depending on the choice of :math:`H(x)` we get a variety of +different search directions :math:`\Delta x`. + +Step 4, which is a one dimensional optimization or `Line Search` along +:math:`\Delta x` is what gives this class of methods its name. + +Different line search algorithms differ in their choice of the search +direction :math:`\Delta x` and the method used for one dimensional +optimization along :math:`\Delta x`. The choice of :math:`H(x)` is the +primary source of computational complexity in these +methods. Currently, Ceres Solver supports three choices of search +directions, all aimed at large scale problems. + +1. ``STEEPEST_DESCENT`` This corresponds to choosing :math:`H(x)` to + be the identity matrix. This is not a good search direction for + anything but the simplest of the problems. It is only included here + for completeness. + +2. ``NONLINEAR_CONJUGATE_GRADIENT`` A generalization of the Conjugate + Gradient method to non-linear functions. The generalization can be + performed in a number of different ways, resulting in a variety of + search directions. Ceres Solver currently supports + ``FLETCHER_REEVES``, ``POLAK_RIBIERE`` and ``HESTENES_STIEFEL`` + directions. + +3. ``BFGS`` A generalization of the Secant method to multiple + dimensions in which a full, dense approximation to the inverse + Hessian is maintained and used to compute a quasi-Newton step + [NocedalWright]_. BFGS is currently the best known general + quasi-Newton algorithm. + +4. ``LBFGS`` A limited memory approximation to the full ``BFGS`` + method in which the last `M` iterations are used to approximate the + inverse Hessian used to compute a quasi-Newton step [Nocedal]_, + [ByrdNocedal]_. + +Currently Ceres Solver supports both a backtracking and interpolation +based Armijo line search algorithm, and a sectioning / zoom +interpolation (strong) Wolfe condition line search algorithm. +However, note that in order for the assumptions underlying the +``BFGS`` and ``LBFGS`` methods to be guaranteed to be satisfied the +Wolfe line search algorithm should be used. + +.. _section-linear-solver: + +LinearSolver +============ + +Recall that in both of the trust-region methods described above, the +key computational cost is the solution of a linear least squares +problem of the form + +.. math:: \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + f(x)\|^2 . + :label: simple2 + +Let :math:`H(x)= J(x)^\top J(x)` and :math:`g(x) = -J(x)^\top +f(x)`. For notational convenience let us also drop the dependence on +:math:`x`. Then it is easy to see that solving :eq:`simple2` is +equivalent to solving the *normal equations*. + +.. math:: H \Delta x = g + :label: normal + +Ceres provides a number of different options for solving :eq:`normal`. + +.. _section-qr: + +``DENSE_QR`` +------------ + +For small problems (a couple of hundred parameters and a few thousand +residuals) with relatively dense Jacobians, ``DENSE_QR`` is the method +of choice [Bjorck]_. Let :math:`J = QR` be the QR-decomposition of +:math:`J`, where :math:`Q` is an orthonormal matrix and :math:`R` is +an upper triangular matrix [TrefethenBau]_. Then it can be shown that +the solution to :eq:`normal` is given by + +.. math:: \Delta x^* = -R^{-1}Q^\top f + + +Ceres uses ``Eigen`` 's dense QR factorization routines. + +.. _section-cholesky: + +``DENSE_NORMAL_CHOLESKY`` & ``SPARSE_NORMAL_CHOLESKY`` +------------------------------------------------------ + +Large non-linear least square problems are usually sparse. In such +cases, using a dense QR factorization is inefficient. Let :math:`H = +R^\top R` be the Cholesky factorization of the normal equations, where +:math:`R` is an upper triangular matrix, then the solution to +:eq:`normal` is given by + +.. math:: + + \Delta x^* = R^{-1} R^{-\top} g. + + +The observant reader will note that the :math:`R` in the Cholesky +factorization of :math:`H` is the same upper triangular matrix +:math:`R` in the QR factorization of :math:`J`. Since :math:`Q` is an +orthonormal matrix, :math:`J=QR` implies that :math:`J^\top J = R^\top +Q^\top Q R = R^\top R`. There are two variants of Cholesky +factorization -- sparse and dense. + +``DENSE_NORMAL_CHOLESKY`` as the name implies performs a dense +Cholesky factorization of the normal equations. Ceres uses +``Eigen`` 's dense LDLT factorization routines. + +``SPARSE_NORMAL_CHOLESKY``, as the name implies performs a sparse +Cholesky factorization of the normal equations. This leads to +substantial savings in time and memory for large sparse +problems. Ceres uses the sparse Cholesky factorization routines in +Professor Tim Davis' ``SuiteSparse`` or ``CXSparse`` packages [Chen]_ +or the sparse Cholesky factorization algorithm in ``Eigen`` (which +incidently is a port of the algorithm implemented inside ``CXSparse``) + +.. _section-cgnr: + +``CGNR`` +-------- + +For general sparse problems, if the problem is too large for +``CHOLMOD`` or a sparse linear algebra library is not linked into +Ceres, another option is the ``CGNR`` solver. This solver uses the +Conjugate Gradients solver on the *normal equations*, but without +forming the normal equations explicitly. It exploits the relation + +.. math:: + H x = J^\top J x = J^\top(J x) + +The convergence of Conjugate Gradients depends on the conditioner +number :math:`\kappa(H)`. Usually :math:`H` is poorly conditioned and +a :ref:`section-preconditioner` must be used to get reasonable +performance. Currently only the ``JACOBI`` preconditioner is available +for use with ``CGNR``. It uses the block diagonal of :math:`H` to +precondition the normal equations. + +When the user chooses ``CGNR`` as the linear solver, Ceres +automatically switches from the exact step algorithm to an inexact +step algorithm. + +.. _section-schur: + +``DENSE_SCHUR`` & ``SPARSE_SCHUR`` +---------------------------------- + +While it is possible to use ``SPARSE_NORMAL_CHOLESKY`` to solve bundle +adjustment problems, bundle adjustment problem have a special +structure, and a more efficient scheme for solving :eq:`normal` +can be constructed. + +Suppose that the SfM problem consists of :math:`p` cameras and +:math:`q` points and the variable vector :math:`x` has the block +structure :math:`x = [y_{1}, ... ,y_{p},z_{1}, ... ,z_{q}]`. Where, +:math:`y` and :math:`z` correspond to camera and point parameters, +respectively. Further, let the camera blocks be of size :math:`c` and +the point blocks be of size :math:`s` (for most problems :math:`c` = +:math:`6`--`9` and :math:`s = 3`). Ceres does not impose any constancy +requirement on these block sizes, but choosing them to be constant +simplifies the exposition. + +A key characteristic of the bundle adjustment problem is that there is +no term :math:`f_{i}` that includes two or more point blocks. This in +turn implies that the matrix :math:`H` is of the form + +.. math:: H = \left[ \begin{matrix} B & E\\ E^\top & C \end{matrix} \right]\ , + :label: hblock + +where :math:`B \in \mathbb{R}^{pc\times pc}` is a block sparse matrix +with :math:`p` blocks of size :math:`c\times c` and :math:`C \in +\mathbb{R}^{qs\times qs}` is a block diagonal matrix with :math:`q` blocks +of size :math:`s\times s`. :math:`E \in \mathbb{R}^{pc\times qs}` is a +general block sparse matrix, with a block of size :math:`c\times s` +for each observation. Let us now block partition :math:`\Delta x = +[\Delta y,\Delta z]` and :math:`g=[v,w]` to restate :eq:`normal` +as the block structured linear system + +.. math:: \left[ \begin{matrix} B & E\\ E^\top & C \end{matrix} + \right]\left[ \begin{matrix} \Delta y \\ \Delta z + \end{matrix} \right] = \left[ \begin{matrix} v\\ w + \end{matrix} \right]\ , + :label: linear2 + +and apply Gaussian elimination to it. As we noted above, :math:`C` is +a block diagonal matrix, with small diagonal blocks of size +:math:`s\times s`. Thus, calculating the inverse of :math:`C` by +inverting each of these blocks is cheap. This allows us to eliminate +:math:`\Delta z` by observing that :math:`\Delta z = C^{-1}(w - E^\top +\Delta y)`, giving us + +.. math:: \left[B - EC^{-1}E^\top\right] \Delta y = v - EC^{-1}w\ . + :label: schur + +The matrix + +.. math:: S = B - EC^{-1}E^\top + +is the Schur complement of :math:`C` in :math:`H`. It is also known as +the *reduced camera matrix*, because the only variables +participating in :eq:`schur` are the ones corresponding to the +cameras. :math:`S \in \mathbb{R}^{pc\times pc}` is a block structured +symmetric positive definite matrix, with blocks of size :math:`c\times +c`. The block :math:`S_{ij}` corresponding to the pair of images +:math:`i` and :math:`j` is non-zero if and only if the two images +observe at least one common point. + + +Now, :eq:`linear2` can be solved by first forming :math:`S`, solving for +:math:`\Delta y`, and then back-substituting :math:`\Delta y` to +obtain the value of :math:`\Delta z`. Thus, the solution of what was +an :math:`n\times n`, :math:`n=pc+qs` linear system is reduced to the +inversion of the block diagonal matrix :math:`C`, a few matrix-matrix +and matrix-vector multiplies, and the solution of block sparse +:math:`pc\times pc` linear system :eq:`schur`. For almost all +problems, the number of cameras is much smaller than the number of +points, :math:`p \ll q`, thus solving :eq:`schur` is +significantly cheaper than solving :eq:`linear2`. This is the +*Schur complement trick* [Brown]_. + +This still leaves open the question of solving :eq:`schur`. The +method of choice for solving symmetric positive definite systems +exactly is via the Cholesky factorization [TrefethenBau]_ and +depending upon the structure of the matrix, there are, in general, two +options. The first is direct factorization, where we store and factor +:math:`S` as a dense matrix [TrefethenBau]_. This method has +:math:`O(p^2)` space complexity and :math:`O(p^3)` time complexity and +is only practical for problems with up to a few hundred cameras. Ceres +implements this strategy as the ``DENSE_SCHUR`` solver. + + +But, :math:`S` is typically a fairly sparse matrix, as most images +only see a small fraction of the scene. This leads us to the second +option: Sparse Direct Methods. These methods store :math:`S` as a +sparse matrix, use row and column re-ordering algorithms to maximize +the sparsity of the Cholesky decomposition, and focus their compute +effort on the non-zero part of the factorization [Chen]_. Sparse +direct methods, depending on the exact sparsity structure of the Schur +complement, allow bundle adjustment algorithms to significantly scale +up over those based on dense factorization. Ceres implements this +strategy as the ``SPARSE_SCHUR`` solver. + +.. _section-iterative_schur: + +``ITERATIVE_SCHUR`` +------------------- + +Another option for bundle adjustment problems is to apply +Preconditioned Conjugate Gradients to the reduced camera matrix +:math:`S` instead of :math:`H`. One reason to do this is that +:math:`S` is a much smaller matrix than :math:`H`, but more +importantly, it can be shown that :math:`\kappa(S)\leq \kappa(H)`. +Ceres implements Conjugate Gradients on :math:`S` as the +``ITERATIVE_SCHUR`` solver. When the user chooses ``ITERATIVE_SCHUR`` +as the linear solver, Ceres automatically switches from the exact step +algorithm to an inexact step algorithm. + +The key computational operation when using Conjuagate Gradients is the +evaluation of the matrix vector product :math:`Sx` for an arbitrary +vector :math:`x`. There are two ways in which this product can be +evaluated, and this can be controlled using +``Solver::Options::use_explicit_schur_complement``. Depending on the +problem at hand, the performance difference between these two methods +can be quite substantial. + + 1. **Implicit** This is default. Implicit evaluation is suitable for + large problems where the cost of computing and storing the Schur + Complement :math:`S` is prohibitive. Because PCG only needs + access to :math:`S` via its product with a vector, one way to + evaluate :math:`Sx` is to observe that + + .. math:: x_1 &= E^\top x + .. math:: x_2 &= C^{-1} x_1 + .. math:: x_3 &= Ex_2\\ + .. math:: x_4 &= Bx\\ + .. math:: Sx &= x_4 - x_3 + :label: schurtrick1 + + Thus, we can run PCG on :math:`S` with the same computational + effort per iteration as PCG on :math:`H`, while reaping the + benefits of a more powerful preconditioner. In fact, we do not + even need to compute :math:`H`, :eq:`schurtrick1` can be + implemented using just the columns of :math:`J`. + + Equation :eq:`schurtrick1` is closely related to *Domain + Decomposition methods* for solving large linear systems that + arise in structural engineering and partial differential + equations. In the language of Domain Decomposition, each point in + a bundle adjustment problem is a domain, and the cameras form the + interface between these domains. The iterative solution of the + Schur complement then falls within the sub-category of techniques + known as Iterative Sub-structuring [Saad]_ [Mathew]_. + + 2. **Explicit** The complexity of implicit matrix-vector product + evaluation scales with the number of non-zeros in the + Jacobian. For small to medium sized problems, the cost of + constructing the Schur Complement is small enough that it is + better to construct it explicitly in memory and use it to + evaluate the product :math:`Sx`. + +When the user chooses ``ITERATIVE_SCHUR`` as the linear solver, Ceres +automatically switches from the exact step algorithm to an inexact +step algorithm. + + .. NOTE:: + + In exact arithmetic, the choice of implicit versus explicit Schur + complement would have no impact on solution quality. However, in + practice if the Jacobian is poorly conditioned, one may observe + (usually small) differences in solution quality. This is a + natural consequence of performing computations in finite arithmetic. + + +.. _section-preconditioner: + +Preconditioner +-------------- + +The convergence rate of Conjugate Gradients for +solving :eq:`normal` depends on the distribution of eigenvalues +of :math:`H` [Saad]_. A useful upper bound is +:math:`\sqrt{\kappa(H)}`, where, :math:`\kappa(H)` is the condition +number of the matrix :math:`H`. For most bundle adjustment problems, +:math:`\kappa(H)` is high and a direct application of Conjugate +Gradients to :eq:`normal` results in extremely poor performance. + +The solution to this problem is to replace :eq:`normal` with a +*preconditioned* system. Given a linear system, :math:`Ax =b` and a +preconditioner :math:`M` the preconditioned system is given by +:math:`M^{-1}Ax = M^{-1}b`. The resulting algorithm is known as +Preconditioned Conjugate Gradients algorithm (PCG) and its worst case +complexity now depends on the condition number of the *preconditioned* +matrix :math:`\kappa(M^{-1}A)`. + +The computational cost of using a preconditioner :math:`M` is the cost +of computing :math:`M` and evaluating the product :math:`M^{-1}y` for +arbitrary vectors :math:`y`. Thus, there are two competing factors to +consider: How much of :math:`H`'s structure is captured by :math:`M` +so that the condition number :math:`\kappa(HM^{-1})` is low, and the +computational cost of constructing and using :math:`M`. The ideal +preconditioner would be one for which :math:`\kappa(M^{-1}A) +=1`. :math:`M=A` achieves this, but it is not a practical choice, as +applying this preconditioner would require solving a linear system +equivalent to the unpreconditioned problem. It is usually the case +that the more information :math:`M` has about :math:`H`, the more +expensive it is use. For example, Incomplete Cholesky factorization +based preconditioners have much better convergence behavior than the +Jacobi preconditioner, but are also much more expensive. + +The simplest of all preconditioners is the diagonal or Jacobi +preconditioner, i.e., :math:`M=\operatorname{diag}(A)`, which for +block structured matrices like :math:`H` can be generalized to the +block Jacobi preconditioner. Ceres implements the block Jacobi +preconditioner and refers to it as ``JACOBI``. When used with +:ref:`section-cgnr` it refers to the block diagonal of :math:`H` and +when used with :ref:`section-iterative_schur` it refers to the block +diagonal of :math:`B` [Mandel]_. + +Another obvious choice for :ref:`section-iterative_schur` is the block +diagonal of the Schur complement matrix :math:`S`, i.e, the block +Jacobi preconditioner for :math:`S`. Ceres implements it and refers to +is as the ``SCHUR_JACOBI`` preconditioner. + +For bundle adjustment problems arising in reconstruction from +community photo collections, more effective preconditioners can be +constructed by analyzing and exploiting the camera-point visibility +structure of the scene [KushalAgarwal]_. Ceres implements the two +visibility based preconditioners described by Kushal & Agarwal as +``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``. These are fairly new +preconditioners and Ceres' implementation of them is in its early +stages and is not as mature as the other preconditioners described +above. + +.. _section-ordering: + +Ordering +-------- + +The order in which variables are eliminated in a linear solver can +have a significant of impact on the efficiency and accuracy of the +method. For example when doing sparse Cholesky factorization, there +are matrices for which a good ordering will give a Cholesky factor +with :math:`O(n)` storage, where as a bad ordering will result in an +completely dense factor. + +Ceres allows the user to provide varying amounts of hints to the +solver about the variable elimination ordering to use. This can range +from no hints, where the solver is free to decide the best ordering +based on the user's choices like the linear solver being used, to an +exact order in which the variables should be eliminated, and a variety +of possibilities in between. + +Instances of the :class:`ParameterBlockOrdering` class are used to +communicate this information to Ceres. + +Formally an ordering is an ordered partitioning of the parameter +blocks. Each parameter block belongs to exactly one group, and each +group has a unique integer associated with it, that determines its +order in the set of groups. We call these groups *Elimination Groups* + +Given such an ordering, Ceres ensures that the parameter blocks in the +lowest numbered elimination group are eliminated first, and then the +parameter blocks in the next lowest numbered elimination group and so +on. Within each elimination group, Ceres is free to order the +parameter blocks as it chooses. For example, consider the linear system + +.. math:: + x + y &= 3\\ + 2x + 3y &= 7 + +There are two ways in which it can be solved. First eliminating +:math:`x` from the two equations, solving for :math:`y` and then back +substituting for :math:`x`, or first eliminating :math:`y`, solving +for :math:`x` and back substituting for :math:`y`. The user can +construct three orderings here. + +1. :math:`\{0: x\}, \{1: y\}` : Eliminate :math:`x` first. +2. :math:`\{0: y\}, \{1: x\}` : Eliminate :math:`y` first. +3. :math:`\{0: x, y\}` : Solver gets to decide the elimination order. + +Thus, to have Ceres determine the ordering automatically using +heuristics, put all the variables in the same elimination group. The +identity of the group does not matter. This is the same as not +specifying an ordering at all. To control the ordering for every +variable, create an elimination group per variable, ordering them in +the desired order. + +If the user is using one of the Schur solvers (``DENSE_SCHUR``, +``SPARSE_SCHUR``, ``ITERATIVE_SCHUR``) and chooses to specify an +ordering, it must have one important property. The lowest numbered +elimination group must form an independent set in the graph +corresponding to the Hessian, or in other words, no two parameter +blocks in in the first elimination group should co-occur in the same +residual block. For the best performance, this elimination group +should be as large as possible. For standard bundle adjustment +problems, this corresponds to the first elimination group containing +all the 3d points, and the second containing the all the cameras +parameter blocks. + +If the user leaves the choice to Ceres, then the solver uses an +approximate maximum independent set algorithm to identify the first +elimination group [LiSaad]_. + +.. _section-solver-options: + +:class:`Solver::Options` +======================== + +.. class:: Solver::Options + + :class:`Solver::Options` controls the overall behavior of the + solver. We list the various settings and their default values below. + +.. function:: bool Solver::Options::IsValid(string* error) const + + Validate the values in the options struct and returns true on + success. If there is a problem, the method returns false with + ``error`` containing a textual description of the cause. + +.. member:: MinimizerType Solver::Options::minimizer_type + + Default: ``TRUST_REGION`` + + Choose between ``LINE_SEARCH`` and ``TRUST_REGION`` algorithms. See + :ref:`section-trust-region-methods` and + :ref:`section-line-search-methods` for more details. + +.. member:: LineSearchDirectionType Solver::Options::line_search_direction_type + + Default: ``LBFGS`` + + Choices are ``STEEPEST_DESCENT``, ``NONLINEAR_CONJUGATE_GRADIENT``, + ``BFGS`` and ``LBFGS``. + +.. member:: LineSearchType Solver::Options::line_search_type + + Default: ``WOLFE`` + + Choices are ``ARMIJO`` and ``WOLFE`` (strong Wolfe conditions). + Note that in order for the assumptions underlying the ``BFGS`` and + ``LBFGS`` line search direction algorithms to be guaranteed to be + satisifed, the ``WOLFE`` line search should be used. + +.. member:: NonlinearConjugateGradientType Solver::Options::nonlinear_conjugate_gradient_type + + Default: ``FLETCHER_REEVES`` + + Choices are ``FLETCHER_REEVES``, ``POLAK_RIBIERE`` and + ``HESTENES_STIEFEL``. + +.. member:: int Solver::Options::max_lbfgs_rank + + Default: 20 + + The L-BFGS hessian approximation is a low rank approximation to the + inverse of the Hessian matrix. The rank of the approximation + determines (linearly) the space and time complexity of using the + approximation. Higher the rank, the better is the quality of the + approximation. The increase in quality is however is bounded for a + number of reasons. + + 1. The method only uses secant information and not actual + derivatives. + + 2. The Hessian approximation is constrained to be positive + definite. + + So increasing this rank to a large number will cost time and space + complexity without the corresponding increase in solution + quality. There are no hard and fast rules for choosing the maximum + rank. The best choice usually requires some problem specific + experimentation. + +.. member:: bool Solver::Options::use_approximate_eigenvalue_bfgs_scaling + + Default: ``false`` + + As part of the ``BFGS`` update step / ``LBFGS`` right-multiply + step, the initial inverse Hessian approximation is taken to be the + Identity. However, [Oren]_ showed that using instead :math:`I * + \gamma`, where :math:`\gamma` is a scalar chosen to approximate an + eigenvalue of the true inverse Hessian can result in improved + convergence in a wide variety of cases. Setting + ``use_approximate_eigenvalue_bfgs_scaling`` to true enables this + scaling in ``BFGS`` (before first iteration) and ``LBFGS`` (at each + iteration). + + Precisely, approximate eigenvalue scaling equates to + + .. math:: \gamma = \frac{y_k' s_k}{y_k' y_k} + + With: + + .. math:: y_k = \nabla f_{k+1} - \nabla f_k + .. math:: s_k = x_{k+1} - x_k + + Where :math:`f()` is the line search objective and :math:`x` the + vector of parameter values [NocedalWright]_. + + It is important to note that approximate eigenvalue scaling does + **not** *always* improve convergence, and that it can in fact + *significantly* degrade performance for certain classes of problem, + which is why it is disabled by default. In particular it can + degrade performance when the sensitivity of the problem to different + parameters varies significantly, as in this case a single scalar + factor fails to capture this variation and detrimentally downscales + parts of the Jacobian approximation which correspond to + low-sensitivity parameters. It can also reduce the robustness of the + solution to errors in the Jacobians. + +.. member:: LineSearchIterpolationType Solver::Options::line_search_interpolation_type + + Default: ``CUBIC`` + + Degree of the polynomial used to approximate the objective + function. Valid values are ``BISECTION``, ``QUADRATIC`` and + ``CUBIC``. + +.. member:: double Solver::Options::min_line_search_step_size + + The line search terminates if: + + .. math:: \|\Delta x_k\|_\infty < \text{min_line_search_step_size} + + where :math:`\|\cdot\|_\infty` refers to the max norm, and + :math:`\Delta x_k` is the step change in the parameter values at + the :math:`k`-th iteration. + +.. member:: double Solver::Options::line_search_sufficient_function_decrease + + Default: ``1e-4`` + + Solving the line search problem exactly is computationally + prohibitive. Fortunately, line search based optimization algorithms + can still guarantee convergence if instead of an exact solution, + the line search algorithm returns a solution which decreases the + value of the objective function sufficiently. More precisely, we + are looking for a step size s.t. + + .. math:: f(\text{step_size}) \le f(0) + \text{sufficient_decrease} * [f'(0) * \text{step_size}] + + This condition is known as the Armijo condition. + +.. member:: double Solver::Options::max_line_search_step_contraction + + Default: ``1e-3`` + + In each iteration of the line search, + + .. math:: \text{new_step_size} >= \text{max_line_search_step_contraction} * \text{step_size} + + Note that by definition, for contraction: + + .. math:: 0 < \text{max_step_contraction} < \text{min_step_contraction} < 1 + +.. member:: double Solver::Options::min_line_search_step_contraction + + Default: ``0.6`` + + In each iteration of the line search, + + .. math:: \text{new_step_size} <= \text{min_line_search_step_contraction} * \text{step_size} + + Note that by definition, for contraction: + + .. math:: 0 < \text{max_step_contraction} < \text{min_step_contraction} < 1 + +.. member:: int Solver::Options::max_num_line_search_step_size_iterations + + Default: ``20`` + + Maximum number of trial step size iterations during each line + search, if a step size satisfying the search conditions cannot be + found within this number of trials, the line search will stop. + + As this is an 'artificial' constraint (one imposed by the user, not + the underlying math), if ``WOLFE`` line search is being used, *and* + points satisfying the Armijo sufficient (function) decrease + condition have been found during the current search (in :math:`<=` + ``max_num_line_search_step_size_iterations``). Then, the step size + with the lowest function value which satisfies the Armijo condition + will be returned as the new valid step, even though it does *not* + satisfy the strong Wolfe conditions. This behaviour protects + against early termination of the optimizer at a sub-optimal point. + +.. member:: int Solver::Options::max_num_line_search_direction_restarts + + Default: ``5`` + + Maximum number of restarts of the line search direction algorithm + before terminating the optimization. Restarts of the line search + direction algorithm occur when the current algorithm fails to + produce a new descent direction. This typically indicates a + numerical failure, or a breakdown in the validity of the + approximations used. + +.. member:: double Solver::Options::line_search_sufficient_curvature_decrease + + Default: ``0.9`` + + The strong Wolfe conditions consist of the Armijo sufficient + decrease condition, and an additional requirement that the + step size be chosen s.t. the *magnitude* ('strong' Wolfe + conditions) of the gradient along the search direction + decreases sufficiently. Precisely, this second condition + is that we seek a step size s.t. + + .. math:: \|f'(\text{step_size})\| <= \text{sufficient_curvature_decrease} * \|f'(0)\| + + Where :math:`f()` is the line search objective and :math:`f'()` is the derivative + of :math:`f` with respect to the step size: :math:`\frac{d f}{d~\text{step size}}`. + +.. member:: double Solver::Options::max_line_search_step_expansion + + Default: ``10.0`` + + During the bracketing phase of a Wolfe line search, the step size + is increased until either a point satisfying the Wolfe conditions + is found, or an upper bound for a bracket containing a point + satisfying the conditions is found. Precisely, at each iteration + of the expansion: + + .. math:: \text{new_step_size} <= \text{max_step_expansion} * \text{step_size} + + By definition for expansion + + .. math:: \text{max_step_expansion} > 1.0 + +.. member:: TrustRegionStrategyType Solver::Options::trust_region_strategy_type + + Default: ``LEVENBERG_MARQUARDT`` + + The trust region step computation algorithm used by + Ceres. Currently ``LEVENBERG_MARQUARDT`` and ``DOGLEG`` are the two + valid choices. See :ref:`section-levenberg-marquardt` and + :ref:`section-dogleg` for more details. + +.. member:: DoglegType Solver::Options::dogleg_type + + Default: ``TRADITIONAL_DOGLEG`` + + Ceres supports two different dogleg strategies. + ``TRADITIONAL_DOGLEG`` method by Powell and the ``SUBSPACE_DOGLEG`` + method described by [ByrdSchnabel]_ . See :ref:`section-dogleg` + for more details. + +.. member:: bool Solver::Options::use_nonmonotonic_steps + + Default: ``false`` + + Relax the requirement that the trust-region algorithm take strictly + decreasing steps. See :ref:`section-non-monotonic-steps` for more + details. + +.. member:: int Solver::Options::max_consecutive_nonmonotonic_steps + + Default: ``5`` + + The window size used by the step selection algorithm to accept + non-monotonic steps. + +.. member:: int Solver::Options::max_num_iterations + + Default: ``50`` + + Maximum number of iterations for which the solver should run. + +.. member:: double Solver::Options::max_solver_time_in_seconds + + Default: ``1e6`` + Maximum amount of time for which the solver should run. + +.. member:: int Solver::Options::num_threads + + Default: ``1`` + + Number of threads used by Ceres to evaluate the Jacobian. + +.. member:: double Solver::Options::initial_trust_region_radius + + Default: ``1e4`` + + The size of the initial trust region. When the + ``LEVENBERG_MARQUARDT`` strategy is used, the reciprocal of this + number is the initial regularization parameter. + +.. member:: double Solver::Options::max_trust_region_radius + + Default: ``1e16`` + + The trust region radius is not allowed to grow beyond this value. + +.. member:: double Solver::Options::min_trust_region_radius + + Default: ``1e-32`` + + The solver terminates, when the trust region becomes smaller than + this value. + +.. member:: double Solver::Options::min_relative_decrease + + Default: ``1e-3`` + + Lower threshold for relative decrease before a trust-region step is + accepted. + +.. member:: double Solver::Options::min_lm_diagonal + + Default: ``1e6`` + + The ``LEVENBERG_MARQUARDT`` strategy, uses a diagonal matrix to + regularize the trust region step. This is the lower bound on + the values of this diagonal matrix. + +.. member:: double Solver::Options::max_lm_diagonal + + Default: ``1e32`` + + The ``LEVENBERG_MARQUARDT`` strategy, uses a diagonal matrix to + regularize the trust region step. This is the upper bound on + the values of this diagonal matrix. + +.. member:: int Solver::Options::max_num_consecutive_invalid_steps + + Default: ``5`` + + The step returned by a trust region strategy can sometimes be + numerically invalid, usually because of conditioning + issues. Instead of crashing or stopping the optimization, the + optimizer can go ahead and try solving with a smaller trust + region/better conditioned problem. This parameter sets the number + of consecutive retries before the minimizer gives up. + +.. member:: double Solver::Options::function_tolerance + + Default: ``1e-6`` + + Solver terminates if + + .. math:: \frac{|\Delta \text{cost}|}{\text{cost}} <= \text{function_tolerance} + + where, :math:`\Delta \text{cost}` is the change in objective + function value (up or down) in the current iteration of + Levenberg-Marquardt. + +.. member:: double Solver::Options::gradient_tolerance + + Default: ``1e-10`` + + Solver terminates if + + .. math:: \|x - \Pi \boxplus(x, -g(x))\|_\infty <= \text{gradient_tolerance} + + where :math:`\|\cdot\|_\infty` refers to the max norm, :math:`\Pi` + is projection onto the bounds constraints and :math:`\boxplus` is + Plus operation for the overall local parameterization associated + with the parameter vector. + +.. member:: double Solver::Options::parameter_tolerance + + Default: ``1e-8`` + + Solver terminates if + + .. math:: \|\Delta x\| <= (\|x\| + \text{parameter_tolerance}) * \text{parameter_tolerance} + + where :math:`\Delta x` is the step computed by the linear solver in + the current iteration. + +.. member:: LinearSolverType Solver::Options::linear_solver_type + + Default: ``SPARSE_NORMAL_CHOLESKY`` / ``DENSE_QR`` + + Type of linear solver used to compute the solution to the linear + least squares problem in each iteration of the Levenberg-Marquardt + algorithm. If Ceres is built with support for ``SuiteSparse`` or + ``CXSparse`` or ``Eigen``'s sparse Cholesky factorization, the + default is ``SPARSE_NORMAL_CHOLESKY``, it is ``DENSE_QR`` + otherwise. + +.. member:: PreconditionerType Solver::Options::preconditioner_type + + Default: ``JACOBI`` + + The preconditioner used by the iterative linear solver. The default + is the block Jacobi preconditioner. Valid values are (in increasing + order of complexity) ``IDENTITY``, ``JACOBI``, ``SCHUR_JACOBI``, + ``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``. See + :ref:`section-preconditioner` for more details. + +.. member:: VisibilityClusteringType Solver::Options::visibility_clustering_type + + Default: ``CANONICAL_VIEWS`` + + Type of clustering algorithm to use when constructing a visibility + based preconditioner. The original visibility based preconditioning + paper and implementation only used the canonical views algorithm. + + This algorithm gives high quality results but for large dense + graphs can be particularly expensive. As its worst case complexity + is cubic in size of the graph. + + Another option is to use ``SINGLE_LINKAGE`` which is a simple + thresholded single linkage clustering algorithm that only pays + attention to tightly coupled blocks in the Schur complement. This + is a fast algorithm that works well. + + The optimal choice of the clustering algorithm depends on the + sparsity structure of the problem, but generally speaking we + recommend that you try ``CANONICAL_VIEWS`` first and if it is too + expensive try ``SINGLE_LINKAGE``. + +.. member:: DenseLinearAlgebraLibrary Solver::Options::dense_linear_algebra_library_type + + Default:``EIGEN`` + + Ceres supports using multiple dense linear algebra libraries for + dense matrix factorizations. Currently ``EIGEN`` and ``LAPACK`` are + the valid choices. ``EIGEN`` is always available, ``LAPACK`` refers + to the system ``BLAS + LAPACK`` library which may or may not be + available. + + This setting affects the ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` + and ``DENSE_SCHUR`` solvers. For small to moderate sized probem + ``EIGEN`` is a fine choice but for large problems, an optimized + ``LAPACK + BLAS`` implementation can make a substantial difference + in performance. + +.. member:: SparseLinearAlgebraLibrary Solver::Options::sparse_linear_algebra_library_type + + Default: The highest available according to: ``SUITE_SPARSE`` > + ``CX_SPARSE`` > ``EIGEN_SPARSE`` > ``NO_SPARSE`` + + Ceres supports the use of three sparse linear algebra libraries, + ``SuiteSparse``, which is enabled by setting this parameter to + ``SUITE_SPARSE``, ``CXSparse``, which can be selected by setting + this parameter to ``CX_SPARSE`` and ``Eigen`` which is enabled by + setting this parameter to ``EIGEN_SPARSE``. Lastly, ``NO_SPARSE`` + means that no sparse linear solver should be used; note that this is + irrespective of whether Ceres was compiled with support for one. + + ``SuiteSparse`` is a sophisticated and complex sparse linear + algebra library and should be used in general. + + If your needs/platforms prevent you from using ``SuiteSparse``, + consider using ``CXSparse``, which is a much smaller, easier to + build library. As can be expected, its performance on large + problems is not comparable to that of ``SuiteSparse``. + + Last but not the least you can use the sparse linear algebra + routines in ``Eigen``. Currently the performance of this library is + the poorest of the three. But this should change in the near + future. + + Another thing to consider here is that the sparse Cholesky + factorization libraries in Eigen are licensed under ``LGPL`` and + building Ceres with support for ``EIGEN_SPARSE`` will result in an + LGPL licensed library (since the corresponding code from Eigen is + compiled into the library). + + The upside is that you do not need to build and link to an external + library to use ``EIGEN_SPARSE``. + +.. member:: int Solver::Options::num_linear_solver_threads + + Default: ``1`` + + Number of threads used by the linear solver. + +.. member:: shared_ptr Solver::Options::linear_solver_ordering + + Default: ``NULL`` + + An instance of the ordering object informs the solver about the + desired order in which parameter blocks should be eliminated by the + linear solvers. See section~\ref{sec:ordering`` for more details. + + If ``NULL``, the solver is free to choose an ordering that it + thinks is best. + + See :ref:`section-ordering` for more details. + +.. member:: bool Solver::Options::use_explicit_schur_complement + + Default: ``false`` + + Use an explicitly computed Schur complement matrix with + ``ITERATIVE_SCHUR``. + + By default this option is disabled and ``ITERATIVE_SCHUR`` + evaluates evaluates matrix-vector products between the Schur + complement and a vector implicitly by exploiting the algebraic + expression for the Schur complement. + + The cost of this evaluation scales with the number of non-zeros in + the Jacobian. + + For small to medium sized problems there is a sweet spot where + computing the Schur complement is cheap enough that it is much more + efficient to explicitly compute it and use it for evaluating the + matrix-vector products. + + Enabling this option tells ``ITERATIVE_SCHUR`` to use an explicitly + computed Schur complement. This can improve the performance of the + ``ITERATIVE_SCHUR`` solver significantly. + + .. NOTE: + + This option can only be used with the ``SCHUR_JACOBI`` + preconditioner. + +.. member:: bool Solver::Options::use_post_ordering + + Default: ``false`` + + Sparse Cholesky factorization algorithms use a fill-reducing + ordering to permute the columns of the Jacobian matrix. There are + two ways of doing this. + + 1. Compute the Jacobian matrix in some order and then have the + factorization algorithm permute the columns of the Jacobian. + + 2. Compute the Jacobian with its columns already permuted. + + The first option incurs a significant memory penalty. The + factorization algorithm has to make a copy of the permuted Jacobian + matrix, thus Ceres pre-permutes the columns of the Jacobian matrix + and generally speaking, there is no performance penalty for doing + so. + + In some rare cases, it is worth using a more complicated reordering + algorithm which has slightly better runtime performance at the + expense of an extra copy of the Jacobian matrix. Setting + ``use_postordering`` to ``true`` enables this tradeoff. + +.. member:: bool Solver::Options::dynamic_sparsity + + Some non-linear least squares problems are symbolically dense but + numerically sparse. i.e. at any given state only a small number of + Jacobian entries are non-zero, but the position and number of + non-zeros is different depending on the state. For these problems + it can be useful to factorize the sparse jacobian at each solver + iteration instead of including all of the zero entries in a single + general factorization. + + If your problem does not have this property (or you do not know), + then it is probably best to keep this false, otherwise it will + likely lead to worse performance. + + This setting only affects the `SPARSE_NORMAL_CHOLESKY` solver. + +.. member:: int Solver::Options::min_linear_solver_iterations + + Default: ``0`` + + Minimum number of iterations used by the linear solver. This only + makes sense when the linear solver is an iterative solver, e.g., + ``ITERATIVE_SCHUR`` or ``CGNR``. + +.. member:: int Solver::Options::max_linear_solver_iterations + + Default: ``500`` + + Minimum number of iterations used by the linear solver. This only + makes sense when the linear solver is an iterative solver, e.g., + ``ITERATIVE_SCHUR`` or ``CGNR``. + +.. member:: double Solver::Options::eta + + Default: ``1e-1`` + + Forcing sequence parameter. The truncated Newton solver uses this + number to control the relative accuracy with which the Newton step + is computed. This constant is passed to + ``ConjugateGradientsSolver`` which uses it to terminate the + iterations when + + .. math:: \frac{Q_i - Q_{i-1}}{Q_i} < \frac{\eta}{i} + +.. member:: bool Solver::Options::jacobi_scaling + + Default: ``true`` + + ``true`` means that the Jacobian is scaled by the norm of its + columns before being passed to the linear solver. This improves the + numerical conditioning of the normal equations. + +.. member:: bool Solver::Options::use_inner_iterations + + Default: ``false`` + + Use a non-linear version of a simplified variable projection + algorithm. Essentially this amounts to doing a further optimization + on each Newton/Trust region step using a coordinate descent + algorithm. For more details, see :ref:`section-inner-iterations`. + +.. member:: double Solver::Options::inner_iteration_tolerance + + Default: ``1e-3`` + + Generally speaking, inner iterations make significant progress in + the early stages of the solve and then their contribution drops + down sharply, at which point the time spent doing inner iterations + is not worth it. + + Once the relative decrease in the objective function due to inner + iterations drops below ``inner_iteration_tolerance``, the use of + inner iterations in subsequent trust region minimizer iterations is + disabled. + +.. member:: shared_ptr Solver::Options::inner_iteration_ordering + + Default: ``NULL`` + + If :member:`Solver::Options::use_inner_iterations` true, then the + user has two choices. + + 1. Let the solver heuristically decide which parameter blocks to + optimize in each inner iteration. To do this, set + :member:`Solver::Options::inner_iteration_ordering` to ``NULL``. + + 2. Specify a collection of of ordered independent sets. The lower + numbered groups are optimized before the higher number groups + during the inner optimization phase. Each group must be an + independent set. Not all parameter blocks need to be included in + the ordering. + + See :ref:`section-ordering` for more details. + +.. member:: LoggingType Solver::Options::logging_type + + Default: ``PER_MINIMIZER_ITERATION`` + +.. member:: bool Solver::Options::minimizer_progress_to_stdout + + Default: ``false`` + + By default the :class:`Minimizer` progress is logged to ``STDERR`` + depending on the ``vlog`` level. If this flag is set to true, and + :member:`Solver::Options::logging_type` is not ``SILENT``, the logging + output is sent to ``STDOUT``. + + For ``TRUST_REGION_MINIMIZER`` the progress display looks like + + .. code-block:: bash + + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 4.185660e+06 0.00e+00 1.09e+08 0.00e+00 0.00e+00 1.00e+04 0 7.59e-02 3.37e-01 + 1 1.062590e+05 4.08e+06 8.99e+06 5.36e+02 9.82e-01 3.00e+04 1 1.65e-01 5.03e-01 + 2 4.992817e+04 5.63e+04 8.32e+06 3.19e+02 6.52e-01 3.09e+04 1 1.45e-01 6.48e-01 + + Here + + #. ``cost`` is the value of the objective function. + #. ``cost_change`` is the change in the value of the objective + function if the step computed in this iteration is accepted. + #. ``|gradient|`` is the max norm of the gradient. + #. ``|step|`` is the change in the parameter vector. + #. ``tr_ratio`` is the ratio of the actual change in the objective + function value to the change in the value of the trust + region model. + #. ``tr_radius`` is the size of the trust region radius. + #. ``ls_iter`` is the number of linear solver iterations used to + compute the trust region step. For direct/factorization based + solvers it is always 1, for iterative solvers like + ``ITERATIVE_SCHUR`` it is the number of iterations of the + Conjugate Gradients algorithm. + #. ``iter_time`` is the time take by the current iteration. + #. ``total_time`` is the total time taken by the minimizer. + + For ``LINE_SEARCH_MINIMIZER`` the progress display looks like + + .. code-block:: bash + + 0: f: 2.317806e+05 d: 0.00e+00 g: 3.19e-01 h: 0.00e+00 s: 0.00e+00 e: 0 it: 2.98e-02 tt: 8.50e-02 + 1: f: 2.312019e+05 d: 5.79e+02 g: 3.18e-01 h: 2.41e+01 s: 1.00e+00 e: 1 it: 4.54e-02 tt: 1.31e-01 + 2: f: 2.300462e+05 d: 1.16e+03 g: 3.17e-01 h: 4.90e+01 s: 2.54e-03 e: 1 it: 4.96e-02 tt: 1.81e-01 + + Here + + #. ``f`` is the value of the objective function. + #. ``d`` is the change in the value of the objective function if + the step computed in this iteration is accepted. + #. ``g`` is the max norm of the gradient. + #. ``h`` is the change in the parameter vector. + #. ``s`` is the optimal step length computed by the line search. + #. ``it`` is the time take by the current iteration. + #. ``tt`` is the total time taken by the minimizer. + +.. member:: vector Solver::Options::trust_region_minimizer_iterations_to_dump + + Default: ``empty`` + + List of iterations at which the trust region minimizer should dump + the trust region problem. Useful for testing and benchmarking. If + ``empty``, no problems are dumped. + +.. member:: string Solver::Options::trust_region_problem_dump_directory + + Default: ``/tmp`` + + Directory to which the problems should be written to. Should be + non-empty if + :member:`Solver::Options::trust_region_minimizer_iterations_to_dump` is + non-empty and + :member:`Solver::Options::trust_region_problem_dump_format_type` is not + ``CONSOLE``. + +.. member:: DumpFormatType Solver::Options::trust_region_problem_dump_format + + Default: ``TEXTFILE`` + + The format in which trust region problems should be logged when + :member:`Solver::Options::trust_region_minimizer_iterations_to_dump` + is non-empty. There are three options: + + * ``CONSOLE`` prints the linear least squares problem in a human + readable format to ``stderr``. The Jacobian is printed as a + dense matrix. The vectors :math:`D`, :math:`x` and :math:`f` are + printed as dense vectors. This should only be used for small + problems. + + * ``TEXTFILE`` Write out the linear least squares problem to the + directory pointed to by + :member:`Solver::Options::trust_region_problem_dump_directory` as + text files which can be read into ``MATLAB/Octave``. The Jacobian + is dumped as a text file containing :math:`(i,j,s)` triplets, the + vectors :math:`D`, `x` and `f` are dumped as text files + containing a list of their values. + + A ``MATLAB/Octave`` script called + ``ceres_solver_iteration_???.m`` is also output, which can be + used to parse and load the problem into memory. + +.. member:: bool Solver::Options::check_gradients + + Default: ``false`` + + Check all Jacobians computed by each residual block with finite + differences. This is expensive since it involves computing the + derivative by normal means (e.g. user specified, autodiff, etc), + then also computing it using finite differences. The results are + compared, and if they differ substantially, the optimization fails + and the details are stored in the solver summary. + +.. member:: double Solver::Options::gradient_check_relative_precision + + Default: ``1e08`` + + Precision to check for in the gradient checker. If the relative + difference between an element in a Jacobian exceeds this number, + then the Jacobian for that cost term is dumped. + +.. member:: double Solver::Options::gradient_check_numeric_derivative_relative_step_size + + Default: ``1e-6`` + + .. NOTE:: + + This option only applies to the numeric differentiation used for + checking the user provided derivatives when when + `Solver::Options::check_gradients` is true. If you are using + :class:`NumericDiffCostFunction` and are interested in changing + the step size for numeric differentiation in your cost function, + please have a look at :class:`NumericDiffOptions`. + + Relative shift used for taking numeric derivatives when + `Solver::Options::check_gradients` is `true`. + + For finite differencing, each dimension is evaluated at slightly + shifted values, e.g., for forward differences, the numerical + derivative is + + .. math:: + + \delta &= gradient\_check\_numeric\_derivative\_relative\_step\_size\\ + \Delta f &= \frac{f((1 + \delta) x) - f(x)}{\delta x} + + The finite differencing is done along each dimension. The reason to + use a relative (rather than absolute) step size is that this way, + numeric differentiation works for functions where the arguments are + typically large (e.g. :math:`10^9`) and when the values are small + (e.g. :math:`10^{-5}`). It is possible to construct *torture cases* + which break this finite difference heuristic, but they do not come + up often in practice. + +.. member:: vector Solver::Options::callbacks + + Callbacks that are executed at the end of each iteration of the + :class:`Minimizer`. They are executed in the order that they are + specified in this vector. By default, parameter blocks are updated + only at the end of the optimization, i.e., when the + :class:`Minimizer` terminates. This behavior is controlled by + :member:`Solver::Options::update_state_every_variable`. If the user + wishes to have access to the update parameter blocks when his/her + callbacks are executed, then set + :member:`Solver::Options::update_state_every_iteration` to true. + + The solver does NOT take ownership of these pointers. + +.. member:: bool Solver::Options::update_state_every_iteration + + Default: ``false`` + + Normally the parameter blocks are only updated when the solver + terminates. Setting this to true update them in every + iteration. This setting is useful when building an interactive + application using Ceres and using an :class:`IterationCallback`. + +:class:`ParameterBlockOrdering` +=============================== + +.. class:: ParameterBlockOrdering + + ``ParameterBlockOrdering`` is a class for storing and manipulating + an ordered collection of groups/sets with the following semantics: + + Group IDs are non-negative integer values. Elements are any type + that can serve as a key in a map or an element of a set. + + An element can only belong to one group at a time. A group may + contain an arbitrary number of elements. + + Groups are ordered by their group id. + +.. function:: bool ParameterBlockOrdering::AddElementToGroup(const double* element, const int group) + + Add an element to a group. If a group with this id does not exist, + one is created. This method can be called any number of times for + the same element. Group ids should be non-negative numbers. Return + value indicates if adding the element was a success. + +.. function:: void ParameterBlockOrdering::Clear() + + Clear the ordering. + +.. function:: bool ParameterBlockOrdering::Remove(const double* element) + + Remove the element, no matter what group it is in. If the element + is not a member of any group, calling this method will result in a + crash. Return value indicates if the element was actually removed. + +.. function:: void ParameterBlockOrdering::Reverse() + + Reverse the order of the groups in place. + +.. function:: int ParameterBlockOrdering::GroupId(const double* element) const + + Return the group id for the element. If the element is not a member + of any group, return -1. + +.. function:: bool ParameterBlockOrdering::IsMember(const double* element) const + + True if there is a group containing the parameter block. + +.. function:: int ParameterBlockOrdering::GroupSize(const int group) const + + This function always succeeds, i.e., implicitly there exists a + group for every integer. + +.. function:: int ParameterBlockOrdering::NumElements() const + + Number of elements in the ordering. + +.. function:: int ParameterBlockOrdering::NumGroups() const + + Number of groups with one or more elements. + + +:class:`IterationCallback` +========================== + +.. class:: IterationSummary + + :class:`IterationSummary` describes the state of the minimizer at + the end of each iteration. + +.. member:: int32 IterationSummary::iteration + + Current iteration number. + +.. member:: bool IterationSummary::step_is_valid + + Step was numerically valid, i.e., all values are finite and the + step reduces the value of the linearized model. + + **Note**: :member:`IterationSummary::step_is_valid` is `false` + when :member:`IterationSummary::iteration` = 0. + +.. member:: bool IterationSummary::step_is_nonmonotonic + + Step did not reduce the value of the objective function + sufficiently, but it was accepted because of the relaxed + acceptance criterion used by the non-monotonic trust region + algorithm. + + **Note**: :member:`IterationSummary::step_is_nonmonotonic` is + `false` when when :member:`IterationSummary::iteration` = 0. + +.. member:: bool IterationSummary::step_is_successful + + Whether or not the minimizer accepted this step or not. + + If the ordinary trust region algorithm is used, this means that the + relative reduction in the objective function value was greater than + :member:`Solver::Options::min_relative_decrease`. However, if the + non-monotonic trust region algorithm is used + (:member:`Solver::Options::use_nonmonotonic_steps` = `true`), then + even if the relative decrease is not sufficient, the algorithm may + accept the step and the step is declared successful. + + **Note**: :member:`IterationSummary::step_is_successful` is `false` + when when :member:`IterationSummary::iteration` = 0. + +.. member:: double IterationSummary::cost + + Value of the objective function. + +.. member:: double IterationSummary::cost_change + + Change in the value of the objective function in this + iteration. This can be positive or negative. + +.. member:: double IterationSummary::gradient_max_norm + + Infinity norm of the gradient vector. + +.. member:: double IterationSummary::gradient_norm + + 2-norm of the gradient vector. + +.. member:: double IterationSummary::step_norm + + 2-norm of the size of the step computed in this iteration. + +.. member:: double IterationSummary::relative_decrease + + For trust region algorithms, the ratio of the actual change in cost + and the change in the cost of the linearized approximation. + + This field is not used when a linear search minimizer is used. + +.. member:: double IterationSummary::trust_region_radius + + Size of the trust region at the end of the current iteration. For + the Levenberg-Marquardt algorithm, the regularization parameter is + 1.0 / member::`IterationSummary::trust_region_radius`. + +.. member:: double IterationSummary::eta + + For the inexact step Levenberg-Marquardt algorithm, this is the + relative accuracy with which the step is solved. This number is + only applicable to the iterative solvers capable of solving linear + systems inexactly. Factorization-based exact solvers always have an + eta of 0.0. + +.. member:: double IterationSummary::step_size + + Step sized computed by the line search algorithm. + + This field is not used when a trust region minimizer is used. + +.. member:: int IterationSummary::line_search_function_evaluations + + Number of function evaluations used by the line search algorithm. + + This field is not used when a trust region minimizer is used. + +.. member:: int IterationSummary::linear_solver_iterations + + Number of iterations taken by the linear solver to solve for the + trust region step. + + Currently this field is not used when a line search minimizer is + used. + +.. member:: double IterationSummary::iteration_time_in_seconds + + Time (in seconds) spent inside the minimizer loop in the current + iteration. + +.. member:: double IterationSummary::step_solver_time_in_seconds + + Time (in seconds) spent inside the trust region step solver. + +.. member:: double IterationSummary::cumulative_time_in_seconds + + Time (in seconds) since the user called Solve(). + + +.. class:: IterationCallback + + Interface for specifying callbacks that are executed at the end of + each iteration of the minimizer. + + .. code-block:: c++ + + class IterationCallback { + public: + virtual ~IterationCallback() {} + virtual CallbackReturnType operator()(const IterationSummary& summary) = 0; + }; + + + The solver uses the return value of ``operator()`` to decide whether + to continue solving or to terminate. The user can return three + values. + + #. ``SOLVER_ABORT`` indicates that the callback detected an abnormal + situation. The solver returns without updating the parameter + blocks (unless ``Solver::Options::update_state_every_iteration`` is + set true). Solver returns with ``Solver::Summary::termination_type`` + set to ``USER_FAILURE``. + + #. ``SOLVER_TERMINATE_SUCCESSFULLY`` indicates that there is no need + to optimize anymore (some user specified termination criterion + has been met). Solver returns with + ``Solver::Summary::termination_type``` set to ``USER_SUCCESS``. + + #. ``SOLVER_CONTINUE`` indicates that the solver should continue + optimizing. + + For example, the following :class:`IterationCallback` is used + internally by Ceres to log the progress of the optimization. + + .. code-block:: c++ + + class LoggingCallback : public IterationCallback { + public: + explicit LoggingCallback(bool log_to_stdout) + : log_to_stdout_(log_to_stdout) {} + + ~LoggingCallback() {} + + CallbackReturnType operator()(const IterationSummary& summary) { + const char* kReportRowFormat = + "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e " + "rho:% 3.2e mu:% 3.2e eta:% 3.2e li:% 3d"; + string output = StringPrintf(kReportRowFormat, + summary.iteration, + summary.cost, + summary.cost_change, + summary.gradient_max_norm, + summary.step_norm, + summary.relative_decrease, + summary.trust_region_radius, + summary.eta, + summary.linear_solver_iterations); + if (log_to_stdout_) { + cout << output << endl; + } else { + VLOG(1) << output; + } + return SOLVER_CONTINUE; + } + + private: + const bool log_to_stdout_; + }; + + + +:class:`CRSMatrix` +================== + +.. class:: CRSMatrix + + A compressed row sparse matrix used primarily for communicating the + Jacobian matrix to the user. + +.. member:: int CRSMatrix::num_rows + + Number of rows. + +.. member:: int CRSMatrix::num_cols + + Number of columns. + +.. member:: vector CRSMatrix::rows + + :member:`CRSMatrix::rows` is a :member:`CRSMatrix::num_rows` + 1 + sized array that points into the :member:`CRSMatrix::cols` and + :member:`CRSMatrix::values` array. + +.. member:: vector CRSMatrix::cols + + :member:`CRSMatrix::cols` contain as many entries as there are + non-zeros in the matrix. + + For each row ``i``, ``cols[rows[i]]`` ... ``cols[rows[i + 1] - 1]`` + are the indices of the non-zero columns of row ``i``. + +.. member:: vector CRSMatrix::values + + :member:`CRSMatrix::values` contain as many entries as there are + non-zeros in the matrix. + + For each row ``i``, + ``values[rows[i]]`` ... ``values[rows[i + 1] - 1]`` are the values + of the non-zero columns of row ``i``. + +e.g., consider the 3x4 sparse matrix + +.. code-block:: c++ + + 0 10 0 4 + 0 2 -3 2 + 1 2 0 0 + +The three arrays will be: + +.. code-block:: c++ + + -row0- ---row1--- -row2- + rows = [ 0, 2, 5, 7] + cols = [ 1, 3, 1, 2, 3, 0, 1] + values = [10, 4, 2, -3, 2, 1, 2] + + +:class:`Solver::Summary` +======================== + +.. class:: Solver::Summary + + Summary of the various stages of the solver after termination. + +.. function:: string Solver::Summary::BriefReport() const + + A brief one line description of the state of the solver after + termination. + +.. function:: string Solver::Summary::FullReport() const + + A full multiline description of the state of the solver after + termination. + +.. function:: bool Solver::Summary::IsSolutionUsable() const + + Whether the solution returned by the optimization algorithm can be + relied on to be numerically sane. This will be the case if + `Solver::Summary:termination_type` is set to `CONVERGENCE`, + `USER_SUCCESS` or `NO_CONVERGENCE`, i.e., either the solver + converged by meeting one of the convergence tolerances or because + the user indicated that it had converged or it ran to the maximum + number of iterations or time. + +.. member:: MinimizerType Solver::Summary::minimizer_type + + Type of minimization algorithm used. + +.. member:: TerminationType Solver::Summary::termination_type + + The cause of the minimizer terminating. + +.. member:: string Solver::Summary::message + + Reason why the solver terminated. + +.. member:: double Solver::Summary::initial_cost + + Cost of the problem (value of the objective function) before the + optimization. + +.. member:: double Solver::Summary::final_cost + + Cost of the problem (value of the objective function) after the + optimization. + +.. member:: double Solver::Summary::fixed_cost + + The part of the total cost that comes from residual blocks that + were held fixed by the preprocessor because all the parameter + blocks that they depend on were fixed. + +.. member:: vector Solver::Summary::iterations + + :class:`IterationSummary` for each minimizer iteration in order. + +.. member:: int Solver::Summary::num_successful_steps + + Number of minimizer iterations in which the step was + accepted. Unless :member:`Solver::Options::use_non_monotonic_steps` + is `true` this is also the number of steps in which the objective + function value/cost went down. + +.. member:: int Solver::Summary::num_unsuccessful_steps + + Number of minimizer iterations in which the step was rejected + either because it did not reduce the cost enough or the step was + not numerically valid. + +.. member:: int Solver::Summary::num_inner_iteration_steps + + Number of times inner iterations were performed. + + .. member:: int Solver::Summary::num_line_search_steps + + Total number of iterations inside the line search algorithm across + all invocations. We call these iterations "steps" to distinguish + them from the outer iterations of the line search and trust region + minimizer algorithms which call the line search algorithm as a + subroutine. + +.. member:: double Solver::Summary::preprocessor_time_in_seconds + + Time (in seconds) spent in the preprocessor. + +.. member:: double Solver::Summary::minimizer_time_in_seconds + + Time (in seconds) spent in the Minimizer. + +.. member:: double Solver::Summary::postprocessor_time_in_seconds + + Time (in seconds) spent in the post processor. + +.. member:: double Solver::Summary::total_time_in_seconds + + Time (in seconds) spent in the solver. + +.. member:: double Solver::Summary::linear_solver_time_in_seconds + + Time (in seconds) spent in the linear solver computing the trust + region step. + +.. member:: double Solver::Summary::residual_evaluation_time_in_seconds + + Time (in seconds) spent evaluating the residual vector. + +.. member:: double Solver::Summary::jacobian_evaluation_time_in_seconds + + Time (in seconds) spent evaluating the Jacobian matrix. + +.. member:: double Solver::Summary::inner_iteration_time_in_seconds + + Time (in seconds) spent doing inner iterations. + +.. member:: int Solver::Summary::num_parameter_blocks + + Number of parameter blocks in the problem. + +.. member:: int Solver::Summary::num_parameters + + Number of parameters in the problem. + +.. member:: int Solver::Summary::num_effective_parameters + + Dimension of the tangent space of the problem (or the number of + columns in the Jacobian for the problem). This is different from + :member:`Solver::Summary::num_parameters` if a parameter block is + associated with a :class:`LocalParameterization`. + +.. member:: int Solver::Summary::num_residual_blocks + + Number of residual blocks in the problem. + +.. member:: int Solver::Summary::num_residuals + + Number of residuals in the problem. + +.. member:: int Solver::Summary::num_parameter_blocks_reduced + + Number of parameter blocks in the problem after the inactive and + constant parameter blocks have been removed. A parameter block is + inactive if no residual block refers to it. + +.. member:: int Solver::Summary::num_parameters_reduced + + Number of parameters in the reduced problem. + +.. member:: int Solver::Summary::num_effective_parameters_reduced + + Dimension of the tangent space of the reduced problem (or the + number of columns in the Jacobian for the reduced problem). This is + different from :member:`Solver::Summary::num_parameters_reduced` if + a parameter block in the reduced problem is associated with a + :class:`LocalParameterization`. + +.. member:: int Solver::Summary::num_residual_blocks_reduced + + Number of residual blocks in the reduced problem. + +.. member:: int Solver::Summary::num_residuals_reduced + + Number of residuals in the reduced problem. + +.. member:: int Solver::Summary::num_threads_given + + Number of threads specified by the user for Jacobian and residual + evaluation. + +.. member:: int Solver::Summary::num_threads_used + + Number of threads actually used by the solver for Jacobian and + residual evaluation. This number is not equal to + :member:`Solver::Summary::num_threads_given` if `OpenMP` is not + available. + +.. member:: int Solver::Summary::num_linear_solver_threads_given + + Number of threads specified by the user for solving the trust + region problem. + +.. member:: int Solver::Summary::num_linear_solver_threads_used + + Number of threads actually used by the solver for solving the trust + region problem. This number is not equal to + :member:`Solver::Summary::num_linear_solver_threads_given` if + `OpenMP` is not available. + +.. member:: LinearSolverType Solver::Summary::linear_solver_type_given + + Type of the linear solver requested by the user. + +.. member:: LinearSolverType Solver::Summary::linear_solver_type_used + + Type of the linear solver actually used. This may be different from + :member:`Solver::Summary::linear_solver_type_given` if Ceres + determines that the problem structure is not compatible with the + linear solver requested or if the linear solver requested by the + user is not available, e.g. The user requested + `SPARSE_NORMAL_CHOLESKY` but no sparse linear algebra library was + available. + +.. member:: vector Solver::Summary::linear_solver_ordering_given + + Size of the elimination groups given by the user as hints to the + linear solver. + +.. member:: vector Solver::Summary::linear_solver_ordering_used + + Size of the parameter groups used by the solver when ordering the + columns of the Jacobian. This maybe different from + :member:`Solver::Summary::linear_solver_ordering_given` if the user + left :member:`Solver::Summary::linear_solver_ordering_given` blank + and asked for an automatic ordering, or if the problem contains + some constant or inactive parameter blocks. + +.. member:: std::string Solver::Summary::schur_structure_given + + For Schur type linear solvers, this string describes the template + specialization which was detected in the problem and should be + used. + +.. member:: std::string Solver::Summary::schur_structure_used + + For Schur type linear solvers, this string describes the template + specialization that was actually instantiated and used. The reason + this will be different from + :member:`Solver::Summary::schur_structure_given` is because the + corresponding template specialization does not exist. + + Template specializations can be added to ceres by editing + ``internal/ceres/generate_template_specializations.py`` + +.. member:: bool Solver::Summary::inner_iterations_given + + `True` if the user asked for inner iterations to be used as part of + the optimization. + +.. member:: bool Solver::Summary::inner_iterations_used + + `True` if the user asked for inner iterations to be used as part of + the optimization and the problem structure was such that they were + actually performed. For example, in a problem with just one parameter + block, inner iterations are not performed. + +.. member:: vector inner_iteration_ordering_given + + Size of the parameter groups given by the user for performing inner + iterations. + +.. member:: vector inner_iteration_ordering_used + + Size of the parameter groups given used by the solver for + performing inner iterations. This maybe different from + :member:`Solver::Summary::inner_iteration_ordering_given` if the + user left :member:`Solver::Summary::inner_iteration_ordering_given` + blank and asked for an automatic ordering, or if the problem + contains some constant or inactive parameter blocks. + +.. member:: PreconditionerType Solver::Summary::preconditioner_type_given + + Type of the preconditioner requested by the user. + +.. member:: PreconditionerType Solver::Summary::preconditioner_type_used + + Type of the preconditioner actually used. This may be different + from :member:`Solver::Summary::linear_solver_type_given` if Ceres + determines that the problem structure is not compatible with the + linear solver requested or if the linear solver requested by the + user is not available. + +.. member:: VisibilityClusteringType Solver::Summary::visibility_clustering_type + + Type of clustering algorithm used for visibility based + preconditioning. Only meaningful when the + :member:`Solver::Summary::preconditioner_type` is + ``CLUSTER_JACOBI`` or ``CLUSTER_TRIDIAGONAL``. + +.. member:: TrustRegionStrategyType Solver::Summary::trust_region_strategy_type + + Type of trust region strategy. + +.. member:: DoglegType Solver::Summary::dogleg_type + + Type of dogleg strategy used for solving the trust region problem. + +.. member:: DenseLinearAlgebraLibraryType Solver::Summary::dense_linear_algebra_library_type + + Type of the dense linear algebra library used. + +.. member:: SparseLinearAlgebraLibraryType Solver::Summary::sparse_linear_algebra_library_type + + Type of the sparse linear algebra library used. + +.. member:: LineSearchDirectionType Solver::Summary::line_search_direction_type + + Type of line search direction used. + +.. member:: LineSearchType Solver::Summary::line_search_type + + Type of the line search algorithm used. + +.. member:: LineSearchInterpolationType Solver::Summary::line_search_interpolation_type + + When performing line search, the degree of the polynomial used to + approximate the objective function. + +.. member:: NonlinearConjugateGradientType Solver::Summary::nonlinear_conjugate_gradient_type + + If the line search direction is `NONLINEAR_CONJUGATE_GRADIENT`, + then this indicates the particular variant of non-linear conjugate + gradient used. + +.. member:: int Solver::Summary::max_lbfgs_rank + + If the type of the line search direction is `LBFGS`, then this + indicates the rank of the Hessian approximation. diff --git a/docs/source/nnls_tutorial.rst b/docs/source/nnls_tutorial.rst new file mode 100644 index 0000000..9c4e585 --- /dev/null +++ b/docs/source/nnls_tutorial.rst @@ -0,0 +1,1037 @@ +.. highlight:: c++ + +.. default-domain:: cpp + +.. _chapter-nnls_tutorial: + +======================== +Non-linear Least Squares +======================== + +Introduction +============ + +Ceres can solve bounds constrained robustified non-linear least +squares problems of the form + +.. math:: :label: ceresproblem + + \min_{\mathbf{x}} &\quad \frac{1}{2}\sum_{i} \rho_i\left(\left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2\right) \\ + \text{s.t.} &\quad l_j \le x_j \le u_j + +Problems of this form comes up in a broad range of areas across +science and engineering - from `fitting curves`_ in statistics, to +constructing `3D models from photographs`_ in computer vision. + +.. _fitting curves: http://en.wikipedia.org/wiki/Nonlinear_regression +.. _3D models from photographs: http://en.wikipedia.org/wiki/Bundle_adjustment + +In this chapter we will learn how to solve :eq:`ceresproblem` using +Ceres Solver. Full working code for all the examples described in this +chapter and more can be found in the `examples +`_ +directory. + +The expression +:math:`\rho_i\left(\left\|f_i\left(x_{i_1},...,x_{i_k}\right)\right\|^2\right)` +is known as a ``ResidualBlock``, where :math:`f_i(\cdot)` is a +:class:`CostFunction` that depends on the parameter blocks +:math:`\left[x_{i_1},... , x_{i_k}\right]`. In most optimization +problems small groups of scalars occur together. For example the three +components of a translation vector and the four components of the +quaternion that define the pose of a camera. We refer to such a group +of small scalars as a ``ParameterBlock``. Of course a +``ParameterBlock`` can just be a single parameter. :math:`l_j` and +:math:`u_j` are bounds on the parameter block :math:`x_j`. + +:math:`\rho_i` is a :class:`LossFunction`. A :class:`LossFunction` is +a scalar function that is used to reduce the influence of outliers on +the solution of non-linear least squares problems. + +As a special case, when :math:`\rho_i(x) = x`, i.e., the identity +function, and :math:`l_j = -\infty` and :math:`u_j = \infty` we get +the more familiar `non-linear least squares problem +`_. + +.. math:: \frac{1}{2}\sum_{i} \left\|f_i\left(x_{i_1}, ... ,x_{i_k}\right)\right\|^2. + :label: ceresproblem2 + +.. _section-hello-world: + +Hello World! +============ + +To get started, consider the problem of finding the minimum of the +function + +.. math:: \frac{1}{2}(10 -x)^2. + +This is a trivial problem, whose minimum is located at :math:`x = 10`, +but it is a good place to start to illustrate the basics of solving a +problem with Ceres [#f1]_. + +The first step is to write a functor that will evaluate this the +function :math:`f(x) = 10 - x`: + +.. code-block:: c++ + + struct CostFunctor { + template + bool operator()(const T* const x, T* residual) const { + residual[0] = T(10.0) - x[0]; + return true; + } + }; + +The important thing to note here is that ``operator()`` is a templated +method, which assumes that all its inputs and outputs are of some type +``T``. The use of templating here allows Ceres to call +``CostFunctor::operator()``, with ``T=double`` when just the value +of the residual is needed, and with a special type ``T=Jet`` when the +Jacobians are needed. In :ref:`section-derivatives` we will discuss the +various ways of supplying derivatives to Ceres in more detail. + +Once we have a way of computing the residual function, it is now time +to construct a non-linear least squares problem using it and have +Ceres solve it. + +.. code-block:: c++ + + int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // The variable to solve for with its initial value. + double initial_x = 5.0; + double x = initial_x; + + // Build the problem. + Problem problem; + + // Set up the only cost function (also known as residual). This uses + // auto-differentiation to obtain the derivative (jacobian). + CostFunction* cost_function = + new AutoDiffCostFunction(new CostFunctor); + problem.AddResidualBlock(cost_function, NULL, &x); + + // Run the solver! + Solver::Options options; + options.linear_solver_type = ceres::DENSE_QR; + options.minimizer_progress_to_stdout = true; + Solver::Summary summary; + Solve(options, &problem, &summary); + + std::cout << summary.BriefReport() << "\n"; + std::cout << "x : " << initial_x + << " -> " << x << "\n"; + return 0; + } + +:class:`AutoDiffCostFunction` takes a ``CostFunctor`` as input, +automatically differentiates it and gives it a :class:`CostFunction` +interface. + +Compiling and running `examples/helloworld.cc +`_ +gives us + +.. code-block:: bash + + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 4.512500e+01 0.00e+00 9.50e+00 0.00e+00 0.00e+00 1.00e+04 0 5.33e-04 3.46e-03 + 1 4.511598e-07 4.51e+01 9.50e-04 9.50e+00 1.00e+00 3.00e+04 1 5.00e-04 4.05e-03 + 2 5.012552e-16 4.51e-07 3.17e-08 9.50e-04 1.00e+00 9.00e+04 1 1.60e-05 4.09e-03 + Ceres Solver Report: Iterations: 2, Initial cost: 4.512500e+01, Final cost: 5.012552e-16, Termination: CONVERGENCE + x : 0.5 -> 10 + +Starting from a :math:`x=5`, the solver in two iterations goes to 10 +[#f2]_. The careful reader will note that this is a linear problem and +one linear solve should be enough to get the optimal value. The +default configuration of the solver is aimed at non-linear problems, +and for reasons of simplicity we did not change it in this example. It +is indeed possible to obtain the solution to this problem using Ceres +in one iteration. Also note that the solver did get very close to the +optimal function value of 0 in the very first iteration. We will +discuss these issues in greater detail when we talk about convergence +and parameter settings for Ceres. + +.. rubric:: Footnotes + +.. [#f1] `examples/helloworld.cc + `_ +.. [#f2] Actually the solver ran for three iterations, and it was + by looking at the value returned by the linear solver in the third + iteration, it observed that the update to the parameter block was too + small and declared convergence. Ceres only prints out the display at + the end of an iteration, and terminates as soon as it detects + convergence, which is why you only see two iterations here and not + three. + +.. _section-derivatives: + + +Derivatives +=========== + +Ceres Solver like most optimization packages, depends on being able to +evaluate the value and the derivatives of each term in the objective +function at arbitrary parameter values. Doing so correctly and +efficiently is essential to getting good results. Ceres Solver +provides a number of ways of doing so. You have already seen one of +them in action -- +Automatic Differentiation in `examples/helloworld.cc +`_ + +We now consider the other two possibilities. Analytic and numeric +derivatives. + + +Numeric Derivatives +------------------- + +In some cases, its not possible to define a templated cost functor, +for example when the evaluation of the residual involves a call to a +library function that you do not have control over. In such a +situation, numerical differentiation can be used. The user defines a +functor which computes the residual value and construct a +:class:`NumericDiffCostFunction` using it. e.g., for :math:`f(x) = 10 - x` +the corresponding functor would be + +.. code-block:: c++ + + struct NumericDiffCostFunctor { + bool operator()(const double* const x, double* residual) const { + residual[0] = 10.0 - x[0]; + return true; + } + }; + +Which is added to the :class:`Problem` as: + +.. code-block:: c++ + + CostFunction* cost_function = + new NumericDiffCostFunction( + new NumericDiffCostFunctor); + problem.AddResidualBlock(cost_function, NULL, &x); + +Notice the parallel from when we were using automatic differentiation + +.. code-block:: c++ + + CostFunction* cost_function = + new AutoDiffCostFunction(new CostFunctor); + problem.AddResidualBlock(cost_function, NULL, &x); + +The construction looks almost identical to the one used for automatic +differentiation, except for an extra template parameter that indicates +the kind of finite differencing scheme to be used for computing the +numerical derivatives [#f3]_. For more details see the documentation +for :class:`NumericDiffCostFunction`. + +**Generally speaking we recommend automatic differentiation instead of +numeric differentiation. The use of C++ templates makes automatic +differentiation efficient, whereas numeric differentiation is +expensive, prone to numeric errors, and leads to slower convergence.** + + +Analytic Derivatives +-------------------- + +In some cases, using automatic differentiation is not possible. For +example, it may be the case that it is more efficient to compute the +derivatives in closed form instead of relying on the chain rule used +by the automatic differentiation code. + +In such cases, it is possible to supply your own residual and jacobian +computation code. To do this, define a subclass of +:class:`CostFunction` or :class:`SizedCostFunction` if you know the +sizes of the parameters and residuals at compile time. Here for +example is ``SimpleCostFunction`` that implements :math:`f(x) = 10 - +x`. + +.. code-block:: c++ + + class QuadraticCostFunction : public ceres::SizedCostFunction<1, 1> { + public: + virtual ~QuadraticCostFunction() {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + const double x = parameters[0][0]; + residuals[0] = 10 - x; + + // Compute the Jacobian if asked for. + if (jacobians != NULL && jacobians[0] != NULL) { + jacobians[0][0] = -1; + } + return true; + } + }; + + +``SimpleCostFunction::Evaluate`` is provided with an input array of +``parameters``, an output array ``residuals`` for residuals and an +output array ``jacobians`` for Jacobians. The ``jacobians`` array is +optional, ``Evaluate`` is expected to check when it is non-null, and +if it is the case then fill it with the values of the derivative of +the residual function. In this case since the residual function is +linear, the Jacobian is constant [#f4]_ . + +As can be seen from the above code fragments, implementing +:class:`CostFunction` objects is a bit tedious. We recommend that +unless you have a good reason to manage the jacobian computation +yourself, you use :class:`AutoDiffCostFunction` or +:class:`NumericDiffCostFunction` to construct your residual blocks. + +More About Derivatives +---------------------- + +Computing derivatives is by far the most complicated part of using +Ceres, and depending on the circumstance the user may need more +sophisticated ways of computing derivatives. This section just +scratches the surface of how derivatives can be supplied to +Ceres. Once you are comfortable with using +:class:`NumericDiffCostFunction` and :class:`AutoDiffCostFunction` we +recommend taking a look at :class:`DynamicAutoDiffCostFunction`, +:class:`CostFunctionToFunctor`, :class:`NumericDiffFunctor` and +:class:`ConditionedCostFunction` for more advanced ways of +constructing and computing cost functions. + +.. rubric:: Footnotes + +.. [#f3] `examples/helloworld_numeric_diff.cc + `_. +.. [#f4] `examples/helloworld_analytic_diff.cc + `_. + + +.. _section-powell: + +Powell's Function +================= + +Consider now a slightly more complicated example -- the minimization +of Powell's function. Let :math:`x = \left[x_1, x_2, x_3, x_4 \right]` +and + +.. math:: + + \begin{align} + f_1(x) &= x_1 + 10x_2 \\ + f_2(x) &= \sqrt{5} (x_3 - x_4)\\ + f_3(x) &= (x_2 - 2x_3)^2\\ + f_4(x) &= \sqrt{10} (x_1 - x_4)^2\\ + F(x) &= \left[f_1(x),\ f_2(x),\ f_3(x),\ f_4(x) \right] + \end{align} + + +:math:`F(x)` is a function of four parameters, has four residuals +and we wish to find :math:`x` such that :math:`\frac{1}{2}\|F(x)\|^2` +is minimized. + +Again, the first step is to define functors that evaluate of the terms +in the objective functor. Here is the code for evaluating +:math:`f_4(x_1, x_4)`: + +.. code-block:: c++ + + struct F4 { + template + bool operator()(const T* const x1, const T* const x4, T* residual) const { + residual[0] = T(sqrt(10.0)) * (x1[0] - x4[0]) * (x1[0] - x4[0]); + return true; + } + }; + + +Similarly, we can define classes ``F1``, ``F2`` and ``F3`` to evaluate +:math:`f_1(x_1, x_2)`, :math:`f_2(x_3, x_4)` and :math:`f_3(x_2, x_3)` +respectively. Using these, the problem can be constructed as follows: + + +.. code-block:: c++ + + double x1 = 3.0; double x2 = -1.0; double x3 = 0.0; double x4 = 1.0; + + Problem problem; + + // Add residual terms to the problem using the using the autodiff + // wrapper to get the derivatives automatically. + problem.AddResidualBlock( + new AutoDiffCostFunction(new F1), NULL, &x1, &x2); + problem.AddResidualBlock( + new AutoDiffCostFunction(new F2), NULL, &x3, &x4); + problem.AddResidualBlock( + new AutoDiffCostFunction(new F3), NULL, &x2, &x3) + problem.AddResidualBlock( + new AutoDiffCostFunction(new F4), NULL, &x1, &x4); + + +Note that each ``ResidualBlock`` only depends on the two parameters +that the corresponding residual object depends on and not on all four +parameters. Compiling and running `examples/powell.cc +`_ +gives us: + +.. code-block:: bash + + Initial x1 = 3, x2 = -1, x3 = 0, x4 = 1 + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 1.075000e+02 0.00e+00 1.55e+02 0.00e+00 0.00e+00 1.00e+04 0 4.95e-04 2.30e-03 + 1 5.036190e+00 1.02e+02 2.00e+01 2.16e+00 9.53e-01 3.00e+04 1 4.39e-05 2.40e-03 + 2 3.148168e-01 4.72e+00 2.50e+00 6.23e-01 9.37e-01 9.00e+04 1 9.06e-06 2.43e-03 + 3 1.967760e-02 2.95e-01 3.13e-01 3.08e-01 9.37e-01 2.70e+05 1 8.11e-06 2.45e-03 + 4 1.229900e-03 1.84e-02 3.91e-02 1.54e-01 9.37e-01 8.10e+05 1 6.91e-06 2.48e-03 + 5 7.687123e-05 1.15e-03 4.89e-03 7.69e-02 9.37e-01 2.43e+06 1 7.87e-06 2.50e-03 + 6 4.804625e-06 7.21e-05 6.11e-04 3.85e-02 9.37e-01 7.29e+06 1 5.96e-06 2.52e-03 + 7 3.003028e-07 4.50e-06 7.64e-05 1.92e-02 9.37e-01 2.19e+07 1 5.96e-06 2.55e-03 + 8 1.877006e-08 2.82e-07 9.54e-06 9.62e-03 9.37e-01 6.56e+07 1 5.96e-06 2.57e-03 + 9 1.173223e-09 1.76e-08 1.19e-06 4.81e-03 9.37e-01 1.97e+08 1 7.87e-06 2.60e-03 + 10 7.333425e-11 1.10e-09 1.49e-07 2.40e-03 9.37e-01 5.90e+08 1 6.20e-06 2.63e-03 + 11 4.584044e-12 6.88e-11 1.86e-08 1.20e-03 9.37e-01 1.77e+09 1 6.91e-06 2.65e-03 + 12 2.865573e-13 4.30e-12 2.33e-09 6.02e-04 9.37e-01 5.31e+09 1 5.96e-06 2.67e-03 + 13 1.791438e-14 2.69e-13 2.91e-10 3.01e-04 9.37e-01 1.59e+10 1 7.15e-06 2.69e-03 + + Ceres Solver v1.12.0 Solve Report + ---------------------------------- + Original Reduced + Parameter blocks 4 4 + Parameters 4 4 + Residual blocks 4 4 + Residual 4 4 + + Minimizer TRUST_REGION + + Dense linear algebra library EIGEN + Trust region strategy LEVENBERG_MARQUARDT + + Given Used + Linear solver DENSE_QR DENSE_QR + Threads 1 1 + Linear solver threads 1 1 + + Cost: + Initial 1.075000e+02 + Final 1.791438e-14 + Change 1.075000e+02 + + Minimizer iterations 14 + Successful steps 14 + Unsuccessful steps 0 + + Time (in seconds): + Preprocessor 0.002 + + Residual evaluation 0.000 + Jacobian evaluation 0.000 + Linear solver 0.000 + Minimizer 0.001 + + Postprocessor 0.000 + Total 0.005 + + Termination: CONVERGENCE (Gradient tolerance reached. Gradient max norm: 3.642190e-11 <= 1.000000e-10) + + Final x1 = 0.000292189, x2 = -2.92189e-05, x3 = 4.79511e-05, x4 = 4.79511e-05 + +It is easy to see that the optimal solution to this problem is at +:math:`x_1=0, x_2=0, x_3=0, x_4=0` with an objective function value of +:math:`0`. In 10 iterations, Ceres finds a solution with an objective +function value of :math:`4\times 10^{-12}`. + +.. rubric:: Footnotes + +.. [#f5] `examples/powell.cc + `_. + + +.. _section-fitting: + +Curve Fitting +============= + +The examples we have seen until now are simple optimization problems +with no data. The original purpose of least squares and non-linear +least squares analysis was fitting curves to data. It is only +appropriate that we now consider an example of such a problem +[#f6]_. It contains data generated by sampling the curve :math:`y = +e^{0.3x + 0.1}` and adding Gaussian noise with standard deviation +:math:`\sigma = 0.2`. Let us fit some data to the curve + +.. math:: y = e^{mx + c}. + +We begin by defining a templated object to evaluate the +residual. There will be a residual for each observation. + +.. code-block:: c++ + + struct ExponentialResidual { + ExponentialResidual(double x, double y) + : x_(x), y_(y) {} + + template + bool operator()(const T* const m, const T* const c, T* residual) const { + residual[0] = T(y_) - exp(m[0] * T(x_) + c[0]); + return true; + } + + private: + // Observations for a sample. + const double x_; + const double y_; + }; + +Assuming the observations are in a :math:`2n` sized array called +``data`` the problem construction is a simple matter of creating a +:class:`CostFunction` for every observation. + + +.. code-block:: c++ + + double m = 0.0; + double c = 0.0; + + Problem problem; + for (int i = 0; i < kNumObservations; ++i) { + CostFunction* cost_function = + new AutoDiffCostFunction( + new ExponentialResidual(data[2 * i], data[2 * i + 1])); + problem.AddResidualBlock(cost_function, NULL, &m, &c); + } + +Compiling and running `examples/curve_fitting.cc +`_ +gives us: + +.. code-block:: bash + + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 1.211734e+02 0.00e+00 3.61e+02 0.00e+00 0.00e+00 1.00e+04 0 5.34e-04 2.56e-03 + 1 1.211734e+02 -2.21e+03 0.00e+00 7.52e-01 -1.87e+01 5.00e+03 1 4.29e-05 3.25e-03 + 2 1.211734e+02 -2.21e+03 0.00e+00 7.51e-01 -1.86e+01 1.25e+03 1 1.10e-05 3.28e-03 + 3 1.211734e+02 -2.19e+03 0.00e+00 7.48e-01 -1.85e+01 1.56e+02 1 1.41e-05 3.31e-03 + 4 1.211734e+02 -2.02e+03 0.00e+00 7.22e-01 -1.70e+01 9.77e+00 1 1.00e-05 3.34e-03 + 5 1.211734e+02 -7.34e+02 0.00e+00 5.78e-01 -6.32e+00 3.05e-01 1 1.00e-05 3.36e-03 + 6 3.306595e+01 8.81e+01 4.10e+02 3.18e-01 1.37e+00 9.16e-01 1 2.79e-05 3.41e-03 + 7 6.426770e+00 2.66e+01 1.81e+02 1.29e-01 1.10e+00 2.75e+00 1 2.10e-05 3.45e-03 + 8 3.344546e+00 3.08e+00 5.51e+01 3.05e-02 1.03e+00 8.24e+00 1 2.10e-05 3.48e-03 + 9 1.987485e+00 1.36e+00 2.33e+01 8.87e-02 9.94e-01 2.47e+01 1 2.10e-05 3.52e-03 + 10 1.211585e+00 7.76e-01 8.22e+00 1.05e-01 9.89e-01 7.42e+01 1 2.10e-05 3.56e-03 + 11 1.063265e+00 1.48e-01 1.44e+00 6.06e-02 9.97e-01 2.22e+02 1 2.60e-05 3.61e-03 + 12 1.056795e+00 6.47e-03 1.18e-01 1.47e-02 1.00e+00 6.67e+02 1 2.10e-05 3.64e-03 + 13 1.056751e+00 4.39e-05 3.79e-03 1.28e-03 1.00e+00 2.00e+03 1 2.10e-05 3.68e-03 + Ceres Solver Report: Iterations: 13, Initial cost: 1.211734e+02, Final cost: 1.056751e+00, Termination: CONVERGENCE + Initial m: 0 c: 0 + Final m: 0.291861 c: 0.131439 + +Starting from parameter values :math:`m = 0, c=0` with an initial +objective function value of :math:`121.173` Ceres finds a solution +:math:`m= 0.291861, c = 0.131439` with an objective function value of +:math:`1.05675`. These values are a bit different than the +parameters of the original model :math:`m=0.3, c= 0.1`, but this is +expected. When reconstructing a curve from noisy data, we expect to +see such deviations. Indeed, if you were to evaluate the objective +function for :math:`m=0.3, c=0.1`, the fit is worse with an objective +function value of :math:`1.082425`. The figure below illustrates the fit. + +.. figure:: least_squares_fit.png + :figwidth: 500px + :height: 400px + :align: center + + Least squares curve fitting. + + +.. rubric:: Footnotes + +.. [#f6] `examples/curve_fitting.cc + `_ + + +Robust Curve Fitting +===================== + +Now suppose the data we are given has some outliers, i.e., we have +some points that do not obey the noise model. If we were to use the +code above to fit such data, we would get a fit that looks as +below. Notice how the fitted curve deviates from the ground truth. + +.. figure:: non_robust_least_squares_fit.png + :figwidth: 500px + :height: 400px + :align: center + +To deal with outliers, a standard technique is to use a +:class:`LossFunction`. Loss functions reduce the influence of +residual blocks with high residuals, usually the ones corresponding to +outliers. To associate a loss function with a residual block, we change + +.. code-block:: c++ + + problem.AddResidualBlock(cost_function, NULL , &m, &c); + +to + +.. code-block:: c++ + + problem.AddResidualBlock(cost_function, new CauchyLoss(0.5) , &m, &c); + +:class:`CauchyLoss` is one of the loss functions that ships with Ceres +Solver. The argument :math:`0.5` specifies the scale of the loss +function. As a result, we get the fit below [#f7]_. Notice how the +fitted curve moves back closer to the ground truth curve. + +.. figure:: robust_least_squares_fit.png + :figwidth: 500px + :height: 400px + :align: center + + Using :class:`LossFunction` to reduce the effect of outliers on a + least squares fit. + + +.. rubric:: Footnotes + +.. [#f7] `examples/robust_curve_fitting.cc + `_ + + +Bundle Adjustment +================= + +One of the main reasons for writing Ceres was our need to solve large +scale bundle adjustment problems [HartleyZisserman]_, [Triggs]_. + +Given a set of measured image feature locations and correspondences, +the goal of bundle adjustment is to find 3D point positions and camera +parameters that minimize the reprojection error. This optimization +problem is usually formulated as a non-linear least squares problem, +where the error is the squared :math:`L_2` norm of the difference between +the observed feature location and the projection of the corresponding +3D point on the image plane of the camera. Ceres has extensive support +for solving bundle adjustment problems. + +Let us solve a problem from the `BAL +`_ dataset [#f8]_. + +The first step as usual is to define a templated functor that computes +the reprojection error/residual. The structure of the functor is +similar to the ``ExponentialResidual``, in that there is an +instance of this object responsible for each image observation. + +Each residual in a BAL problem depends on a three dimensional point +and a nine parameter camera. The nine parameters defining the camera +are: three for rotation as a Rodriques' axis-angle vector, three +for translation, one for focal length and two for radial distortion. +The details of this camera model can be found the `Bundler homepage +`_ and the `BAL homepage +`_. + +.. code-block:: c++ + + struct SnavelyReprojectionError { + SnavelyReprojectionError(double observed_x, double observed_y) + : observed_x(observed_x), observed_y(observed_y) {} + + template + bool operator()(const T* const camera, + const T* const point, + T* residuals) const { + // camera[0,1,2] are the angle-axis rotation. + T p[3]; + ceres::AngleAxisRotatePoint(camera, point, p); + // camera[3,4,5] are the translation. + p[0] += camera[3]; p[1] += camera[4]; p[2] += camera[5]; + + // Compute the center of distortion. The sign change comes from + // the camera model that Noah Snavely's Bundler assumes, whereby + // the camera coordinate system has a negative z axis. + T xp = - p[0] / p[2]; + T yp = - p[1] / p[2]; + + // Apply second and fourth order radial distortion. + const T& l1 = camera[7]; + const T& l2 = camera[8]; + T r2 = xp*xp + yp*yp; + T distortion = T(1.0) + r2 * (l1 + l2 * r2); + + // Compute final projected point position. + const T& focal = camera[6]; + T predicted_x = focal * distortion * xp; + T predicted_y = focal * distortion * yp; + + // The error is the difference between the predicted and observed position. + residuals[0] = predicted_x - T(observed_x); + residuals[1] = predicted_y - T(observed_y); + return true; + } + + // Factory to hide the construction of the CostFunction object from + // the client code. + static ceres::CostFunction* Create(const double observed_x, + const double observed_y) { + return (new ceres::AutoDiffCostFunction( + new SnavelyReprojectionError(observed_x, observed_y))); + } + + double observed_x; + double observed_y; + }; + + +Note that unlike the examples before, this is a non-trivial function +and computing its analytic Jacobian is a bit of a pain. Automatic +differentiation makes life much simpler. The function +:func:`AngleAxisRotatePoint` and other functions for manipulating +rotations can be found in ``include/ceres/rotation.h``. + +Given this functor, the bundle adjustment problem can be constructed +as follows: + +.. code-block:: c++ + + ceres::Problem problem; + for (int i = 0; i < bal_problem.num_observations(); ++i) { + ceres::CostFunction* cost_function = + SnavelyReprojectionError::Create( + bal_problem.observations()[2 * i + 0], + bal_problem.observations()[2 * i + 1]); + problem.AddResidualBlock(cost_function, + NULL /* squared loss */, + bal_problem.mutable_camera_for_observation(i), + bal_problem.mutable_point_for_observation(i)); + } + + +Notice that the problem construction for bundle adjustment is very +similar to the curve fitting example -- one term is added to the +objective function per observation. + +Since this is a large sparse problem (well large for ``DENSE_QR`` +anyways), one way to solve this problem is to set +:member:`Solver::Options::linear_solver_type` to +``SPARSE_NORMAL_CHOLESKY`` and call :member:`Solve`. And while this is +a reasonable thing to do, bundle adjustment problems have a special +sparsity structure that can be exploited to solve them much more +efficiently. Ceres provides three specialized solvers (collectively +known as Schur-based solvers) for this task. The example code uses the +simplest of them ``DENSE_SCHUR``. + +.. code-block:: c++ + + ceres::Solver::Options options; + options.linear_solver_type = ceres::DENSE_SCHUR; + options.minimizer_progress_to_stdout = true; + ceres::Solver::Summary summary; + ceres::Solve(options, &problem, &summary); + std::cout << summary.FullReport() << "\n"; + +For a more sophisticated bundle adjustment example which demonstrates +the use of Ceres' more advanced features including its various linear +solvers, robust loss functions and local parameterizations see +`examples/bundle_adjuster.cc +`_ + + +.. rubric:: Footnotes + +.. [#f8] `examples/simple_bundle_adjuster.cc + `_ + +Other Examples +============== + +Besides the examples in this chapter, the `example +`_ +directory contains a number of other examples: + +#. `bundle_adjuster.cc + `_ + shows how to use the various features of Ceres to solve bundle + adjustment problems. + +#. `circle_fit.cc + `_ + shows how to fit data to a circle. + +#. `ellipse_approximation.cc + `_ + fits points randomly distributed on an ellipse with an approximate + line segment contour. This is done by jointly optimizing the + control points of the line segment contour along with the preimage + positions for the data points. The purpose of this example is to + show an example use case for ``Solver::Options::dynamic_sparsity``, + and how it can benefit problems which are numerically dense but + dynamically sparse. + +#. `denoising.cc + `_ + implements image denoising using the `Fields of Experts + `_ + model. + +#. `nist.cc + `_ + implements and attempts to solves the `NIST + `_ + non-linear regression problems. + +#. `more_garbow_hillstrom.cc + `_ + A subset of the test problems from the paper + + Testing Unconstrained Optimization Software + Jorge J. More, Burton S. Garbow and Kenneth E. Hillstrom + ACM Transactions on Mathematical Software, 7(1), pp. 17-41, 1981 + + which were augmented with bounds and used for testing bounds + constrained optimization algorithms by + + A Trust Region Approach to Linearly Constrained Optimization + David M. Gay + Numerical Analysis (Griffiths, D.F., ed.), pp. 72-105 + Lecture Notes in Mathematics 1066, Springer Verlag, 1984. + + +#. `libmv_bundle_adjuster.cc + `_ + is the bundle adjustment algorithm used by `Blender `_/libmv. + +#. `libmv_homography.cc + `_ + This file demonstrates solving for a homography between two sets of + points and using a custom exit criterion by having a callback check + for image-space error. + +#. `robot_pose_mle.cc + `_ + This example demonstrates how to use the ``DynamicAutoDiffCostFunction`` + variant of CostFunction. The ``DynamicAutoDiffCostFunction`` is meant to + be used in cases where the number of parameter blocks or the sizes are not + known at compile time. + + This example simulates a robot traversing down a 1-dimension hallway with + noise odometry readings and noisy range readings of the end of the hallway. + By fusing the noisy odometry and sensor readings this example demonstrates + how to compute the maximum likelihood estimate (MLE) of the robot's pose at + each timestep. + +#. `slam/pose_graph_2d/pose_graph_2d.cc + `_ + The Simultaneous Localization and Mapping (SLAM) problem consists of building + a map of an unknown environment while simultaneously localizing against this + map. The main difficulty of this problem stems from not having any additional + external aiding information such as GPS. SLAM has been considered one of the + fundamental challenges of robotics. There are many resources on SLAM + [#f9]_. A pose graph optimization problem is one example of a SLAM + problem. The following explains how to formulate the pose graph based SLAM + problem in 2-Dimensions with relative pose constraints. + + Consider a robot moving in a 2-Dimensional plane. The robot has access to a + set of sensors such as wheel odometry or a laser range scanner. From these + raw measurements, we want to estimate the trajectory of the robot as well as + build a map of the environment. In order to reduce the computational + complexity of the problem, the pose graph approach abstracts the raw + measurements away. Specifically, it creates a graph of nodes which represent + the pose of the robot, and edges which represent the relative transformation + (delta position and orientation) between the two nodes. The edges are virtual + measurements derived from the raw sensor measurements, e.g. by integrating + the raw wheel odometry or aligning the laser range scans acquired from the + robot. A visualization of the resulting graph is shown below. + + .. figure:: slam2d.png + :figwidth: 500px + :height: 400px + :align: center + + Visual representation of a graph SLAM problem. + + The figure depicts the pose of the robot as the triangles, the measurements + are indicated by the connecting lines, and the loop closure measurements are + shown as dotted lines. Loop closures are measurements between non-sequential + robot states and they reduce the accumulation of error over time. The + following will describe the mathematical formulation of the pose graph + problem. + + The robot at timestamp :math:`t` has state :math:`x_t = [p^T, \psi]^T` where + :math:`p` is a 2D vector that represents the position in the plane and + :math:`\psi` is the orientation in radians. The measurement of the relative + transform between the robot state at two timestamps :math:`a` and :math:`b` + is given as: :math:`z_{ab} = [\hat{p}_{ab}^T, \hat{\psi}_{ab}]`. The residual + implemented in the Ceres cost function which computes the error between the + measurement and the predicted measurement is: + + .. math:: r_{ab} = + \left[ + \begin{array}{c} + R_a^T\left(p_b - p_a\right) - \hat{p}_{ab} \\ + \mathrm{Normalize}\left(\psi_b - \psi_a - \hat{\psi}_{ab}\right) + \end{array} + \right] + + where the function :math:`\mathrm{Normalize}()` normalizes the angle in the range + :math:`[-\pi,\pi)`, and :math:`R` is the rotation matrix given by + + .. math:: R_a = + \left[ + \begin{array}{cc} + \cos \psi_a & -\sin \psi_a \\ + \sin \psi_a & \cos \psi_a \\ + \end{array} + \right] + + To finish the cost function, we need to weight the residual by the + uncertainty of the measurement. Hence, we pre-multiply the residual by the + inverse square root of the covariance matrix for the measurement, + i.e. :math:`\Sigma_{ab}^{-\frac{1}{2}} r_{ab}` where :math:`\Sigma_{ab}` is + the covariance. + + Lastly, we use a local parameterization to normalize the orientation in the + range which is normalized between :math:`[-\pi,\pi)`. Specially, we define + the :member:`AngleLocalParameterization::operator()` function to be: + :math:`\mathrm{Normalize}(\psi + \delta \psi)`. + + This package includes an executable :member:`pose_graph_2d` that will read a + problem definition file. This executable can work with any 2D problem + definition that uses the g2o format. It would be relatively straightforward + to implement a new reader for a different format such as TORO or + others. :member:`pose_graph_2d` will print the Ceres solver full summary and + then output to disk the original and optimized poses (``poses_original.txt`` + and ``poses_optimized.txt``, respectively) of the robot in the following + format: + + .. code-block:: bash + + pose_id x y yaw_radians + pose_id x y yaw_radians + pose_id x y yaw_radians + + where ``pose_id`` is the corresponding integer ID from the file + definition. Note, the file will be sorted in ascending order for the + ``pose_id``. + + The executable :member:`pose_graph_2d` expects the first argument to be + the path to the problem definition. To run the executable, + + .. code-block:: bash + + /path/to/bin/pose_graph_2d /path/to/dataset/dataset.g2o + + A python script is provided to visualize the resulting output files. + + .. code-block:: bash + + /path/to/repo/examples/slam/pose_graph_2d/plot_results.py --optimized_poses ./poses_optimized.txt --initial_poses ./poses_original.txt + + As an example, a standard synthetic benchmark dataset [#f10]_ created by + Edwin Olson which has 3500 nodes in a grid world with a total of 5598 edges + was solved. Visualizing the results with the provided script produces: + + .. figure:: manhattan_olson_3500_result.png + :figwidth: 600px + :height: 600px + :align: center + + with the original poses in green and the optimized poses in blue. As shown, + the optimized poses more closely match the underlying grid world. Note, the + left side of the graph has a small yaw drift due to a lack of relative + constraints to provide enough information to reconstruct the trajectory. + + .. rubric:: Footnotes + + .. [#f9] Giorgio Grisetti, Rainer Kummerle, Cyrill Stachniss, Wolfram + Burgard. A Tutorial on Graph-Based SLAM. IEEE Intelligent Transportation + Systems Magazine, 52(3):199–222, 2010. + + .. [#f10] E. Olson, J. Leonard, and S. Teller, “Fast iterative optimization of + pose graphs with poor initial estimates,” in Robotics and Automation + (ICRA), IEEE International Conference on, 2006, pp. 2262–2269. + +#. `slam/pose_graph_3d/pose_graph_3d.cc + `_ + The following explains how to formulate the pose graph based SLAM problem in + 3-Dimensions with relative pose constraints. The example also illustrates how + to use Eigen's geometry module with Ceres's automatic differentiation + functionality. + + The robot at timestamp :math:`t` has state :math:`x_t = [p^T, q^T]^T` where + :math:`p` is a 3D vector that represents the position and :math:`q` is the + orientation represented as an Eigen quaternion. The measurement of the + relative transform between the robot state at two timestamps :math:`a` and + :math:`b` is given as: :math:`z_{ab} = [\hat{p}_{ab}^T, \hat{q}_{ab}^T]^T`. + The residual implemented in the Ceres cost function which computes the error + between the measurement and the predicted measurement is: + + .. math:: r_{ab} = + \left[ + \begin{array}{c} + R(q_a)^{T} (p_b - p_a) - \hat{p}_{ab} \\ + 2.0 \mathrm{vec}\left((q_a^{-1} q_b) \hat{q}_{ab}^{-1}\right) + \end{array} + \right] + + where the function :math:`\mathrm{vec}()` returns the vector part of the + quaternion, i.e. :math:`[q_x, q_y, q_z]`, and :math:`R(q)` is the rotation + matrix for the quaternion. + + To finish the cost function, we need to weight the residual by the + uncertainty of the measurement. Hence, we pre-multiply the residual by the + inverse square root of the covariance matrix for the measurement, + i.e. :math:`\Sigma_{ab}^{-\frac{1}{2}} r_{ab}` where :math:`\Sigma_{ab}` is + the covariance. + + Given that we are using a quaternion to represent the orientation, we need to + use a local parameterization (:class:`EigenQuaternionParameterization`) to + only apply updates orthogonal to the 4-vector defining the + quaternion. Eigen's quaternion uses a different internal memory layout for + the elements of the quaternion than what is commonly used. Specifically, + Eigen stores the elements in memory as :math:`[x, y, z, w]` where the real + part is last whereas it is typically stored first. Note, when creating an + Eigen quaternion through the constructor the elements are accepted in + :math:`w`, :math:`x`, :math:`y`, :math:`z` order. Since Ceres operates on + parameter blocks which are raw double pointers this difference is important + and requires a different parameterization. + + This package includes an executable :member:`pose_graph_3d` that will read a + problem definition file. This executable can work with any 3D problem + definition that uses the g2o format with quaternions used for the orientation + representation. It would be relatively straightforward to implement a new + reader for a different format such as TORO or others. :member:`pose_graph_3d` + will print the Ceres solver full summary and then output to disk the original + and optimized poses (``poses_original.txt`` and ``poses_optimized.txt``, + respectively) of the robot in the following format: + + .. code-block:: bash + + pose_id x y z q_x q_y q_z q_w + pose_id x y z q_x q_y q_z q_w + pose_id x y z q_x q_y q_z q_w + ... + + where ``pose_id`` is the corresponding integer ID from the file + definition. Note, the file will be sorted in ascending order for the + ``pose_id``. + + The executable :member:`pose_graph_3d` expects the first argument to be the + path to the problem definition. The executable can be run via + + .. code-block:: bash + + /path/to/bin/pose_graph_3d /path/to/dataset/dataset.g2o + + A script is provided to visualize the resulting output files. There is also + an option to enable equal axes using ``--axes_equal`` + + .. code-block:: bash + + /path/to/repo/examples/slam/pose_graph_3d/plot_results.py --optimized_poses ./poses_optimized.txt --initial_poses ./poses_original.txt + + As an example, a standard synthetic benchmark dataset [#f9]_ where the robot is + traveling on the surface of a sphere which has 2500 nodes with a total of + 4949 edges was solved. Visualizing the results with the provided script + produces: + + .. figure:: pose_graph_3d_ex.png + :figwidth: 600px + :height: 300px + :align: center diff --git a/docs/source/non_robust_least_squares_fit.png b/docs/source/non_robust_least_squares_fit.png new file mode 100644 index 0000000000000000000000000000000000000000..643d162e3db4124176cf5417c7ab215a7a086f43 GIT binary patch literal 55181 zcmeEucTkhv_a`D!6a-&Tq@yB5KzeT?0!F&j&=EtEUJYHr1`;$v=tX*w-lR7LCG-vf zLJoR`_CfskPLDQCVcD4U-T{g0(v*bgy{p6I3{T`kqQM1Am+O zV%dvU$5(}9AZL;r&q?7|7d8hS8488(z}DrNG;9vut`CP@VtRL3meXokqRtEqPQiXBoa6>_*}Grm-PII@ zfa;l?G3+H}_ttuH5)${X*C;V&464(ve$4^ENF>ysgqE)8tDU~JRu*|EjkY`?j42)b z`9hq&a{3)5pRJ|v!*eBF?GN@N30RqYQ8JCYZ>^?4T&oDd8;2Mw9Cf%Ic4!DSdUFsf zqAdeAf9mII2QBhjO?+$ps`3uTCg;2PlhNvzWlzi(9v!1-tG&9h#yJ|d@y=drM2f7> zYJz>LNVHJ>TDff}Y~3wHxME+BE80Bf0WlN^g(9jrJ@U5R-@!l;Hi-)9QAYeQ8`r@RV zmE&CsvB>7I8$UJ|Ik?hYbuF36OWqK5x zCJu=0#)VgOEo~wR?gE`2M#jcM&+UOxcCYC>^OZWt;HFg>iXTfot8{Q`_?Trk@&BfV)<2-Xas;TXhtMEfAz_V#!r&p}-y2 zKGOBpw7;Xp`7sJ}2p~NzYL2}*!xF|;xmkwAffY@UppP-5fl$1DQ`(cGog)ua1z z#0dW4?*~gs>LFe`{*6Z)0wf;?R=m|th#GWcFJ8PLPFD$5qFg|ZiP|rH%6n!46bWLj zlar?P)2@dPlso*i8rB#iS%$+V?^JP1Ylsus4xjJd=E-h9V5<7hc zRS;YnHiX;54&)83#9tb;xtZfw7p*WwGvc%6~2)x&q7mwCyOZ#T^|>bjJ@FgzyyKk3EASY+VioJBK+e>*W!FHA_KLac#ItJEMBbo!4AVRP`8C2c*BhBicd0Mpj`#$BKD2Yd-7ae+u&y%TVi+)zgo|;H;fg zuUn|EZ+yEb_dS{L^yw_AbvRv1s~*G8xTc-#frT}J%hr-U^%kH^nXEx9e)V&Q=54K^ zVQTie;uqw!kr~2wqH+=zq}P2>dq=DCdJK!unVXKztlzZRRX?x9bB+1PrD#i##X%CF zaa>}ZJ~|uiKGA>SPU<`dE^a>`ta?#SCpYSdNf5mZaYV+aizyC z*sFfJI64vmnQ*ESK(6i)@ruU3hscHraV8k3Ev*$LEK}Pat;mMC2w1}fn_Y$=!b+~X zm1sz_c z=b>#EMwV;m+Sb`C_C87xK+5+G)vg&JvYBS4j)HCmSeWfjRJ(L~bhjyWdaNpZ$ap+B zUU(C-wQg5oq9x3Ndew7P@;(NxaliKDnCOBk4tWIU0wWBQHVh(fvRFN@N;Q5z?fz2a=pxjj;^jQgwm7OoZ~oG(iS=p0-}YU`9py$H!?CR2(zOs99l6@ z2i`N=OX_8LRCg$Qd7`SZW=V;k%Loeu-yTDw1W)6>o@x@d0E?lWiRTTz^$JIZA16nn z^Hy-rk30pCPJsj5g~l}9W~+?l)zx-&jdgXh5cDovvj&FY1?7eA#sU8@_{R4ISjSqr zT8}?T{H4t8o0+_(%u6&nbj~#>yx&g`XOwSai%Qj2QQ{-nMzxhUP6f|XF{*msi_Oxw zCtYjy+$n}TeAc%N0;)c*xDs?NU^pVaq+Q;ZHP^|yI-!V`+!O(68e$9l&{9oz_Q+GW z=vupo5Z6){v#H7=Be82;zHKj7Qz}Y85Sk|>lQtY+Yu1xKyWwXG+0s+xuu)FwGcH5YRrF%BemgZJyt-YjuNvcsm1fT+|Qy~)Q zG)vMJ%8GwV1dwX^VT9&<1OmaG+?w@fKxR9@@=mLBZ0)-Q7vK0d@44YoF1l8qzl$~D zP}M11AHY2`CUQ>4aM212HFW*EfMQZxk%yGl8<&)IU2YEL3EPN%J-Duwncmw8oD0V+R;!@Q#AS;D;^D0=o$z7N>@4UCIXg<53BV|Z3mem+&kl2E=L{&!2u z!Gm+JAzeL_{ySWm?i2ZiZszThZ>}}<6O}E3NVLlhyYA1w#dvCBH@YdJnifgbe{64h z*k!p^T)M=4*|nNtWv5Xz4UVamu?Z@0!AsP(cW;8@k0ZjO9#GDPI%t*`R0tG~VLzXZ zTaPxl#@Z9^!Rp3DDR}C`^>))Io3pOjuGZc~mb<*+AM+7Jie5AyX}vd-tW>|U9aG?D z4AWN;PDK4Xwu;y(ME-kK~*?ck7fukAo@9(H=^LLm{r zP6}fo2{v9(Dd=Axkl!y5z6QUjd zMEKUb^cqz$1#FdF-@ON0*dZR3SunrwWNYi#bR;y?)tOp+hZ4n&MMftlCzl&^^)ElG zZ=75cH8wWxG3!9wV6_;VB?dPp&aW-_tt6Y8DjCD*x0m-f7kG41zol-ukdg@Jc9nOR zf4g@_1UfJoUSo!U>{hb6eBt{2hkQslAR`8{BHhbAnmpc(2)ZB9*1hUH%s!Qn!CSzW zUW^5B*=}-xCr@WVud`whZC~JpzxCeQ0Kj57nFZu*edF|F*;_gw;*;E9c=dncRXV<_ z9Ej?kNg2HNHSL9yC{IC2OY5*xm3&{)C#r3ED@)4_-+IP!<9NPzyY&}=U*iLysmA&3 zKGR3*)b~=fJGbTgwg<(l1PV8uQZcERiE1{o)+TS-iqLBhfveZd8C2Dy*)1$BcY9?# z|2$?;jnd1{&c55Xy<7Mt0J+_eot=HO@za2{6EsxG8!_O~c8>wutshzeU;(gyV51roFkJ6;U^DSMg{FJN!pmm4aur*#TaI+sb3OtYpEVB<-%~N% zZo?|7xkFU#0HP75rhPEOixfqQc6t=taZKE>4e@OWR3DkrqrVCY69%9Uu1tl64cdbBY~Xz*CKSIu2{x~wX?_wDPSdT&l_W2d$jdc_$6QH5jc zz9c0$f5}-P5b6$!=B2gqtCN$7E-1q=Jl+R*0?N|NtZ*`(e5s7edEGZ)hq|z^5HE>< z6n*<0SVI9&K8tgruOey&?g$PeL-D%9ksecp;DQ2gCw$ z(1=n{G@<8Ua>lmvyYiGmHH5FTwuVnY1 z1hoRDqaXLY62py3+FcdfxXJ{Oa4xELcS51qk+Zq6PZs-I7Ap73BRgPxTYk+?RC+cv zXNqetzWx!yJgo9KQ`uIa7}%P{5IYV=WO*Rktp-)?lBA#DEJjeK_oc@Np{v)qK;6&e zzfiMiaAfj6foIA7{_|&4Shiehcd%M~ZnDNF^(_^ioTZA_MCW_yzcwZVv%S3IGTPGM z#Lb&{$Lz+d($hFqR8$1yqhH?4OIuo6O4^3W#@VQiLHgj(FBk`VE(AroRsaQsC8G#q5tnN!sb5De-2&7)V2EP(@>&!pwK{ zxW$d=brt$v7;t~<6Qz00*|)8>bNMuH2c803hzDna;NnkoZ$?R17S;VlKx&Io%O+JR z-7%3QH4VFLVoBe$T~(OP-Om@p(|x&88df17cAyJSKsa(o!g>w9@jTd88}sQ2jmOq; zSF7qhXJ$~f5rs3^QNL~(-V@x&!YIn7HK?_QGNkUcW*@vTpR zfJe&81%N5*F$|TEOl?iR+IDEhT3Q?D?E&)J9RPyg_>XyFupvwTr$2SBccN>H&4k|A zuP%(R#K-y=h7E+T5QC4XmkteW+MiSjlnxZ)@%Z3oE2Z3nA5NzEP`8nmx3(VUY?<5SW$4mT!(y^C9z%;Qbr4l0Dea23 zUA#ajn!iDl-tlAkRhPax4k7_<03~1B)X9q zyvVK4Kz*A$PTi6*`3<6{#k70aF}`^;Xm4G;PniB}#V8{L1OfSy%aFK+IfcZdwP0v5 zme7QQrh?=~TT_bcQNFoD3H_W}L#vz1N6AZ9aj~v7Nf;;{S&DYQ87 zC>^q*9%5jVSN?o{x$W7hfTVwI$qOMpABG7axut;cUE=mrL_$n`z-L+w;m*oK`MO8D zzM_x$X!$pzA%m)jsGd7AplZRa3{$;Ukkj-G0@Xk?fK`| za^0hfytQAS@8kfNF2(sXsOA8yfnC8IfRM;eUHM!I5J3}Vhvs-Ay03X{@kYq^v8-Dz z%>IdtSQxLQZT|~wtIbVqXbJaJ#B?4(%wI{WzJ18Ms*Y+TWvZM7{+jcq9QjQ$<@)LB zzDos;P47E`g7@mt>rhMEOPL8-lTKBu>eUUEDUbirO8x!<>}hc{$Fb3BZ=)!38p~P5 zN8rL^K3dD7k*$;K)d@cw$`L>y_tIa1bFKK+!wbMLJ%)r=cPfGf`nd`9P>URi_+@$k5}tFcON1m)+2ZA7pw+pcq+%>As7hqhCs8QFBTcCG z51fc=1_B2`oeRKPV7!)=m!sTs@T6$n$uwGv`QeXOHUAagZ$yA!j=I+HREjiLU|mK> zM>R>zEG&wc0UYRm5mbydQr8p!1F;zrm|vzZ9JrKR{HZ#4PFjGBer2r~Brwuzxpqt+lf~p0O z<=+Tq-M(^$VUG7*-c7Fipi+meeS9oTaeIDvJ}edsa7|``hTBmge*wkqDA1K-evGt>RuF%U^TmDF#6x*_#6+ zhR*zSu24O0pLjXllbGLoPDnG6U3e~2)VM2W^3sdxEp3>r&a2Ykw4M;g<+Ljn+<9^^ zv7_wusjjZNN=u>+iB?K4;g>p&`ZT>iWdmDYJv~j5VGAFNCku{inqKy;HH*s9_WMi= zAYtqZ%w(?;e$`a430aIuylT}H02r@Rvg!*L7z{3RL1}_n6>4!ryEaTrPHmoAh2uu7 zuRp)}SV}T=4J5I615j6byzBR3meb76&bnXV>NmCM+`}8bQ?wJ+ZMsLt@zAf}99O?c z)wj~ir+#Agfk=LfKpsm_)#R2)Lg)=>-is(HTls5ba zH6dZv__|~Amf3i1uvHNP5jV1uXQ?X^LGI`thhz}J{5uULEL$fN@yg7a&@*3j| zWdTFpBZoL&TozS07!g&Z=;ld8NL;UZuEzI;%Y&5%1SjO==m%es!$_Ng^%(f5uXl#| zhpB$e(9NxI{P0kK`ZQ6H)-8BHI4(745H41dn6^*PEuQ!~z)naPz1L$61DSiU>Lk!~ zyMBo}QjH>98}k7O1&5ClqT}Ms&QQI~oLb`mPkvvw#A2h1rBQp@O<$UDogP!`zMbR` z#TvaT6dvcwgy8uAa7e9MASs`>a^Iy!K%+6$+}Q8~L+5AQ3!#o|5nP@Mz$#x&;QPr>as){$`I!9Z@G$y;Lw7_o&20BBp21LE_A3z(9WO5|#%e=(u-&)&fPA*?BYw}w@G`cu=J2)}fcfmAxIu%w$|614>oj6= zl>`;$@G^A$q_y#Q4;4wNLjjz8LpmpF!evm?TXRTUOJ9t0f!O4zE2Mo&4g;v~lSPn_ z)=&pS#N(k#C)+L(%?hN0p-hX9mDf?n*(eUX+}pznqQPa8;GWP=`nI z>YtH**GAf*z-zWRFQ34*6O^WxV?{Io_#;Z3nl@?KNvsDn!Gl0d>v*Jv-YX=r3+^-) zO5m6u5l|em11#Eue5f0s6Y3^^Iokr*HY&ws8Ng9mRqx_FWnlV!*8xI1N?AsKs3iEe zndPvZGGy!DS-J4j!Djl({9Yo9VU1sofw0ZeY@YP-1A54%06kIzU0#Q9U| z(x4qHVC}<$gxXd9c=gU`4khT;b9{^&JxORC7YK;s0!Rjpyk>yQOfYjmbO5X*@Q%ae z?q&VjulMY%?YNA9ye-2?35to%;00*t0gba6RDJPOz)*J03s7JAR&KL3uf$iC>}{y9Jxyv!S*I?U+tI&@1;dDUnc& zIB=4kf0fjAiojZ4pQSOtYsS@6m?9u5rYdBz=tmOy;k0Ba9I1IL>S*Iq=tbCBX7#^- z)Oh7YR5EzGwgY!wCgw0UiJd;}syyi&H3*)?8v%?7d=6D@jTvBi%J2qThrN@d)IP{i zE+7{Yclt|M=XQf&$n#WrsAqHihZIh_-pgX(VUOga4PaWpjmn(K*CF61sa+V zknr@(_#EzU5(pMeTEGBnSAyeu`P3-w0e*uIIp|}tJzV}xI~S-pzyaSwp$~`7K+Nm>DT;KyflB@}m&S?Vq`>9h_i;grsB?U-& zX-DaL$xzh`(g+{{P&iI_@4yW^U3SaNvv7AKGG*P<0wf6j91I|g!V!Q(qI|uA)IPnn zW#{ItQ8}$DDF1EBri#ye!nII?8S<=tTNqmuo1%>0AygFK4L$;;Xs8mS+Lqg z-}7vGZ(5ljo?dUFdqx5M-}H(*vF`p)FTnpWN0u%5J$Zm=E-QHp6y4^QH^uBNp{c|- z+po{+@YXF^tpdmnyEb9!1!>sA`17`MfiGO24G@H+=7Wy8ZC(((=jmNLiZemaBgU+L(5 zaR;zb?$88E`x)(d{n7bmPk3gDEX-@nVnvnFMdTWwo#I+-ofBBaXMJa!F$wjA0DY>o zM;oh<#?g+BoKR!TlO(%`gR|zGrzt#%!>Jw5W=1PI`O@I!ufO3^XHKI6g>BEDmW+YF z7UzRr++i;T`^^gO{^5-8s|DhHg>=i0IpD5tm52TB6dy4sUpY&lNyh2k&RwLHcmH|a z_+yYn-*!E2H>;q|T0W8d?sPD5JxcU?yw^7(v)^pu(_Y0c~fKV`w(@? z<%*BzzKDx2BEvsiE{L!bB{gG`-8x4IuifbxWaLikZ@5eOS^;-&_cBl`2mZM70lQ^9 zzNGv&Uni(be)nj0K9Xf2T*dKk|JO|wt&jA*(q}v&iQ~%`{RGW{@)*p@0p_Bk`=9G2 z-^(^TfV#Dd?_?PZ;+fjN;)>TCcdfx<$=h`?qA9<_8vGk-|_ckO^A=<`aSL+=9uW8iXkdGx_1Z`m6YK8I7+?# z`?x_u62J?)e%0;Hq-!DKhT*A|GVj$_`cwTYf|gd}(<}+dZ-XRY3j;+~<=+y>!>oB} zo|LGU+&AJxlk&qO z(NPy(u33b5JximbDB~Rn1vjP!hR~LfVlJM^u|?S^TNwmR4M;WS;Q5x@TJY!*xM1XI zkT@W)9OkR=rwqTh4G^oo>Pm)1h>XWcA3^`hD>O_1w%|Ya&Y$~RuJWCT+xpKlcqOmG zbi$yD+!T`D^~l&GmPLY7sjHo5m# z8L+FMU>DA1_q*Ip2J}~)#+VX-4(Xu6YBG0w<(7>&)E8~K738+^mlz}}N}0!7x&@&2 zJK{yow9)#OGlEK}`EW~IE3$2({MU~MskDM34U34+_&0+^HLmjaHALsS&$48aQr_ex z(+42`^%qveDKFnUG%z7i8}Y&E?_R5B&4zHxUD3uxK?3F^nJ-f;@{E?ZzV&f~&na2f zr$8^V&7;GG-!!DQxa?BYrqyvISL1#Ldw^yQx|edU`#f4xpzR#{r2{16mgIDpA zI$`j@kmbcP8{9^Hl3T0hzn4upFjop-my+DrT_t{nJIV(Cv;4`w1?g2~`pz=YBd^t7 zQEd3-)21K6|6UJJp$ET)TW*enowXda?KULsYdEbNBW=8s^5aX2tQxVUT>I7raC!zZrlBN|hQn8ZIBk6%I{! z2U*uEc$7Tt4$lTM(xZ)wz8n92eTc-mTs{s%18Mwvn_l%+A4`Fpl2LQBh)Tew=MUh|1nG#iVP z3Ue~O^S#rMFA!eteDxTN7_3B0!ygqP?$>L+qs4YJtxPS6z}fvDkNl`KZg_~^R&c5r zSutZaDg@>Rjdb^=9WWiO^<8Zw^c^SkCJ)3l3xGfmIps;> zMNix8SOabHxR_)Iv3w3Ox4zW?4*07$?{A-XyBT~Dc1=H6|J`7720qw3SS9L?V=3?3 z8^_au+wt^Aks)Q9FTY>CwRB#?lKwSsGQH9NnREPkdG5k;Ig&iuYBNHx7b_hTBTaHf zGPS&lg&cfaa2}o4`?EmHstGMNda?YTPv(1m zL1lUt*TB&pZKEjzq2|PQAs<3h)fxEj#6INxBjjjIqf}2b#cVh?YP@6dy7M zLRd*dEG$phOEG^TrzPt;Lp2mV- zLx0BT0rH%Ez$Ewpjs5MDEj_wb4u39uW%%$w=LA$V+VL_23~^|)w3XjvX|i!IMRVkX zUqMwl0nU`0 z31Rj&^&d(`sxy}!Z=7^JoulB|%T6|yK0ud5?8{u(WVt{kA&uI}=~+J>o^O#?zJQd_ z1FJnRrJ4bU%C+z;`LT%#_|6adI-)D$+I@!eC&ftu8>5@Xoyg_?x799;<786{wUB=2 zY?HTnsFUtM8)vw`D6lYX<|Ii*Tu)T)_`-uPkE4M}_x2;iq?gYUY?AH-VOIUn;Gyi0 zVt(}4Tzegc9pt~n^v0&*@y|%1)p3zVjDoE1TEouGiimR$U42&Vn~A6O?*){NwG%nm z;nZTL9n;8Z41_)MkolLkBm--*1Y&cu$7TJOrE|l4Y>M45(a5)FrqE6Ig}g$5C5bBJ zFU3N@235BCmL~UMTJzod1;6O7?VX9fdr0ySMLb`X=@tO6#Gihc?{S-vUXTiGpH-&I zn^r^{zXPkBX_;>}YrPM~y96d#>^ZwEJ*TetY%u+^#!Sc|huhIUMm{#X>uIjGOY-t7 z3NAimWrO_9dpkiz#a%wv$^56WlBP4BNY49LNACZ~IQKPj_Rq}5P2hgoterqW#d3`0YN14RC1$ioXMZlMtU&_~d-81IAg;M#bHC84Nc*eNi_-c2Vcs?TAEHwY zMaaxHdr^^yzPC+T{%KZKs$ys@mQXZ?9kGg97$;LbElc|(;xBXpOtF?e(B$W#x_wOw zefag{FNbSMjlAc;;>nS7J|=Ah7`*u;0OY^OkH=e;j5TUUE9CH`-jsDi(5NcTbM)GT zpJpcGA39=s?;S@erZj*w!+wVwx$N2jEQt8a0o75Cz`vbbD+B5jj{Vhm`;eSw0)KXX z)4nR6sIsl}<#`~;UqJp$ol2z&=*B7Ep(GNi-hrEsu`4JmU;pLtu87q;pPEXv?eml~ zoo;cS<-#OuA0gmOdgTS_rj0r*v!lB+^0y{;!~T4vx@GN7HENJHutg8y!b&X0F;{SW z#L+6G__N))arw*y#=n+NtCGm6P8#kleoLQ9u_y5jhw??7Y?III%XAXL!7`M$&4wRx(A0eLjF|#}#)KJK` z&xro8FCVw?3&0@!Fhd3vn!vPI%Fd3CK|w*y#LyJE;KTjjUw8_01CxLe z8RHYK%KGNy<N@qfx{|9r?0>^v`^+{(Tzb zumdwSsgLHO@)(={9N`d~!m*0FfG9sr}XH!?b1)@#Xh#s@ZEi6G`%f0CW&IO&U4p@eP6)2Wm%4a3J zZuQ=qIqNS>VvkK2Sj;{=eMuJ(b&d@V;25W>=lMIa)Q$bFFM@*p=1#M-2JV8VgKFkq z3JW`oSDX9&eJB3D5$LT2^tCqdFqL4U3v71t$H2mRq;3@;-TN?(|R7{jzn|vQo zq^~md$lSQ4dmia_O%!OJsN4xp_|t?7!XFx)l3WJ~V(@2tfkR0<8qMN8x#2brZK=P5 z@m{0R20fvA=dM907QkQlYxMxN9-T5*Dfu`oXEL0NFZgit`^e;$K2Uw{Y#_*}Zv*6z zYLLZk_p9gA6oc^f=?kJkgA++gx(d}?C+2nmhnt-&j=E1dFP&^zxgIDh(~%h#Jp^HT z4^Er%dpUuch$PFPHS4)*1=u<>uiMf}Ah_4J2l65VYXijJ#kP5PhU%$6^q}2rhI9sSO`=kiOlX zvNwuVTSnf5sV5vC_c$#6jIuCWJw4FiZkuAs(74n%gYBbUpWIS9$~?g(Qq)Cc zv<7FcR}+H32vAsi#go2lWuy~=H(8sG>>VwKD{J5a3wqg2%($=Jl(iw z>3@Vrtrvi$UM_VfbZiO*&Rt2xWIH;6M}7M~{A@jI?GVmNC1+7RTs6GCC6Bu=w0E*^ znB8%=n9*|l<>5u8bXTB~g0ng*RAY|W`Bo{=xNv}R+m|}At86-ao_U=+C*=CMCOW*& z$UCm=3eS|d7?$Bsbhu_iqlWR6DMJ}2t~L?>)P(O zpQF_nG;R_FBJ^@5-iuuMZ@&s{f}qX4AxupfP~VzSp;ZvCR=kz)pHP1bs1Dk-nYlGq zi8NubiG(3^^MNsL|Igp4fshki6-Z_u$dDPnu^U8W01<4hp1W|D0pg{n8GYtf#iM${ z+h0FaN_?R!{1-=S6^z1t#;MW6WuWX_#Ol-TO*7+z{GOdI(3~Kq#4r| z)igk|(de}bpw+rnUZ>Los3S`T_=rPEY0i@CSrp9-E0_~_!Xl((%bhiH+Dh>boovqJ( zftyhi6E9dnqLCMM(njlNvT=vns-G42l^gLz1=odR#O)60#@)`Wsar~)$G!4#y3=*W z)vBc$gOsk%{)0Y)pcOGEMA}IkW805raN1#3s=t%_axG@3`luC`R7$FynhoI zuW&v}S%Fi7+T~8ERoqXHsXXasCNKDdC)p3`RN;RfuRP{HJVv<&toeob9fI#S0xi8* zr|prj7R9shY7LXv{qs$9&OyQ#S$?>}?E;)i`RtFGNBfLye%5rb@cg~aag;acEllt` z!n2gH$w^9&yYg#E@js?q6Y@PhsnWtKCg(Mp8-{>Df#VO4{dXtq3&T(a%l+F&D8-Y5 zt)VpblzB(duRO6ib+f9BG`+QT1+K<$_CWXk9f=aX+&d^cA*Sx~|0z=v`coYGVb&K* z%pZ9QKg7MWJicRZ^=YT_ezOKgunDf=k3>Y{pNN13b0<)ce$X?B>QLIj>^#tx`|J#@ zd%1ZhmzJ-Kn;@S21LCGp{5ob;bYcn=Dzfv7-OYc(=-(C^61i^CJqtc3^(X*OTQluz zwgAl2!h6iZ&*cuy6K)zK#f+1pCt+bjWUacStgf`(jAx2_^|gGT(&h&p@vBWcgBl#i zf8TYE@=SH(lA*V4G%>=3i6B}NQ?4k_W{lBy)lkrr! zv`XeD`)s=`@fXP2m<$mRpe3~68$g>|e=Eb2bNDZRwJb4qtA=oE{*xf+_z%sEE+B2@Bv=6-6MPVdpXj@a4}I_+ zs>ap^j^P3oj=+aqYvfXT!x2&bLPL*-h9N6JO-`D3RV4)QkgIqqHlXEqxLg2|(B|$C zqXUom?UHZRRd+mic(OmigFgI>n;m=zY9NhNump1GBD#5Vwa_wKTm7iXUtu$hW;#3vc%Or^4Y+gE! zNWWF>(WkI?dIE_tM`>JztPO0lswoW<)5=42|6y|g)_KDid=FG$Pun!rccl+z8NVO0T<~6tMjD9Z(_y=$wk%)a~U02?7A`=WaPX zn4X0WY%Li~hwy3ntX%{$uhy@-RZcfrl!2Z*DiE9t1auC95vPSgyJ~Go9UcSSQ%_-F zZd^09_1fnR)W|SR%F$hzZELlVBFe=~v!U&ob=R_{@MqvenKTUB*#mSs3^`580#o+o zM0#UVgp~HWjXoopo`k`*)7SwZ>QlcJR2|j&N*#D$X6!t&TwJf;gSGk_@cskJ502{!J-a%eA{EcaZK9f{v5~5;$Cy?m^&L%`dl; zq_jDqj8@LtdZ`N76lvvYApy#>dD#J-_dv(n;&;+b2>8B`&^wzvX#@sf>(DQIs?(&G z>^!fyIMe&DE*c+YmK=TTjUszHsB>I%A}Jlq#1eRXK=}P-?&0p~-UCRzMId59n!5cA zSD)5675b3d^00*llp%PvB8{zK)D?X+7b}(gL?Ih#`axn`eFtUvQaWh!o7c~D;UEFX zAbh8lo=3jZ@gq68a*H<3gznrKvVI}&Sy1EtHki((;TiF4!KIi5l|nlsYr zx;6FYkcE{Yom{2kh2AB(_W;m!IQP^tnXLkS+bpi%=iaio=Fu)M4qhBH&n%>{4OQ~! zs~JT<13%GkJg$E?pN1c|bxgGM>X8@<SucIu1s$&5V#6( zj83R*mw;5ML_vuL_iO(VM=>Ym>A9_e1s?5WVesZ0zm(cx@vwe=11&3(!cn-ds^QyY zvDhLI^no+NZ80EBj=B+3na4NGWXc(v%iEFDqs)EPc;BOw~t@ ze!eRxC^3}&2k0!69Gv|?&%+$h{fVkf_gpY~eP}3VQ0aiDGc`o<6LW&Fl2=E-SiL3N zi8Hs|?U86Q<-fmmfg8RN^5Y1K@jQm{2|bOzMI>PkC$rES8 zz=aYG3d_K)E2c*!#Tz=wyVn2m7Y~=>^CJf|F^HcCHHZ)P+-;gmf-&fkPhfmYgX^OKytZ#iBoqvqJWQ z(0)X>!?#(&2CUd;(+8hiiyoq`l+^Al_9<5ADEuV(PwO6uux-S=ZjttEnuS--dh;d= zB!3a|vy4lj#O$AGbBUJ+UVT@uvycf(oLlfm$clZiT6F?l0gKXZ8Bj{jw-mlTP|NnL z`1`|}soUI8Qn|CNujM1(<)AfNL#kFxWG*w1W1&6cRMd=mpi1)eGckRmV*_J_xtO4 zZ_}=wSArOgQu(QqB1sG5PMi1sXuI#+#%{$)cF>j#>+^Wmu(SC+B)wIt|LyFw&Lsne z9vT&vuBSHp%W`ddP2O(BMY~t4fV~&CVi*@Wlg<5@as&8s2TP6f%X!VfH`+okvJ0!T zcwn_ELKLmDA;w0$(ihgq&w3l&zj6U*JK20^@lA{((M7b{st!t6|e1>E-!%Y4T%YebnqB>o1m0eCq-F?)P8^^TWbl zh763A0WI_Yj#Rq-HFPhanTL;>qQ3iPlatqz$k%L-Uj5to(TKowmA9r%c6?QlYyER@ z5zYE@v*UvCgbw?vE6_ehddt1340&2G+J!OU#9sA($0;7Q3FVD_S@`8+7#S+1ICvC- z51B4W>RtZpHP-*?iWxF;hhR5)#vdk0w% z&C~>nMrX)%ruF-Da!{1|ofQ^CEh2%&cDER&z@34pIK{o%)-YFNy`8nj75aDUMLOdv zfX_51ISUJGrVKPi*8}I?h`8KuKEw&ti(W<+_I-=r`X~Es;S+Pe6fPN3#B?2(i?e>ds0f}^qQNWigGGcSO~n<`U?Z5jHcZ)RE@tcQlqhlI)h zyixg{Z0hcVf^Cun>;5{PC+63BiYoqq6ZHMM9d6rA6)Z2a+a^!R79QJup{dyGjbDaM zNE`CVi8A%H7sbYFe%vt7BC~_HbQghy{*XPa=1*Uu6y3V(zye)Ea~N9a)DS+S`fG?s zvO$kWYF0-ZX_orkn$S3m*ODjksJySnRo@?zsp!Nb0u)N$z1JCJlTZ@Z})^ZF+9Bns!?_x5N*7_|%vjZ0>lf&v1&l(cT&&dBGZ zeEl?^D|~r%brp-fLLmsW(J7>m+eWFWus~6Mw{-I#P(FUzleJyxT zj#Z9)HnvvdWMkw7?Xz2@;0Nypm@ec5agV&RW~KQ+l53aYyHiOG768y zKbPiFp9vtHw`)j8iA{)%Cik+G>(qE6IbP4uTjXPww&u8%V&|S-iHhD}A;_vVDKgEd zu&j=EAiV9tV_+KMAmBt^-9`g+d+>_-kXi~k|Mdo3Q2SJc`>kFj4t$+^Qqm2>3zUxo zO65b61TrTcRmn#9@nmdvp5G1Sjo8ZMI9disrx%UltK!QVd;kh

d#K`WvI6ppC9%G_-(%m*%8uH6I`DV6n&wVdcy0W>@H~TiDt*sybQs)b=Ar(N znk|}_9DL7l7>~T2LRDW^H|WRw)e%~$029b=mjQ{*~J+ZLlNOx`^=`m&1Klvl8nI-l$gIDR~pfA>$ zg7V^b^3n@5rJ>yE7hYu~YrC;glg2#BtwSG_Fcw->GJ=JdW@$L~ZM#v^*?|Wtrp38H z^O&)PkKuh9#jRg={HA@3rN@~Whh#n_d|F{aGLeGIC4%u(bdH{b3I>)%f& zT_F_;3jJbwcu+r4F@g)Rx=1eDzYv??2HpM;*Z$wwdh4jFx-V?>(A^zUA|)jpLJ$xH zln!Z0k?!tp5LCKTI;BHeKuKwk1}SNYLvz=`_jkYhjdA(oFmw#|*?aA^W<1X`=UgjK z_CnIfsad%DHR+UTqy=(W(#SyFWKF%-34H-XCwS5H2~$2=6u2 z@$@lbprHOFfp)=@- z)3>H66FXteZ=!wXb5~MYAv=PDsMYR!6Q?9fkyTJSOl-LTdqqU+$GNAh%OeXv-wA@a zsH8Ts9XA|Uy|~hMPRdkT;(w4HJx6g}R>wQ0k=oW79LyJ=cIk!|l~{7(AkKXCa1uiJ z(`>tbIaSDwLztoPZzH{qNGhhee7gMZtT|3-DgbS<2G<{g*nzA@-HIeqxhm<2~`5T!rWrUNkw}u{H$-SEY}ls{uNp6ZiWTiiIU&xLAEBd zGhM0F&YpxZo0DnI@ZU?9?O!M3Y!iIuZEVOs9o2MRpJvKYi^8X=d$35oG72I@e&bcJlcJ6Z-OJx5xV_1SMYA>UW@e}FMF6n zvn{x>A$AZa|DE8Dmtv7#2R$fc%N+p}2Dgt7mIJEDLQu>*E$?o|JQ!d{Yh8;G=C_?sZWF_G zkqD>94927nq6yGc?ayvdCsgpCr)$4RX&#w>+}-_{gtQAE$A|_V;EI+ONPy4DC2aav;UcARy8*F z3lny&kMG%a!yPF&umo2G?e)xcoSR*3yiJ5Fu<@+7xNc{~D%?keSLL>c0?PG}Nu(%@ zjyt%~EK@aR?6|#oz~!{NALV64zdi-^#)LHp27#*dM_mVuWA!Y-Sp`gc40gch%L;eK$y@0!&EQc^*-c!cX%2zipC( zK@Tq0d~KR~@32~cE@$4GckxmKGFn+q%7N%#!RdV%)DFFCR%3e=bTm&#pg{1S5pd{f zIrm=bd;X$bOLwsb2J`bj;(lF!1YJSlJ9*PCpIvN z|4u%US~_a?>!tdvn@vA`810?0yXW$9XWxUDC#MMR8|Ozm!asT69>HefDW02^g_4AGJ&d~lY#OlmM*W`e$MI67o!(rVLzb`M?K2wV8x2m#zdGA zzl#z>Vv(m!KtMV6&mI4g|15kPeXdH+ihgUf)b{r$3^H76ftBe^SYx{KGv{~Lk0IvX$I4>fz+FJrL1rr&??B`(2K2x5Qv z!bm{{($V&Gpc@IHI8ge5x|Fyb7gi)8!M_V!fo58BuDaK}KCCp@2Nc^xB3wQjkmCT0 z4rmARw_1zQ5a!JAeQW+a{*!5Db<<2wV?D_1i>BZLB!%(iW_A`?NyxtowS11#=Oo%t ze3^>jLo1G-CGyNn5heV!=>z4ftA_jo*t1uJlsJu?oGrUOBZqzHw`r z&a_u=BB9XT z8N@7Lm+5d)1X*qBqTn@6f9ApC`8pfb8pPpz)A~_qwwP!*NKF{8WF*Ra19K(g`zR#9 zxyh{urMZ;JK|A+BHRuK8C(;W=?{KIB0ZHCVgjfD*C&4^)2v&+2ftxFtUct|c)jp!m z>Ia5nI)uXWg`$iuk1ntMrozffF1KPqoJ(I*iz4=y>PG(4iCpb;E^B)oc}Pn3dYbB! z9k99y95Dk%JLQ$Dl)lH9>`^FE5k=(x);Mjuxy|ihk<0I5V7n9CzV+hQr&*{wF3F~* zpLIhw>Cu0h>mD9`D6G8p8!y;)oByJQ;ngoE1_XXf-oGEd>KVQ}{kjiZr|l)=k%R_Y z+}zx3Uh@8&Dc5iHygJ)EV!eZcfR-t+tDXqbl_J7AXeQCY?Py{QG3>$IUBtn*zB>Mz z_okj&)Y)9yyL+`qtBtz-0>}5p>fONLV4qO{s1iscIhq(x9c0rz%j^wO}44@y$LeI7FwJveg-5e2En(|!+&OUg1_9N3f|2kv@MJ_ z6#wIT;LCKuPfyFIzt|g9Z#fO8{~qfK`Jq>&@e}<+w_@<*9}1s`l2EDt_RmYB_RjJ* z4LY;MLQAl$_B-Dh{y@lhA(DT=%AwH-EU&%YaAfIdZEH`e2^+FA)zi(q_+_y**Av7I?y#yv5WHl&Z7zQ1yW0tI{Hm&^0*(p&3(35We_QFy97;L%oN~Y= z`4xbA59&EFDP{+RI z>D7+MkjnPom$OC&#>9QFjSaR`ABTSDS$&S)ag2#*)ci0cH`qd1edX%nWwY%O@k6k5 z|GkL>{Gw@Rz>5(l}Qk0PqME??eQ#XT{ryjgeKOT@IL5Y@j z*uiATC0M1oKXPXnd2fs;k?}b%%hV3Pd@$+VanbdDQqf9!;49#J0ITwHgSPpKFmAso ztet{tadx|ah1!z;7y8tFz`robD1U}Wd*|+Zn4no@g5`S9OJ&CxBqCzam=D7{h=iGX*QOYYk1@N?AD#9Q^3vE(Pg&!{IFR2*WD`{ zer#=x>aX$PTiE}7SHv0}dXE>=}B1UdvBw>2-0t77mZ^ zb4$2VPhE1}^+!{kO|0?RTV)COc{miD8rrho^>=;LqDj|YslqsWbG;&s3H#w) zt|dt{s@!+{(MCgB_;f6JD5RSkvQ<3fVMIwR5sX%`BkMqSd?SyAE))4Sb93d> z%UFj#)|tH|Iseqe%V$Muf2SW|)KLoH5RMA2V#D33f>fx{dGRfNsL{9MUOtIpQRO(!X|fY9**Z+%HMe6U(oDq`9{bO`Isc=iqtxXAficpjEpT%=Pj zJFA{-#01g>NG#)|CEvNIZ2q-$=SQ0t>IBF#OzENzyw0-KB=994W`^zW4^FIh48Q z1LwF=y|l{xNh0S170QWIj*+O+3RPMUNfe&ApgKx+tQh0c63beRWO@e6$M*?JYBMIU z5sPe4B;s6ec|&d?T8*jHbjf6qoMatk^k8a8CJi}i46RcA%}~ah>x#NxFtM`I63^Xa z2r|Bjgp5R9fF()2O_&O|DBb_^ZfHJhB*UW?Tc|`wO}RJ80gi02OJQy#V)VeD{N}Rd;y8t7$XSJ3q;hqG2Jl zF)rue<)lf!3Hm2wDM%e1!57xcCpyem>k>kullSsLN#J3vwRf>N&$AZ@!3X? zr10=9dE%)A8Lz)>S5pTIX~bkU{8+MnLbzRR#5p<~+Onx80wRAL~Rg zQQqqQ%4vKT55KLVDX5^`A^?>(@((U*qN(t1j>VWa9jGGciPr__mD%#g=^(A81F~5l zARe9lm$1E75yD}6j^u8;F-WFSc0L+OGB%iUWP_+x<>z;4f-=(Y5;d`TM&gMwXEFYwvjbYyLi->t+ZzgAVW+hXQ9*3A1$5DaaTA22Z znt8ljU&WC(xIS7Hqe-fG-LdvuZTd9LuI(vo)^srW2nguldtSTa9^-heQm)bB)g6ke zY}ND`vVXMZKslGS|D4>l=TVc??$dw+=2zDB2!nXDNS2>W9yB=?Dn(eE4KSzOf00mPIv)I!yv$Hda#3vuA z-|%LbJo3Q|v*k^ON-+LGzHX|0@h|QvVC?%*D6TEt^uDyB>#GNZI2%K&RAWWyj+pk^ z(5N^WTPDyX#G=Z6Jex6RmYNNRQ?D87!xpTpo^Tv239b0IMzWUW$m7;sE=Njt!ArON zyHxZ@TifFJ%ik~>Z71v*1Wd^Aa6h+twi=FS=Vmtucvx6bsu8c7iCt+|^kVbU6GRK# z9~eq9hsi_@33O(?@b&cX>VXze9w+}g%Kr7=6UTG|=KLz<44PyU)yn0$v%$azcKcgw zEXhufTAR|?nNcZ!q5uCwTvP8iimq`QF8;T+P<&6{}%-wT0E_C&)e`iyUTK zqRl0gXVjmkz%(Pa;$y+o6}V6(p0I=jLP}D1pyV76ZEQF`Em9}%aDN&IPBgIyq5TkE z^uRQI2k$vZ_u>@3((vq_CMgPU^L<`3MkTx8Az#va;CobrStDc9 zCNMWKV0&}Zsi@t;EiEl*Z$vH0rB|BAS1v@=ND3l6MJ_!5$~e1q*V7NYGAn;c%dsW) zY4IJ4Oo)Xtx*8jb1^0r5J$fu7&Zm2~&VCQEq*S8D`4~GDaI1{a>>Kfn^px^3Oc8@ zr5SP~BJLgDuS!0mv(wXjrEv>x>K`UuC)-;*M)=@a_XY3%l#T|hEl;qTQ%;pfNuTY# zC=Rw5=eD7g&G$~W#t4pijsLXUk$3*&rR0O)`-}DV;G?MMq&*H^#n%!v5@ZmEbay0Z z;yTUcC#}vr`Ffn;em1+3Rm{?Knp>c)EFnD}s}Uk8neor{_R5uOys0u2x3%vKM5)uk z;n*XU2sP3LEPPPiHq|Z11GG$#^+qUieZ{Ycy7fJQtsSnI=h|I5@6Kb)_128wHa9x$ z&u`J~K1o)S2`S0dA6e2b$2E`$4L3*p=MfzUriewHx0G$Kf9AY6x*X~H+yDyvPqtac z=ss$Hd+NpSd$aSdu8^_Q#i55p&_}3Ad%P?2Z;=M?NYj-qNZ_KK-=6q5yP4IKhAIs$ zN=Z)0%-j=ULT7WO@nBrR?SF-mWESJVN*x;yjbL@tq2PY6(q&tnfK zD_8CANbfEy1sxEv$Vlh&ECdgpr3;0u59E}LZgd=Spr&jPAr?eTaYQ%A=tK`lMikXJ z{9pmGMBQs6$_bYnvi5T+Bfl>Dw?FImbSaUm{O)|2rzh!6=eUP{KlW~+>&S3>+lQMj zhydyPK=$<~%;66)WOp{`CCv}FXqIL@bu1ta>Z}G3VbR(@>-I|qod8+fld*!8@-~%| zoCrApzY97~ zmd@+6%ms{w{e7PJOD1vsL})}eEW()!6At`>s-GsPpt1A@ZCM;CaV8mwiv#uUQkKWG zy|!6?;0JF;3T(t8wz2IAC@+bGiAT7hSt|E?Z%X#0QERwQ`28=RvLV$BWZe}Y2Zj1L zzv@L|afw2WP5|zrJjs}~H>Y{n8xzz=Gw|M>CXp*Fclno&F~K70!u*0LG z_knVnh(JNM>>i5V1kIdQtc|SNJGqHa#j6-vtJPF6Bb&E8EBJzu&iw@)-X0I8z?HsV zo1CIWymm#rFvWrn@>Ip^`PmpjL|dJ~0}^Vgdj}-cS2Fp>FbUxG#3(*K?yDHrYhu7A zu6#Z_QHK=!qG+9(xeq=sDs zynr7c?#&HTXk)v#{B+(;K*M4x_Hd@&;V-)9Gt;-<32vChI-6a9QRpQL!A}#g8y3|9 z+HQ1mX>lu01>Ur^fCQN)UP2co!B{0 zc@)U}?ArcP{_dpEp&O@(u;7QfUITlneF_V}UV@ag2niJUv4e@iOG*|ymO@qnZ05>a zlR-?yMAFA<4xufbUh&Xs;H22z>26sJG0T);Yn|aATflvUkxF_SXKBTx+wR+Hq8&0I zX+jZ=niN4eI??r9P$juw+at5UqE1I4(S$zOA{Dg2DVY5==Ehx8g6pMJuJQWZ?E&y- z)TfsKdj5SisygOKA$G%hd0FMg1ro%=`UayFiQUEMAhbN;B(6RX2?e2xH9$xphk3Lj zg(Yp9>vwFwc~o-glMA%Z{fcTATHLZS@Lufo^qvq&6|4RAxjS6x-oEI#INrpf4?XAY z=Yu@Jn06Vk&IhYR6kPK5=&kjy`1dTBj2Pk{4Tg#>&;zfTx;2mg6KSZqq&*0yop6CIKa{_~bPW?0l67HGIH6)y19WGpeBEdwUKtUY;yp8tOL}TDaPw?}nG8B^tN|4^Mj0M0h(pg<8WcT# z`n>qbTlF7Lj!v%wI}0O#vZM4(ia=STe~azSnY9Nx;pGY(yFuEdWlJ| zrXJ0_GgUU~wpXpnXSFLxBpVCux+X2`JcRC>)5D>imyrgyU04u6^Ui#w@H;c> zZZi^!{ZZX!la^3!SW>BFWEB4cTqw%9pmwh@P0H4z1i#B-&q+xV8sP9_EBN7nW22q& zI8z*aH$x?*$c3PqGV{#SoIQG#{46 za>$GY;WZ1)E8_)Tv!z**)TP?aDHEIgK6Xzu32Aw{`biLZBeC#LvuH^xjilrzwHZ2d zaFwt8$I?oXD&4fSiHPu`<76f^zSJA9KgI8!J;MdgL*Mu5acpU&baRDIYmDxji%&Pl z=B+VSl?gG_KahE40(YdPES>deCrgIAw!hhr8+tM}#K(shJ>_{6%b}91<0u3kz`O`1L`AcQH+0EG86s zz{s;p_!=Zcf0Tg%kvJ!Nzb44gGD@FL_1jYg@D(@AQH>77A(nbunRSqUW0Y1TGAyT@ezopQZCaw4tRZ9m}XN{`+Jp8(5(S z^bgQYD9Zhk%Jrh;I6LLIqyV=g6|f_LKI1xO>w9WB@4+0Z%S1H&WT<#jxjeJ8L78#d zh#@THW4I78(#ki`+_++A^YS%50RfIII(^8oZDx}E;13>Wk>*tW#-}sw*81-B`kok0 z8_O?fF%8gV0vV$%eatEx6|O_0dw;Szvg?d5hvHDV?){ql6%`1-EY`gPj*iEdP*<0V zWrrMi;L-RBHY;;>AMa`!@VV`7aU|snvXHte5+Zt?K{}}H43ACI-4@NU{816u5(3S3 zgg|vH7ZHkKs;N;}#G%{6B#cKgZy!rA{Gq!K6`>3g=%>v)*O{5z5bf=;>?_z@CK*4@ z^{SHZU*$i1=kuF~>s)3u@o(Ip_CvP>M}50%?HwJ`NoRk%+Jh{vyE(5({`(${~BO2C8ypt1HY{)vEArm zmJ*|!H6uWfrptvnP~CVM1fKd|@FHpZ)Lj{Yn(n>v3N(u(w0pwF#Bdsg?CS#eBC!(o zFIQg;ZvH^mWBR3+`LTBF2-!MPb-!*+a-SLv9{aSrL>WF)D%uf(@7(nN3!C@)Lu-C- z|JF8Z85P7Fk^OlOQ4EJt`9NkpR&0jipfa3tEqjf40RK}0bK0;KMY+j<@*ok#;FCug{6s3HC(q@Oz- zDTbK9&5Wk}%N+>5*ZaEZR0wyBQWTf7+#TZC>#3D06T@A>z9mV8@UDbXpSYWw`1r-) zWZ9yGr1Qo)W4)i+l>m*l;4Y&bHwQujf;x)(7hCXbF7yfhx?=$MyVUca zVL!)=5TAqI`343Ce;FbEAu0`Neb3Xx3r)Oof!AG*5ogGC=!B#Fxy2mlJjb?`Z93j_ zcz)(1nHh3H{kc+NcN2y2Qc+_;{Dy;>BEJx`;n-s!R0}{4?S;5z$ad}f%j^#&ba_9YVGgN-0_%PWBb zz((;NJSnKE`iSjM2f78IP(?GL|i zy33==Cnfo87!@!h0Gf6Wa4Q%!@qr05Ou;g$%^#z1wIUIpr#$IafMtK+U3pIdan@^~ z@v>&L)33}^V=JP4UHZirn_yJ?Ua18QSr890W?ckGk&ym_swMG=R}Uc*jzAc zqjZvepvxZMBADZYA0Eq23}uFg594aU>G;&$uBVO8*O+sHuT)K!GTF&S`fv8#Mmr-( z8rMlV-UmiY??e+S>$SMfd{`6Yet#V!4s5?0HX%WVO*%b*ep4spiSh~CU?T4Nf7b=K z_Cq&KNW)RZ#d(2>;w%0G5ET+6MY0m}Cj#i%LOD@eEHr#;{vKpV{k)p_7XnO{pE`OG z+u809>_rc=+xkA*ksS{SWe5gzswC`W(g;w7!x@#L~H1LuPGT&Efefs*j zsB8;=wU@B`)HqcEc_=T%J8Ut~i!I^z3@m5I97;Ffz8vuGn!_%jB2P!E z=4nY!F2FBYm)7vfyW@a>()&I&9}Ql4`Bh_r1-um?f$Q`31Fz0Z zdJo#g{0i~Udj(=&D+qTtG9k;?WUoD=lEWuZu)jagn_8{)RnAK~Nv;sgQM(1&bnVL;`i8KpRNpTs8x>Rc^MuuFBD0o(B{uR5GmpdIJ9?oz~ zyQr&k3>UE?R~g1+(CyP8~8*Dm<`Li!M7?31J=W@iLDnRqc~-4 zfu2MgOUTWZr_Ea1QMX(ovF~spg-JF)5c<8B5JdkW_jjiYs=sE2J9I^fC6Ws$6iG-; zCBVRdfquIO)_R+)GOzlEeXf*Cr5?Q)UqDIX3@H#-`Dq9s>mzN|eXP$~R(N*zFR%8H#JJ%zDsd|x-%x;>M6z_Eq@cyfm&0dtXi{>gU$kW4h)`-R?V!xU~2ff=_Sk7V(&Z_?EP z{jU#l&W1gCw@$ha09Gbw#!~$nMc_uyF5w>X?(@(N-O1Hh;{k_axED?|K=(1_ddhU0 zc;thW=IsF&ZM-d4SfJELqM6Q~ps1KeikI54^!5Dh20=_vPt+0ZEfQ!%#cn`TPKHut z`{3QhAkvBZgI0e1BkW zb2ce&x~XT(-+S0C849Cz7xGie2LV(c=RS<+l@h|S^hbFG@uqDP!wPRv`Yk|4y2l@1 z(RyZOaE>@EjQ3b`wU-L;Y`UQZ;^@0`N%Lg&IkZ;hYu`W^M*Qu5-PA%ZTLaG_E_ZnkbrJ$k0LTPHr;87gT1yM0b)y}OOx=%GX?dE}HIBCh?e zf}JcUfOI++V&bUfRK0e*a8+b$8Rb7Z59#=u^{ca(W75wMDXt}g0Qa&k)jGYR@SO_GLM&R5?_ssKtw zC;CMO%GScdc}sh@@FK|F^X9y12a?uW4?;>d#_4`mY>O*`8z#8-iA)WGI6%JJY+E7j zErg?!IJp7C?Vj3S7~M7#4SGqdP%*Uw3N`@rn<0!~_zP-18>=hgz(6^o63;tgIsXJ~ z&L?mdeDrfdCY5ytvwUHvLkhFJ-SwL<3~{IkYNh8&cdSnrTFA042D$OdG)BG#zqiP3 zNh1O;iWq)+b7dZbvbDwcNkhTq7(X4-Plg_@UmboO)NG{ZY8XBSsJ4FE4ukuG%V=Ax zr5r^n?+z!q-4RRO4>4vA>%u zsQDeq>FINaeK-y<2Ljn&Os@#4cqC(Svbam6caXAoC)C z)UW!13$5MP0>Tqk1dJ*O*%y_dsJ~>_(a!@MH-47JM;Y8J?QLhq2a zPruxzKmD^kj@X@G2><(gjFPFHo5_yviSEvYtq&aSyBQywLeBT> zjL5%F@`$)#KGpy%k(H)f=lSd1g&jn;kBXjWEsLjiXn3NqKcy+6Cy6H8&5IRo%)sW| z$Fp%uhI)@clX;z)EPED*zEEx)FvXzp_VTx7(|cGO8Hg-1_Gg1cyh1&e_ZJ$k_FYjV z`T~rCLlhs;Wnlo#)=<+G5UGS02>x5%3O*dgtjz0Efj zlxl8EwDu@T60MH%7r~F<=lOxMC=4lgSiCFQ+VFGw@6_>Ff#O?6AJ9eQ)pYU?vo1RS zgKlU}$&Vz9&<2U=ILjwdq$FQWJO#1~q#i5{tb4n4j`#w_w`ooG&hpme&es0$yUCBa zuSP^RD*&~4`Uq~UkpJD?phNl;l$;Y^ug%-T%CF0`hBfSlkr6{K(QqK~cS0uGQlG&! z3N;#68#zv{N6K00(RCJeV|M-sQ zr*&Ad?IA?Z^H|ENj`t=J0x=T9(3@5us?Uf348?Ke<61l4*Pl$_a+N<|1Qn`RxQTW- zPz0F&S%ycpskQ%!b;WWjb`niYn112Xu)F8tryOl&^_4f6+8%yoQN{HRtcS&+lXX&t zez8u`tK1x4-kn8NUTV=K>B1Y&HvbXT^s)}N1{hAWdn@sSeJ~)kfFzL+2aNpFsk7vh zPYVsfa=5)1t$XTJ^%kYygqW00uNv8D1JY5TpjD6Eumn)DKaq)rlo}g) z;1oY$Z?nr;pID|+kkwR~Oja+S6jsu(#+=Ib$u4?>DCu9HtOQ2@WZs*k0_?s33nl{x zbYg}jJ??2EaFgIct<}dAkdLXzXCxr_(ho>I1q=zgvhOLbyX0&nTSEQo zgYKTT+)Ofpcivxbg*cnhrw#BFf`H74ZU8ib{YiU6piwTHI-2#R3QL-QEjUFPB{EJ) zjSemRh2cH7lUe|}eG9SRgpLQ5pQ?~N`^FsRn<6@^An67MoN%C*bQPt zydc@S(lrr{0xxE`+D_^7RULK8>r2DF83uz+lC0X4kCTqb{OE04$_@G16@%jBTlEFT zJB3d(>PcTGFcvp7G`tSv9R1w+Kf-+Uon|rdXK^~&AjmVk<4xwZHUs;+R+y>coSrDO z?--D7pgU)vNvF#f%Y<6T_5LZcidU5e8IsO=TxB10W_0p`3Pd8pho8bZrql^G5?!|i zZrEU2m~Nx$Bx5uN5VOCjXVf%lY9x~q4n8O-NvY)@#{e|%g zX^(SFw^m)GDKF?-l?vmxo~Z&0!i|ILI`UgN8N(QEy^QZ=Fd1Cv%O0bep2a4f6$*(C zS9=#^zAIQM<9L38#kipH8spl5x0!Rcg-zunB1P#$S(Gc%?zaM4_IVgk4+p z&{4ZL5CvjCDm7Du075%YuN;e?Pl-f6O3wG@5{Pj&dI3SNF_Q%herT^KaC{RfW92B7UwJ5&z97A+@2Jn& zIlpS}Yx5aBe_Tl{wizt|S^iF7{VQ0z22e^+FfS<%dUgvJ3Y_^~)A<|yo~{jb7U6xI z-1->_Jx-~jTQV7=dwBN+SNX1P2%nU3`3(jL=Ct50b|S#B9OZRJWvpX%eRNM$+>u@j zKJrDuaT@>1q-Nas$>fo)pLuEz4yp-7VuCdpJF%(666{T!QZmxx1le+pGzJU%?XmnT z*ue*-6mU`LD0t3QgfzL+Q;y=KQQn`vK}qPT@2j~Y=thRUJEb&65nfMNHQ-PAip;F zm-_gom;aO=EyCXJOuf^0nB|er!jOJ1x_4|(wQbAfu;A36yU?}lDX^+8n!j=ARsYoMu4)SjAx+% zFE!NE=~~or#_(tTC~(_Jj8IB@y@F07^VGylVg}O zSE{P3k2E9l>mDx)v`2tbGp=6xbDZcw`^AuqOUhHH+@FG(PC=PyN;P{Kmy(fyeFP2P<8**LeAx4Qr1eTAH;$Tb;i!gz4WlZji z6EmbtCuGhpj6F{k!GC=q4<#Q`(M|)zRKzHW33dnEh?$!SXtRf8oCfhGk2r%;U6&ym z72k|MM6ZYx3h7M`tXJ!@Gj|gHPYV#g*ey>^lYTk^1R$OF$m-u+yZTnPxr;?+X(EF{v4n&$J4s9C_{4t%iMD6A?j2j2{5%>%0JgR@Nr7ZPiB3)S)Mg zyxrWu=&DN_<$@L6?W98SA_j0jhvTPd6hagl6)d>$U_OF zJJ0Dhu5Rn50cJXFK=$%O$@2}E^7QE3o2qXKKu4&1zpRqUsND?FP5sfYNKR-g`)^M@ z9SU6`%!-VC)4Fj@wYCq&PMJf(Bm2Mg#$Tcur$((^FAEoG5z%JMks1NP1tkWr-{B?1*u#l3{`bf?& z)xA&Hei_nsslGdd00GG0*60>Iyf~zT3}!@uSoy${?ChX#Tf-rOlBFa1xH-$K|r%@xy@=_HJ~ ztO0O6D;%xOmDHUDSCxPZm3(GR{}?L;Nzf(by?bhT@o|T9hVpaUmEK@hRvB*ePCwn` za|X9-fGxJ)POJERU-_nhTb;sv{HE5q`1G`L$40LVINb@~`|=?QpaK#0M>2myiMg)*s@>S55;kx4Wx?!T;-b~b;QP3Rw5x`+{-v4R&!5bx9PTI-f7NUm+hfjRMOAH*_g zQbc_&1=^0H(`=h9CPsLMKBs&$1l7ou?V0JM^=R^36qB__X%K38{0`_^Pq}C|A`1Of zbs4vs8$LZU>cJlxgmp79tEQOu|o@dsT&OD#wz)kl9F8W*s1!x{r&yn%NP&=2MfNKnLX!v zA_=7lwdEE3qn?*f=uNAqhYn-tcU0x>b-?d^KYwDl)rEDGb;mnZ)>-Kr@)9(09uLE% z6}4Iyet=exvLCMU5j6>@GyU#vPhJ%c5*0)hzzv(NXD0Uz?TbS1my*tkhnr)HlS&!8 z{h(GUiwSJ9id<}e;P2x3JW_Nj7Al?RU@OK=prCcHFNG_+9${YL z+b%TokzxOhJ`eV{Fl}3X5Y){dcRrT%aWUPs6Qw81dSmdnmWpy|^mQ6#+M(AUzyz#U zoHsRf+Ao&buR5=C)xPI5eP+dQXJ_ll{ zfVJOlunAo{Z=;w}_&> zuJvqjd}368dkUk8ufE|^fk7U-Pk;h}R$d?u2=vlM9q<`LbQvwKFEM)$G%EA#qs_F? zm<3v%N-~G$yb+Yw3L<$4ir8{LE&nf*h$px`;R-+CfZ(SyI?H+8&CV*_Y^?2 zWD4l8)G|20#G(}YnVvx*9>-c(N6TZ;13+Gpfzl8A?LvePNjbU#kOZC4^9iRaz&I3$ z|K_@;8L2G~wNibwr^tdT!?CtyT}_+}Gno7XKU1J(@IfnV5m)CH7@NGV|7tCrZP5e% zx#Gi`EE8LFL}xeVLQUO(2g0F#)}F0f=f^(Drd9-_TR{_+Ypr??Zz-BD-dXucFyvCh zW#sqjcGMLQ<;g+Kd_sk-^;DVbq`O$Za(1(gOX*}(s%YNp?++P~v61ps#VO+%wMbKk ziZf9`2h$AEXfKuY1>j8q#t(;rA7>oA z$JM9|HCbs{iauLea5wH8nq*5Is;Lp;-R0EMdRCwVDp0CjUNEfHI`dO_sSFzD}|};LSc8FA|q1>Wr>Rg;ny_TgX@#RnHsd#)~&thuHOyq8S_js z=Fs6`@AS0}XjB7M;y_gyYpotPQ!sZ;{@bjd#FzraA)a>dth~69TeP%ozsD0D5 z;k8+68{F1xj|95HrQ@3e=Duob1-wv^^^wb7!jTuP`d{^w6OFWATLqZw%nLrTP587A zmqRyK0C7Em0?$2c$r=-<6jTl3uXV?QqpqvPu;XDl#VmJ*@l3dYBqgQMDXAe45=v0+ zJM@Wh!g6abqZ!l^lf4H@M=-dj(G_Yb3KEz&tpCb4a`_)8@I-+@(&mbI{`lu7g-5{A zO@d6_`>CgA?)dt^7uyFh)Scr>Yd>=ajnjsXY#%RKS}&j!vM<31V8j+ibM>N=XBvc~ zEJvGTxINE-QT2PqK$&;qt^G_q(TWMMUKs>B_1IUimwidPfl2z5x2^9eT3e0pii~+A z-8xxY^guqZd;iCe@&JM*Gh^2Y;~ir3rVT})|2xEpsj0f?>*aVoCYLNwxtwV-5NoU; zoK}v4;7%j^25l3&{gptRRz158ola@asG!vjPxs#6^|wVCww6`OQ4qIh+9xh8M%7kz$Z!WK(4ZlL^W}D0PL}y%)IM z%x^Kz38w_e;jpU$g1A3jM~Qm(e7&Q|#z{`tUxD9=32d^p=c=GsF0Wne(ov74e+G~j zxoT{)AvSAh+tD=qsa*0w%`uDm6PED&O0oxjRQ|!CH z5^(nyzSGUU?yJ!P0K?L_Gbej=*c_q$x_NIpeQ|%rLX8jZaN770& zI}L!HpxAJHD;06oqV>ME#rJaj-DQPtFTj>3OC7G=q1A>6iR=+)K&jr`g637y?wDUv z0?|pEMnHd&ad7p}TA!@2^L!n$s)4rMBn}GKzpCE2-3>2P=NqmnC90H@mbm}|J68j4 z$>RbKUL+n*zIA?(8cO$FO}puI>iVssRHq1x(TWrALBAUTyLb2F3gv_5$MWVSC7^A_ zvmUZrq59Ab2PSJh)@C=mDmOdGyEX!uzzQe$dm3f22aZo=vvfMAq)2VqBc)Onr63~j zWu8QKPM1*HHWdi#vo7SFpSjr{2~Sxjya-zjo)T(G(m%AAtG7t)_63Tix?w2geanxA zU8;D9KoV*b*qGtw*zhG6O2Jq8L&Pv{C8|-m_ByL;#7}h4X-pW&z#XAsfwV3PfSQ9g zlWgyRGNfcuI*&fTdK!Q3j##Q#qx9j0Ehg^@K)AycgHl89+FP&i9Di3FT;J(X(@;ZOU?vc(rnAULKn{TmH18FD-QF`gfPpVt3caM@VT4WyLkAKZ1{rdcW-* zL6b*Hbqng~AP}pDN7&ubqG)9cpidYa)7WA=VB$9LHV6r{_WFpy)%d*9D?|Ts%r^^T zEtKjcpNqBMqTr?1Ga`P<<~{z_^S5^;Hl+)hm&B@<&m}d|P#-eA0TaaDx*xl4+sRXY zcEpAZQnn?T!l$3o)lf#~q~ta%mK0`=eKEG=pWJ3i&G*<%Ud?kgO|&TftRV+mC~Rm` zmy^4Jy00h1s`ldbrQu&prGuehUUo35C3nYn$2GBb+H9Z^*+*0ah!&bW1&aS{;#T#h zV9>DV5zUdN9v^h?wQ5}nm!CGkqJ6bS#?9k8u(&3I@GPe*)HA>!H9PliD$$D{N}zme zq4~5Mw27r0Gi)eT{b5&!IR+cE<+|CtD-+(Q!$O2qiGpTO+@;M6w}Sff>YCf%3Dirg z_i|*p8x|5BgBx0HSn&0|zbIy;o`j2M$1%GcE|)0QsIff)-8eyk7_E>qOP$z?;6jBZ zpGPJa$>($GiSn`St^N$RM9wz%pIM+qX*zr;SBJbMw6-x>m3u?L@3nZgs!aQ_u;<+s z+5?o=eXF^SkHHuLSeqs|8P!NRM*OMyL8U2NC7*DK93u3Ifo`9TgoCr7K-|jVi^mY( z4}IbdajNLv#`P$1eCX=KB9QjNI}MsD<>%%<%9qYyPSTtLE!{;A1H}6-&drS&WhIrK z<>2|eGPp|JCjT^FuCLit=IX^w;UZ+`cQr?3VSljLD(trZzCtk$<1xwJtT9usEBN0X zjU6|?h6~Wy;Be+k{B3ai-^cCMwYBj&W4+Jz$HvAQt3YQ`Y|s^LFquxdy#9~Z%_wa? z^7j>bo`Z?vo}QkLckQN5hj9Za>wi~QS4&o37ppa2?YA`8Ez#I~vAF_MGHmN~if=Gp zepvQUA%;>p0xs0?%5`Vv%SOwR&Es;hl>j6(KxdTH@)RDuOy~B;fPkV@$;1WwZk(@a z9j0r|IneVjWj|f61YCrSM8%w~uFW=wt7fTpE#{8iEUZIK=3FbMqr?osM|C2V$dqhu zOR_w1Q_~6a7n`()KdQ^Xe0KM5ThH(w2*scKX`gHzZ4y$55JLKi;kU_t`LC;7O=`7wnl-}rEx zV59UeyWe%O;MC8>Neet+mKW}2%uC@G^-F-FLpI5mpGH&xZr4?f$u#?gr!5CeErkc+jZ%~tfBy8zIu^+K3sZCAnJb*D_ zfGw$28c3*m?EatjzB($Z@ZEY0T0)UdgYJ?B0i{d2yE~*yNol1+K)SoTK^QuPArvIX z0qKVOj=y`?_x=6-`K>!^v1TopIfrx38_%d9l84JXZLN zC@y=j7zF7sBPa#(EL0mZn5n!6DQcK!;UyZtf@NnLICxp6pweh3@nm25;%Vi_o&Mpl zu6m9g(&%e2TA-(yM35kx?~MJD)=A$(PeObOtaj5z!R)YexksOA5+f8drUpeCB3kWM zD*&tCp=?&I_)$dzENCzA01?9_u(#=DVDgo{;mVtqUX_tYgQdRiE2{p`(3U#uS?fzw zF{i&jyMc0NUjxFTmj9VSjMulHvz7iQAUaC7%kb)zmJ4}vMQxj_GW}CZuisw~u*P)MC#A!| zn|t9vz8W}BmVzM)IYRo@zzbmtV_S6y|D;Hr`)PozhhyQnc?4GQL|F;@2Zndv!q-(V z!H>a(tiEeB@F$~F+%7H*jWJ}l;R&Q}0$OR3jiQ&^xfboKB{8o`RAd0}<|Fq^@Whd9 z1IwWE8uo)Mzf$M-s3Lo?h<1X5rS{f)Cy9DaMqDDV$6>G>17@Ka5{fv{tR1)Gi zZUVkU?chIoLU+`S>;Knp-)EH@H~CWUbZ^;btuOpMiOW|7@?i%#Bk6(dnk6#`w2Reb z8BRzZGCox+F4CH*(7%ZWH7XZ8*jx<74YYA7hw7@jTcOpX@QY$9}B;OsCV`jet|v%xZ!?E=rF_hiY8JTQ>nPaHUGWm%S1x zCq@yZP+bE)_dMxC^2EH^2HQo{=q+f6jk-C!WRiSv0v5}_mI1Eia4r0-3 zfOVLMweHV>uDOa$7niU8-6@h1y2%0hopAljg)Dur|{ z4LUpgP8UBJ%25<(k=6|<+iuzF1!6MIdZ3X~a)IZI-KhC=)`XCigS|e^Js{x?1RePv zh_S0-NXG3HecP}}rwv6c@o$5%b+tM_e)Co2_CO4wygKi*D)^op|3aQx{!v*pl_goB z9&4jcxz#u3%y05fB000owKv{~_8ONb+0-9fLU@t$9s!e`^>26E>!u78)|rQ0b()eGMvFdoC)prX+1ggCQSCkkcJ$02yVx z>6=FG*^3>7nEa5r4_B|8+FSO%c9v;5T}%i{88~={7qL4my;z+qs+Iy^OH1pqjixrs zywGZbT%+bT7whyHZoWnL9(i3Lzy)z)eP{j@GIid88PZ*3^hYT(XeT4H5LgrXlYXT( zSUcQc+s9?sNjgQ4*@=28$GPzHq^C6n?|-$fSEDadmR1V7XafoRqCs8(P#)Vy>J;x3 z0|@$yRy^1?$7q3Rab)Vm22v=!!Co*%Le$*I)H9QI%<+#;KNG6ge!vYI%Eu>J+N)G0 z{o2eWI_e^o)Wo}L&NnA57Z&`AhkIn%F!kd11-XHbk6_G{=()w&7DFaNtcwj9S+^6w zNH3~7)F~8bk?3%fKa*kd*fXhk<PShs|?7L$jQkina{%Aj?fN)Q*W^vGj#X8zUg%ozAP5MfC%sd%(8!yM-5Icb2hk!*lyxbv3f#vHX>rc z?#v&9L$RCua=B5-@Y>|AfXrcHON0)pQojpp*ukpYP2))R+{*OCjZ&_Si_X;Lf5ENU=?faNnEBPsU+Eke#H> zgXrMaT$Pr4lDG<{zP8U(uoSV6tG)#~BlH8>Bl@#7g5yHDjD;FlL<^`Mc1L8*(PJ~R zNDknV)t|q>ybqZ(O2d2_&J+ASDmt?^;{B)vS2EOk?S7Aw8TK!JL1F6BCveoGi|)%V z7q36!Ev1!|I+8!&A^mF;I474s=iCMDUR{Z1C|-BN5bn>{wUgYoC$jr0&0!5bxut~D z2~q-tl5%)bcc0&n^1QM|xd*Yt1)*33V=h-A43Q+8uTcuD-t7$I ztRe-;HudF1l2SyYY|(uK6oP*Wvm9g@!pzn1AXTjA25Ije_AET9fBv4_G7a+&h%P^Z zaJ}G{MW$c#*IhRrQi(=)fuZnkAh;qKLGc4-d_Xbya9tp#KzH9#{(G>kZ69wMh7>L{ z*e-LZAx0F)?YD?iKmsVIm1{t^jxrPn-Si2s?v?($VthIUqB{r8$jHl0-jlh;-L*&> zYvX4$*s?bw!IDB?w+f*>rP787rONn$<`6l%RnSqrxL6b0;H@O|(~2}NaGS4Ve}AFY zQm?X{XXXP6#Ax6#x@8Ch_CB9toi|<=BR8o|v2g{Z=j(t&I^csDm+8amm*rVZ42^@I z`Y0~>y1FQVp;qE8oX^lND>Uu{r26p5vV0GRc!&rovoPYVKhyJlBx$3VC+f=+<9r4& zihl+Mn`EvrA-2PDID`cBf}gpa%m%SEe?9b~+1(qsn>h@k%Hz&L56q74&mosWG?dKV z?sk8&FI||CR!H7aeB~Fqb=Gm#K11$earzc{d~ILG%Hn%u0c>mhpXJdZKjf_hIq+M6 z=>)8v+1A?H`gjg(i+)=eMwInB5-)r<4vk0)_u+H8Cw;*532`r4MJ9;{J$kuf<$NHU zLO$HSc1lqPF*Bi-3v#l#@9V-O2`y279d>$rS9lf(@!z*DpZAQN z`*5T|3jcug_BE=VS-2{*?W=VBm0Xu*p}m-dvwpqplb*>?jHKE9_z4GG`+zOMc#nWT z)zzbfd4EI6dR+M1PUf7hPH&Tdxt_;9PQFvi3hp%74K&6ch6@zrt=J;mTZK0`^m&)6 zO+$)^PI9`;_N1Mup*1n&{G68+3JXLJA)A>08SV>`Jal&c9jjT7)4$%D%C)U>TY&fDr_ga<0a84wCHrVgfORzQP z1;D$5ykRg@88!pK<3lJ~GK;Mrkn;cmEpT{jHsLmv-xk1scqoKe$W@V9b};A0rWE>N z_iA4@O0wpUy=;6umo=D07eI!31X$?68p_E>C zkZ<>$G^sXxQ8!B}8_VVuzU#K(vSS(r?>6g^&5sj+SaE{tX|6Rp`X$?dG_TLJdJZ*; z&)FibsL)eQ`4SEuJB?lSPl>4=)W2;YU9`QVJ$9xQuWDG(&9oyb%Stt_$Y}K47pNij zumYt3@1p28`J4^de$8br%>kb^fC%&I&Q2j(V~ay5rh|LyVcQJ-k1f8I4Z=H9s?r(w z$xL^tO0gO2m9>*Me!=`enAbfB#=lM5xZ$8%B9w=eF;T6Y@phwCPa`+mTYtG?O<&6& zF@Fs2%oGy$_4*Y;v`bJq!P~je*{(rat;t;ZImB}fU0ChdR@`8UWQy*Pu%^2IQ z$*`FJ-WF;yTdUn?R2t!%I!b>};HZ9C+By7&)UIBQ(Rw`d7|2E=p{Va}GC^?Qe7V@* zcf37$o-~vY=5_wFS--e7}I zO400qD~eY-bzE%MjTK!H73Yq950?Lu*@23fy0Y7%pLU|*Wj5TTxz-bEUz&l{=sItz ze3OYGz>hdT0&~DEjhqB1-_;o|O0MJ!^Q`s3E254&Kj3yk>6K^bwmBw< z`6b+DY9v!qA|wzqqj0ObX>A()S%ez!fjk!dbc#&BBHma}*B2F(cep(AQt^2&v~;U981q9L3@T0E>4Y{eyPgl z+_0j}-~|)eptQfQ1lVR8)R}SAzsMjU9NAfY58GEpV(!sKIWqo82B;^cP4zuU*PnGC zYf0c*XOw{qsr`p#^l7%QF2e$d7fm+3Xs?fz&e+;Ec@{hLfh8(ttgW`Twoao79R}Fp zAbf)$yEGDh-wMp+6JgXsAW)s1!DOUUJZ8J@72U=%oXGGv?OlNz@Yba-Se5jTTtDp? z%6JKM?*%A$((}ZC1BD_mDJTOGr(-~C$E}+^Y;M&BW`8+Ts8NJSC5>H+e8hq@-Lz>0 zmobY2rbCIIMr-+k!{Zg36KI%XOdvPGLkNT{5UA%DtY6hIWAoa?uOAosrSaz!5RZ6m z?X38qO^Y3QZ5-XaI>snZVoVgXY^PQ(=H_0WA%B^y+Fn5oh=*K964vq1uqhA+Kt}FI z44aWfdN{|-*p$qg!5HF&D5UOoM0W-Qe5*Ff9cSr8zAUl4W8AE-oK5bS>1_Kq_2dkm zuPTKOcnkYw{CdR2V@euLFdRl0`9=&-MteXS^c>HEj7sRMo5c)kJ)5uDst7Qv)w)Vf zTk|!HjJ$#RoZ+}4f6)7Wkg)|Pts|^V-BBFppS&E}Yziy7bQT^h$ z4{iU==<0DJAT_mYWr``1&5PaQ-o6IF9^}yP=F|}v%<$Y-Bokxs|hD$o$@6C+$0-aX>odKFYCwd`FWP1~gSh?k;S;I!SOrCPe< zc;{|)4PU*xN>~Qr?CbLq&7G{<;(&`4pLl-dsoR^&4a2#Q4{Svd(bI_2+@E{}zVtk% z5XkFLfF-2J(Jn>F1r7A#;+7N0Q~Z^c{}eU#lW#BYT%_gLHnW}-m4ul<&)$1Zmji}s*REP~66 zZP9=c+Z|Rd5pcV8qZ{-(QTDP<8mdwlPfoYgs%dz$`?JKFOslk5i~K!B!i)p-NUhw$ zTwfn=JKB+%LX@%{Cut@jM}_y+Yl{G&@}eEPd@<=6I3xgMr};k{4Cb`#iac60YQxG2 z>&;FUm|4wb`T5yj+6O78!P+C`32=t42a`O8Hqz?AP<kr=ri z__45@prKZFcvszgM7zul=nzdnjqEoAMwK6N-+Y`HiF%ax+GSL4nplZ3#Q5E1CocI9 zvRNFS8vOgf`XH02UrW~|{|8@5An37ZgX>eZZe<$E=7CfmknSPWxmptFcB~;iMrqsg zogzPO&)09TqC*`zw9#;Fz(y-yoU-AGpD&jBhqrD12C7Rsr6h9vnYa1PXq8HFT~iZr z-g5uh4V1NYBwcybRUhS}kdn`-m9^R`+{T-N) zRD~zVdLN~0{;(Xx0b30aN)oZ;#yS1-02r%aUHA#i1eHeYOJ%Y%)LZJ;s^)OB9Zfw@x#u#4j3fHesn zixU_yls1y9FJV_BE}17g4h*>5$>VnLK(gFSB{oQ+D!J6t}c$@`Sk zxHLbX2C=}^a3c9HKg}KYcem?Kas7;{`=VaqMaTZtyL(!|*R3A7E-t()wsHp2bDf30 z#SyR*nl2Oi@2#qV(s!&404bv%l$b@Iy87=1q_d zEw;|II-UY^W2Csz?uTEO5f)*Dm_wROPxk4pGC$kHV2zGSe;WL*PHWp8s?-<>Fhgdf z?F>rAvtQGKW!#eSe`*%4*~>Wgf(habZNEZqQ5f1z7jHv+MV9JqtCky7ai(@2xl3Q` zy?@u_;pq9-sL537u)u}?Q7?vsafAJtce}c9`XonVyU*F)QZrXIQ2cfCIv7!9OO}9= zUfq|@UJnL9K@7s(M{fcI(8~^$^CYx=hJX9uc%u2W-Z-GT_%9}JWQ3jn9F3&MR=iMU zEup9hLTB2 zqV+}Pz&3++QvDtPyt_#Mf@~02$k^pM*l@&~-(Y;qkMqAQ)bv?Oh!&eLWIt=)-^seu z2BC{Xgh!_5j@%WIoi4&%&6(RR^mm8fRl!$=H1_7ys}|<*bPM+)ZF;Tpf~UF)89m-t zh{nN6fWp7pv`>O=^p)P+o^=N3k!0G`w{*mU%h`lV(y4rXeETHc+M;gI`D@iY7O0iz z?cH&w8&_IBnWO`<0oAzy?FQR?rcxb}gKba3T$ZaA97Sc7t&1!<1-YMP4oc=~ zuAyijVN`nJAj!&8KY842RY!!!-}e;A+bu_t3i_A@BC{R?S9)uC^oHw?FOmmsB0$Wi@q z={#2HEPHbLQ^5=8n>DFvQ(?71;f)#_v%zEqw5HY6I(RTVGbW zzsRF7-Ja#WnaVOQOc#Be5c?IhqKyj|D*3AvDq=SnI`{uPd`on~rj_K<%%C*YfbevQ zJR^&m_tVzW;`2KEo#1z&!j#)ok&d1f4}0RBiHU+(cri`})9%pIs06}mX;&y|&vVv? zVMsH_8e#m7eNgS)KHixQN1QFWD%k{xgQZ0sw*4l8tH;p9LZ_9YWzWdoKtxoly8##@ z>r)OzXhxJN691KjCnS^Kl+H^)F|Je{g;=5!?(>JSMp%KpB*Or>+<9&skG{ce9r z64m^Lk967N{cBE+T`SCiva3H63w0)oW^?ra_w!zf0$Bfs0uGhpCIM^@t$%|hEAjBf z>Ph7KT1>M~Ujhb&0&-kA;3h^mFIO2D!fLG>VHdvsOH0zzuT9jYBDcQw`K_n2Q;MaJ z$`GiJUJlQU9g-xbp;m%y6N!jeAOW6+U}L^tY!fNYfHSZTj6QNo+tRtRXH|-4_8&I6 z76QB@!LOoKF;?h_{?(9X=Vjk~2Vtk5vGFfM|MT7>m3<}#8$E+kYU2a=QFvBgyD=bzNpcDHvsi+_)r|P~>1jF>04Wx>9ZG zQ4h@Za;|>iy1~mY;hl5SO3Chjq(RFGol@qt3ae#otIu;Z$%y{?uYdV1dklarc|k_i zI$x4G3-fO#g3?K8!{=5{BVEWhq|mgu#?Edgxvf+TYZv6r#K-^H;u(#CaHmB_CoYev zat2@NxKYo)+2Be?#-{#Km$muL>P-be6jWpm2NEKx*Mb0DiFCbWw)^|9ky?8ny~m{B zQV7DrxL!=lXTX$B0}c0kp3bO|6`t18S?HA%VUD zc&DV;JfuOOOt&kz`mT22uKD*98ShOJzbhE0wKAjZyNd9Z&s0(N33)0qqnkhYzgQGl zxlb7Z2qG~8)b8@*2J*#VN$`?+)%q6e>2Jmw7L4|iMMJ@~@1))ug1~Do^s%^+O-I%f z4aF>t>~GY{&0qgGI{p5xEDhZ{xfnl_!b)CH(Z|e-o2duYO>Iz_&-5@{%Z_}z&>%pO zC~LzV>fl1IUYcqkI&by;2sPC^!TiKBtfKkj8$$k=`0*{N$Qm1d{4}hs>o#zG1>)~g z?Mx5$npI0dNl$yi{bJ*C&*Lh2o$D>li8lj30wfg&>-s|@`0d-*N0m2|u_G*^i}mnp z+loov&f>~|WjlTvKe0s`xAf8L0$s*=#PHFK)re*{F$D6830XaU5#05Z6kDBfhxe_u z@)W+(_8}Bl-S4`aYwtYU1iAIWdUGV(DZm6p?||t|+h6hb(2Lc}B+x~D-a#Zsmwz|z zmNA-$I@-3_Cv6$HUZk}Yi~?e1hy~_Hyw5LD#9Ua5%&{%#V-zj9gEW+c^FfF(6d#0G zy>SqIj{31>IU&SBNrXYBP;miq3T1}-6e{ie9=w(DzJQ*v-A%31xqHoLOZ1PbNVp6? z>o$3}!6^agJdmyXAMuE5`IM_SybijVp(^bn#4ViW7D8+rRd*Ym+nsl3*(|^gO~7BM z#a+Gne4C|F@6fih;pE(T*|&DDqcxznym43QPOW)q6(kVzomb12r%M(++!BHPCU4ak_{_t>I3S5B*O|vorFl|K8xd| z?#fiBPu=Zb@Js|(i}m&{qj2LDL|-QvvYPULjnS+x7}OUFImB= z&5zuuwk1A|4*8-`dDz|+Xvh^RTF+My#GDN9+N_G``&Pfycj{J)gss&Z12g9GIb{$t zPe`P5Vy77dBEwW`JJLFke(k=Wv2)1e-u5!cR;JItaejs#D4va19|!J33WGdJKdo6u zphxSnDb@8)9>98^uus~!yB;U<-${<>&mns_)c>&pHttid5zyxddv$YShl-a(Hp8)939s&78tj`cRln$9zYQpqLfg zfC{>M_M~i97F6xhnH~ebOY!UFWb#3dRQ60%Y-r6Q!ri9Q3qU$C$juo2*{gJLQ_lTW zWkGYYjC%1)f_y;CJSOY>@)gVb@3)Bl1dd94IyHK5Vg-gLrD*y7L#a0EF}c7lka3`a zR~7M8mBpfoDhzO$UNcH73`O8#B+1e^HWR`vhJ!DBSDeY&G%V)y0IN24`b}j2bAZl3 zMxIKd*G6~tMYUYLpt`sa-2d7(HXbjubGKNtapyZEHzw*PORCDa+2}7P6(c>hk!-tf zAbj{K)89KJtdaS|+gAAO(O*9v(t~H+-7HXR<+$6~&X&E(+g;bIvopgfPtt_nEqmbf zq+Wq>goK2O17vCglAwJ3BLP|4h{AiG?i)b=rLRPg^3|-NNy`*(qeEid-LW;kGWm|q zPGN6V7AlQfE2;j{Ne|Wy7Ff|ct~U~=ztvq3qLErO=Wpe6+v?4In)(U)S37SIQY#l@ z;y92Y;#e%9tDj=i^*Sh)B(N}-Zm%}Y&A z6l0v1I53<1hdm&F^nwy5LT?tb0k;m=ef=J55KfV52~Sbs=>5pbkgQs*bu-r(D0+eK z2$U_xMXt(TuAX6q^niePFGk~?>|)!b6*s=*E4V5uFv=GD#M}xTaW~=1cCUK%SQFwz zEpp96JeCPo4V12U@AAuaRbz~_joU?zwf4Q|Cval8_&&x42zhx7V)(RgSG51wco*-O z@i;?Ki?y)x$3d2f^R~I5@A==~hI}zzB)r82m5o4$$#WQF7R%d5_aQ&^Qd;-((@|ao zf5%y!cj6zsH?7Hzetg;I+MJI`~xg5eqUl1Rn;~=24W< zje&B4C;{vgbC+;pJf5=j?xgqYrTvezk|N#`L>};@%dA@{Qi}L`;)mr-0v2BG4F=d# zE&9C3fX^J~YVy7x{@LbE)&E@86*+RvknmNfIkT% zLaU%(QRo&b(&ph65HRyjsN65LdM}WH(J0A83_q#T(lZYKW)3nGz5`Dg{7ac1prQRF zzH|zHA}QrPnl5swVz)<=0QfPDULDC}Br7F$ut!vF25ci+n%`*v#k_M@wgNs7JL%9^ z9?8nd){_Uje-4Fu^^smZ%>FH#le`g;Aj zF@u@HI~HOsdbS_tqyU|iMg{b@mV($e=O-NA?SC)fxlSg724lagtm<1@o^?y_e)zFH zFq(|9&UUpe8oN!v=d&*e9H@=BeAzPO+SC`4qHzr>iCP@ASaJPxD*F-c^dSHYeKItb z@#|MF$PI(%4ak%j?T6wbRD3t{;Vpp9WnEb3Xxpiy;u5(1cYGZSOI0N3O-Xpbj?&lH z$N2$ES_=zuD7g~qwD_z_*a~0Am1*nBCY?mg<@3EEns2Y zaPwKX{I)#X&${)B(tY`gRElOcxlku&?CCO4ssjH(FQhM7&gkWtN>n#U4Y_W*U6;j(TQ7GL)RM--T0L+pI@Smn&`1=c zic{IYpdu3?gUa~|4GE}ho-7ynX27;YsW)SBhy)IW05@q@P7zndV3#%v)09IaTl@QC z0@+QKp`i^8eHM!}DPA_|UDqhiUj_02BQq-KOg3p_0o2O7z-Voc^=Mwo$dl3ZY>!%% zcjXO-4n+ESTbXdfj&&Rg;k2dhv-&2!Ix$A+Tm%+#F~f<3ZvCPo`6_}jSv8-t&bC>| zoGiS_n)Gc`g{{f>Z^{Rj#iCa(5*N;u%Bw5wV^X5K73FSy5x%RA+@!M{3Z$T;m^E3q z`Y#eW%UQTFhzLgyUTEm15?ZC&)lG&nB**7bPnai{`<^Ygx&cnp0PpegzHIeVA|i@i zbGB)Z4%3F4>f^|%$X-FpFCuvQJMS+oYbt0hdoZk>KqxUTdgtp46|m^hkc$o_jXu}q zc!f_X@@L6Sb6_#oCv)q{e-}#duzPAsrCx`Eq7wxKhQuG)OJBKoKC!gx4c&xpfRV!V zfTeV`xXW$2G0gY}{3Lxf!^6OZ)^b;GxG%fGF^k=HMnPy!djfv)1bgrbSJ=OxsF=29 zk7Y+7qe?GRIjf$4ZfGtHmLXTW* zKHwVo%I^kZO|5^QD-VM9gPNXvWB7S2KawUQYtR6@S#rI-xB+B%x`?JfpWVOqj>PK> za6Q&sBeCGl@8kMqBZaQtDB2)!QKAT2W52ZCFl1`0DzDfZWy3YMzewu2~;wxsMrjJfI51fn>&L3K=S54*Q~pRYtX*pNKO??+N}4(F4UOVT_C7AW3wk) z;#Z-_?0B@P1&9CDM0Nt&?t2mHSsW!>WZSqvv>-Y zt#TL|n*rN#PUMv8_ZSL^7pl2Qny4bIAu38P`8jo0*GE(bZB~`zd#jEPJk`Am4J?m( ztLEkAn4@!INwOaGvOl62B;mC%j~mgpxyt;mbAT83i3wn-Yw>o4rn3F=&2J{$dYxn0 zjiXIWmiB>GXKpIEQx50o*^}^-)BRN?(ubfL|M)*oUgMxUvhtDq)1$Ka-WO5@S?wg) z3;92)UnGdo^usde^Y4HgW-&mq0c+UO#Jbku$xKhr&%IfjfH9k6t|xv1xjb@(O*&PSxu*MH*TCQj~nge$JjF>B?>W)hnu^vv|`=9z6iRns7*P?Z4?dZnO5;aSXhSyD1^v@#N? zGv0_5{h+b~Rh%2F`m_~LZ)*i|&Jvm|rJ`T?O4LY6S3m*pkZsV>L*z)Tnz$1JAshpA zX0_C__ATL$zvWgx+24J7xf73tmF#;`Di~@Tmg!@0T&zt0&|1PRbBl$Q6)?28e4nmr z=I03e)HN09*iRLGTQ4%uL;{1&BwqnuT*uZ=w(>VLm4b|%WpCGOCACuuWY4ZPx%doY z-_!jM>B3e<&!4wga9wAtYA+9W&Cnhi6C1dxU*5tR!$7Z65>%o$wm?15KD~9t?bu4O zM0Rw8N|zB-@yoIghg%|JMWR{nB9-3g!H8!PXe2b530zO*i$nyldL7m;u?uj>k_O9d zkqiC97r{snRy#w{3KrhoI#Gk#jxNuxtF>(zBgcj7EG%ZgEPTJm|vs(Cm;WIy(uCODb+ePfFQ4fALW zQzn$2I~KnHD4}aJ7iX7=%EVo3+fnRD<~sybzqM!e23auxH_>Un;x}H-q(j)rr83in z3;zm(Be&*{e{2wWvmWa)_DFtq6)FdkIM0~yGl$*>&p;sX@V>DmILYYWguc5bH(ML( zKQaw!2}@d5+^OutqVK4EciWEqotE90=*SqpvXZHl4$TFDN#tD1addIr#K~1Kxg^jL zoC|0{liYlMINaqgatJbNX}yPw!+D2;kt;Jh&3{fIYr>ypPvwiS4HNOKUdW@xr(N>D zLfjC4{=}xK_l47s+nGNrtL9cF=ciQ82g~Pv6#OoI@`mK)MQ~|EFVF^>D+G;$=bXur{S+yb{}z8vbI%Sdt;#~*zb5+Qs$AIz3vXfox~#Wn2wI1l zIhBJ1I8-AzjcrCEIgJxgRdY>E_SP1l!RwOf_OK3kMdo_hlI%+Gf&A~+05z}u_&VjC zZVx*-J_)-IArS%3P6HSe|A1z#!3*|B>Wo82IV>O5K41UpCI2EqEps{9Pm~n^dMZx5 zYnbbG7!!}zBE7E@7lr!B&|bVY{V$brQreYC(_8vxFc!jD~5 zTbB(G)@4@t4Vw)!2?Gt5z;AZERBNUW2h@=u>3YLwDrVhti5_B-fbq1I)tI*_O?&;V zPR=FoNGW5=XSKAy-#=|=Yt{jNlr`T^bmlR-kpL}69I!yslq+dOE{VoXJNAh%LqG*^ z+3#%m;6_1N50)y=o`wq8wpX|T=XQ2MYy^^A&-ek307-{@WLJ&o??yMqE1H#Epj$k@ zK3c4nP!i2Z!%#qVdFgi$Su%^ttCh5Jm~gPos@p1t z3uvYCT~v;|G!7WhT^24Yl35UqTrKhzol<*%u!c6MG48sfX|A4itn;oi51IA!<&DSv z2EbydAf6q%s?__Xa!Uqm)Q|q~#w!n21GqH$z(dv zc^mz^d^T(Z9u+*k4Vcr{;|eK%ZdvF2^#Ip1dO%xnS)Di;<7|JmvjdRMetYTYOqnO| zq_0MGz6{s2qQ?jA6bs`TLm$D_|1d)j*5(qDZaO*MaTfH})K?d9d7~nylYluDuv8B} z6TLRRO0!*Sjh=H@pbxjsfiq=3kfUKK{7L^1Cm%qo6(DZOdPj$AbRQgS;cen%8AhPz zw_@o7j_&RDKYNSyTe_l~18gRHE21}FKe`LnAzap$>&n>Y+Lz75|3P_cEAQ4l!I1+-Jin9M<5RiC zN!v?`D&}0ZHD68UN=flnc#bI2m1#)844T8+o)Si8!$VcGXu+MJ&F1ivl`k1qQ)l7lfSzpO^YTa8KEj7 zO2`oli6eeC(%^cXoH7&0jfO++xt$%hrmLZz#HI5*MWBc{8ecN^iv@etY#Jk)CwNrmh$8U zNW=^R!Z~{1_nUC=Koe#2flU)J3m&o9Ukub5r04NASEQydCD*7|j z_*bI>U2k$C=Rh9|N<79W->*`@Pyw1(17||ODX1l{+o7?O&nfLW2Xaw^APY%HtdkpT zUob%SGty=B55oY&h%bO#2=MI8t>}g?DVOpZ@0e#AuK1mqjURih7TS{N~9hI2PnRpC*we5J*gj08itIHGTY8#zJv$k2nO$Af`|#h`P^tj$^nn6f2=Xe!Kr zQw8CJ6>+B7!?i}O#SzN!KmkIsO`*+%=dIMft+qztG>84m5$T`Y6u;ko0d<%UcF6hg z7`@isPt;QkFKP})UrXzJalXSMN8k6vD5v+05WY^*$&k`3rOY}796e{1BKju}Adt__ zAbJ4pGN>vb%o6ef%%hY)mbbRD;j{wsDPD!V%WB*2TN;*qd&vq&e@4=V)bJtKNWL@l z;O%r}LGG2v9yfhh13vsgvY;fWH!LQ!l+WdHe_wkIK4m0{hyE--zZ>+$iC+Dwot*Wg zka1BeDmL!M5?cbmUW3cCP%hmC*|rem@7rK%HFcss+2fmG;&JyT#sKFJzQ> znK+DTJyG+UuVj7}teKk4@*rIR>C$5`JFT z#+7KbaU^PDVW&-4b*Av#cRN)%8(9`>ry{+ItOrM40+MDDjj-rDhHmGtTYT< zhFEAe!pdiDCTD#`#_ysy6tA-)UfzE;0Q$blH+VKKd^2Bvay}2hV~2t;kIS6)y}rlN zUCLlxWXj)9K{DBoP?2L5&_>yPG)97pt(`pCoy^rffyV}UC4AqQHdP*o`*q&-h2w{( zuUUh3j~OnfVUeeG*vR|6i3XsKmgT*8C6QEb)u;D0d5Eq4O_vWBV$>rqryc+LtX{2b zD?lkwGz}KUji|wQ*th;Y=90I|TZ8*5aZ`fxTP}>r>Xl57)GJH%Xt6CM%QeW(3edzR zfWpYZ1^9*$K4>g8EszcxF#0-?fML$gJ`I@GTVBzUxeInWz5ND3)a(SIvyocfk@M~*ihEQZ&15bel)_j1I}7!=$gkb=R4NoLSo z6mD>Y?87!(ZgHDnUui(x9f(@dXLx}wi#)LxB5&*lP-Ce?Z$};dk4j1_;=t1ammQkH z1ddP>`Z|T`fj9*C2U za)-u;PsudAj$#tzu5(^E}6lvK8S!XDXUp<@x9-kkj%P2R$&QxPQgn;Df)We0YsMQs>Zk)q}-m2kzS9T1&+a?>3*}bI^_l zE=`>Jp+#CMx;G%Cr^yrNi@nIiNaX}A?;mDOu%CUtXCbidc)RJ?u_e4u(ms16G=7An zPeQaem$qHIqkt(`F4c`yxyIFTq3ANg-4OZ5-!yCs+wnb7fL~5^ zcRo0J7u2#`VGkqolT2{~LlI%`h!yxDfTiotk0+tOB(omO6-`=!zG`ap9F~~%ri#{& zg~23SUVzqM^C}(iNOH$fYKuU$U{ili2(3vQr8Qh;FHxokh2L|+{|>v!++F6^nI9|UGKDiuT?{WlmIg>|aXso)EHs5RY8$*H zByQ9D&lD+J`P1DmjL&MtYM{TbTI(lEL_052RnDsZh;PWC``|hnB`;JRq#)Lots$-#c z_$hwMDr5Lg-zH;#?CZe&s|#O|gN@AM{**3xTN7g}_MirbV+^Bco$@4e?eP7x2Kz=G z7LC&v&vZ(DUHLb{mVd-|kGPOq9>< zS@I=dRuV>Totr_-maU@0sL@9Pv(C*PQdhtbX{ihrHS~$%?89e%s?r5o%(R$~@1>wT z>`@329lfu`R<2R1#^~0%Y*RnHPZ)*IW?|8B;P~glXzrm{Rb8E#2CLn1Gela7dPz-d z>%q^F)J0qigBEzpBV3dFsxW5s`>L;Nz)3KHxzMF4hxXGHbL5dy164CW`DA&j!mSX*BA3F#AX++Mx5u6IGdly^LlXZ9*E{5843JVuaQVDD-X3 zGkvIMNR-Xo+Bmu>%7CylqTgRV%cUpg2pQEHjQJEEkhw*3`6Y$r!nb3=&S9eX9x=cJ z)kU%Z+P>_-dwXYkl%D(=-3a@iS60lrG7)9`MTa5%)8P$H8Z&n7oapG6)AQU}xZaHD6@x3yI+{r5D$jWoAFBi3@xs&wC&;yzN&Dgj{xX0HqqJVOZTINzc)~gOjoeq_LtS-`&&3k}q#KIE2qQgwc zz!LQ7;!Y8mr0VEIENXgZ&I1pL@8gnL)DR;Au<>bB&L<}Uu0Cj-?wzx$d(zJCSf42NU>pHbYT*sEtOP)5Q?c|sJ(S1ya< zKoZ@}J2B7>3tG6rD@Aq7{unUG!Rr+&5CZ`(u`_) in +Ceres Solver. This is done in two steps: + + 1. Define *Functor* that given the parameter values will evaluate the + residual for a given :math:`(x,y)`. + 2. Construct a :class:`CostFunction` by using + :class:`NumericDiffCostFunction` to wrap an instance of + ``Rat43CostFunctor``. + +.. code-block:: c++ + + struct Rat43CostFunctor { + Rat43CostFunctor(const double x, const double y) : x_(x), y_(y) {} + + bool operator()(const double* parameters, double* residuals) const { + const double b1 = parameters[0]; + const double b2 = parameters[1]; + const double b3 = parameters[2]; + const double b4 = parameters[3]; + residuals[0] = b1 * pow(1.0 + exp(b2 - b3 * x_), -1.0 / b4) - y_; + return true; + } + + const double x_; + const double y_; + } + + CostFunction* cost_function = + new NumericDiffCostFunction( + new Rat43CostFunctor(x, y)); + +This is about the minimum amount of work one can expect to do to +define the cost function. The only thing that the user needs to do is +to make sure that the evaluation of the residual is implemented +correctly and efficiently. + +Before going further, it is instructive to get an estimate of the +error in the forward difference formula. We do this by considering the +`Taylor expansion `_ of +:math:`f` near :math:`x`. + +.. math:: + \begin{align} + f(x+h) &= f(x) + h Df(x) + \frac{h^2}{2!} D^2f(x) + + \frac{h^3}{3!}D^3f(x) + \cdots \\ + Df(x) &= \frac{f(x + h) - f(x)}{h} - \left [\frac{h}{2!}D^2f(x) + + \frac{h^2}{3!}D^3f(x) + \cdots \right]\\ + Df(x) &= \frac{f(x + h) - f(x)}{h} + O(h) + \end{align} + +i.e., the error in the forward difference formula is +:math:`O(h)` [#f4]_. + + +Implementation Details +---------------------- + +:class:`NumericDiffCostFunction` implements a generic algorithm to +numerically differentiate a given functor. While the actual +implementation of :class:`NumericDiffCostFunction` is complicated, the +net result is a :class:`CostFunction` that roughly looks something +like the following: + +.. code-block:: c++ + + class Rat43NumericDiffForward : public SizedCostFunction<1,4> { + public: + Rat43NumericDiffForward(const Rat43Functor* functor) : functor_(functor) {} + virtual ~Rat43NumericDiffForward() {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + functor_(parameters[0], residuals); + if (!jacobians) return true; + double* jacobian = jacobians[0]; + if (!jacobian) return true; + + const double f = residuals[0]; + double parameters_plus_h[4]; + for (int i = 0; i < 4; ++i) { + std::copy(parameters, parameters + 4, parameters_plus_h); + const double kRelativeStepSize = 1e-6; + const double h = std::abs(parameters[i]) * kRelativeStepSize; + parameters_plus_h[i] += h; + double f_plus; + functor_(parameters_plus_h, &f_plus); + jacobian[i] = (f_plus - f) / h; + } + return true; + } + + private: + scoped_ptr functor_; + }; + + +Note the choice of step size :math:`h` in the above code, instead of +an absolute step size which is the same for all parameters, we use a +relative step size of :math:`\text{kRelativeStepSize} = 10^{-6}`. This +gives better derivative estimates than an absolute step size [#f2]_ +[#f3]_. This choice of step size only works for parameter values that +are not close to zero. So the actual implementation of +:class:`NumericDiffCostFunction`, uses a more complex step size +selection logic, where close to zero, it switches to a fixed step +size. + + +Central Differences +=================== + +:math:`O(h)` error in the Forward Difference formula is okay but not +great. A better method is to use the *Central Difference* formula: + +.. math:: + Df(x) \approx \frac{f(x + h) - f(x - h)}{2h} + +Notice that if the value of :math:`f(x)` is known, the Forward +Difference formula only requires one extra evaluation, but the Central +Difference formula requires two evaluations, making it twice as +expensive. So is the extra evaluation worth it? + +To answer this question, we again compute the error of approximation +in the central difference formula: + +.. math:: + \begin{align} + f(x + h) &= f(x) + h Df(x) + \frac{h^2}{2!} + D^2f(x) + \frac{h^3}{3!} D^3f(x) + \frac{h^4}{4!} D^4f(x) + \cdots\\ + f(x - h) &= f(x) - h Df(x) + \frac{h^2}{2!} + D^2f(x) - \frac{h^3}{3!} D^3f(c_2) + \frac{h^4}{4!} D^4f(x) + + \cdots\\ + Df(x) & = \frac{f(x + h) - f(x - h)}{2h} + \frac{h^2}{3!} + D^3f(x) + \frac{h^4}{5!} + D^5f(x) + \cdots \\ + Df(x) & = \frac{f(x + h) - f(x - h)}{2h} + O(h^2) + \end{align} + +The error of the Central Difference formula is :math:`O(h^2)`, i.e., +the error goes down quadratically whereas the error in the Forward +Difference formula only goes down linearly. + +Using central differences instead of forward differences in Ceres +Solver is a simple matter of changing a template argument to +:class:`NumericDiffCostFunction` as follows: + +.. code-block:: c++ + + CostFunction* cost_function = + new NumericDiffCostFunction( + new Rat43CostFunctor(x, y)); + +But what do these differences in the error mean in practice? To see +this, consider the problem of evaluating the derivative of the +univariate function + +.. math:: + f(x) = \frac{e^x}{\sin x - x^2}, + +at :math:`x = 1.0`. + +It is easy to determine that :math:`Df(1.0) = +140.73773557129658`. Using this value as reference, we can now compute +the relative error in the forward and central difference formulae as a +function of the absolute step size and plot them. + +.. figure:: forward_central_error.png + :figwidth: 100% + :align: center + +Reading the graph from right to left, a number of things stand out in +the above graph: + + 1. The graph for both formulae have two distinct regions. At first, + starting from a large value of :math:`h` the error goes down as + the effect of truncating the Taylor series dominates, but as the + value of :math:`h` continues to decrease, the error starts + increasing again as roundoff error starts to dominate the + computation. So we cannot just keep on reducing the value of + :math:`h` to get better estimates of :math:`Df`. The fact that we + are using finite precision arithmetic becomes a limiting factor. + 2. Forward Difference formula is not a great method for evaluating + derivatives. Central Difference formula converges much more + quickly to a more accurate estimate of the derivative with + decreasing step size. So unless the evaluation of :math:`f(x)` is + so expensive that you absolutely cannot afford the extra + evaluation required by central differences, **do not use the + Forward Difference formula**. + 3. Neither formula works well for a poorly chosen value of :math:`h`. + + +Ridders' Method +=============== + +So, can we get better estimates of :math:`Df` without requiring such +small values of :math:`h` that we start hitting floating point +roundoff errors? + +One possible approach is to find a method whose error goes down faster +than :math:`O(h^2)`. This can be done by applying `Richardson +Extrapolation +`_ to the +problem of differentiation. This is also known as *Ridders' Method* +[Ridders]_. + +Let us recall, the error in the central differences formula. + +.. math:: + \begin{align} + Df(x) & = \frac{f(x + h) - f(x - h)}{2h} + \frac{h^2}{3!} + D^3f(x) + \frac{h^4}{5!} + D^5f(x) + \cdots\\ + & = \frac{f(x + h) - f(x - h)}{2h} + K_2 h^2 + K_4 h^4 + \cdots + \end{align} + +The key thing to note here is that the terms :math:`K_2, K_4, ...` +are indepdendent of :math:`h` and only depend on :math:`x`. + +Let us now define: + +.. math:: + + A(1, m) = \frac{f(x + h/2^{m-1}) - f(x - h/2^{m-1})}{2h/2^{m-1}}. + +Then observe that + +.. math:: + + Df(x) = A(1,1) + K_2 h^2 + K_4 h^4 + \cdots + +and + +.. math:: + + Df(x) = A(1, 2) + K_2 (h/2)^2 + K_4 (h/2)^4 + \cdots + +Here we have halved the step size to obtain a second central +differences estimate of :math:`Df(x)`. Combining these two estimates, +we get: + +.. math:: + + Df(x) = \frac{4 A(1, 2) - A(1,1)}{4 - 1} + O(h^4) + +which is an approximation of :math:`Df(x)` with truncation error that +goes down as :math:`O(h^4)`. But we do not have to stop here. We can +iterate this process to obtain even more accurate estimates as +follows: + +.. math:: + + A(n, m) = \begin{cases} + \frac{\displaystyle f(x + h/2^{m-1}) - f(x - + h/2^{m-1})}{\displaystyle 2h/2^{m-1}} & n = 1 \\ + \frac{\displaystyle 4^{n-1} A(n - 1, m + 1) - A(n - 1, m)}{\displaystyle 4^{n-1} - 1} & n > 1 + \end{cases} + +It is straightforward to show that the approximation error in +:math:`A(n, 1)` is :math:`O(h^{2n})`. To see how the above formula can +be implemented in practice to compute :math:`A(n,1)` it is helpful to +structure the computation as the following tableau: + +.. math:: + \begin{array}{ccccc} + A(1,1) & A(1, 2) & A(1, 3) & A(1, 4) & \cdots\\ + & A(2, 1) & A(2, 2) & A(2, 3) & \cdots\\ + & & A(3, 1) & A(3, 2) & \cdots\\ + & & & A(4, 1) & \cdots \\ + & & & & \ddots + \end{array} + +So, to compute :math:`A(n, 1)` for increasing values of :math:`n` we +move from the left to the right, computing one column at a +time. Assuming that the primary cost here is the evaluation of the +function :math:`f(x)`, the cost of computing a new column of the above +tableau is two function evaluations. Since the cost of evaluating +:math:`A(1, n)`, requires evaluating the central difference formula +for step size of :math:`2^{1-n}h` + +Applying this method to :math:`f(x) = \frac{e^x}{\sin x - x^2}` +starting with a fairly large step size :math:`h = 0.01`, we get: + +.. math:: + \begin{array}{rrrrr} + 141.678097131 &140.971663667 &140.796145400 &140.752333523 &140.741384778\\ + &140.736185846 &140.737639311 &140.737729564 &140.737735196\\ + & &140.737736209 &140.737735581 &140.737735571\\ + & & &140.737735571 &140.737735571\\ + & & & &140.737735571\\ + \end{array} + +Compared to the *correct* value :math:`Df(1.0) = 140.73773557129658`, +:math:`A(5, 1)` has a relative error of :math:`10^{-13}`. For +comparison, the relative error for the central difference formula with +the same stepsize (:math:`0.01/2^4 = 0.000625`) is :math:`10^{-5}`. + +The above tableau is the basis of Ridders' method for numeric +differentiation. The full implementation is an adaptive scheme that +tracks its own estimation error and stops automatically when the +desired precision is reached. Of course it is more expensive than the +forward and central difference formulae, but is also significantly +more robust and accurate. + +Using Ridder's method instead of forward or central differences in +Ceres is again a simple matter of changing a template argument to +:class:`NumericDiffCostFunction` as follows: + +.. code-block:: c++ + + CostFunction* cost_function = + new NumericDiffCostFunction( + new Rat43CostFunctor(x, y)); + +The following graph shows the relative error of the three methods as a +function of the absolute step size. For Ridders's method we assume +that the step size for evaluating :math:`A(n,1)` is :math:`2^{1-n}h`. + +.. figure:: forward_central_ridders_error.png + :figwidth: 100% + :align: center + +Using the 10 function evaluations that are needed to compute +:math:`A(5,1)` we are able to approximate :math:`Df(1.0)` about a 1000 +times better than the best central differences estimate. To put these +numbers in perspective, machine epsilon for double precision +arithmetic is :math:`\approx 2.22 \times 10^{-16}`. + +Going back to ``Rat43``, let us also look at the runtime cost of the +various methods for computing numeric derivatives. + +========================== ========= +CostFunction Time (ns) +========================== ========= +Rat43Analytic 255 +Rat43AnalyticOptimized 92 +Rat43NumericDiffForward 262 +Rat43NumericDiffCentral 517 +Rat43NumericDiffRidders 3760 +========================== ========= + +As expected, Central Differences is about twice as expensive as +Forward Differences and the remarkable accuracy improvements of +Ridders' method cost an order of magnitude more runtime. + +Recommendations +=============== + +Numeric differentiation should be used when you cannot compute the +derivatives either analytically or using automatic differention. This +is usually the case when you are calling an external library or +function whose analytic form you do not know or even if you do, you +are not in a position to re-write it in a manner required to use +:ref:`chapter-automatic_derivatives`. + + +When using numeric differentiation, use at least Central Differences, +and if execution time is not a concern or the objective function is +such that determining a good static relative step size is hard, +Ridders' method is recommended. + +.. rubric:: Footnotes + +.. [#f2] `Numerical Differentiation + `_ +.. [#f3] [Press]_ Numerical Recipes, Section 5.7 +.. [#f4] In asymptotic error analysis, an error of :math:`O(h^k)` + means that the absolute-value of the error is at most some + constant times :math:`h^k` when :math:`h` is close enough to + :math:`0`. diff --git a/docs/source/pose_graph_3d_ex.png b/docs/source/pose_graph_3d_ex.png new file mode 100644 index 0000000000000000000000000000000000000000..ae2cfc389a0f04c3e3ab1cb5b1eb7616a1da354c GIT binary patch literal 105676 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 Pd}*m2Q+=vpaqa&B=yJ_J literal 0 HcmV?d00001 diff --git a/docs/source/robust_least_squares_fit.png b/docs/source/robust_least_squares_fit.png new file mode 100644 index 0000000000000000000000000000000000000000..89003c9f695a687f0ebf6ae0a27385c5980755dc GIT binary patch literal 53967 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 Q2ZKPQB^BP3iW`3ZUr+x6!TXys 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 literal 0 HcmV?d00001 diff --git a/docs/source/solving_faqs.rst b/docs/source/solving_faqs.rst new file mode 100644 index 0000000..64604c4 --- /dev/null +++ b/docs/source/solving_faqs.rst @@ -0,0 +1,171 @@ +.. _chapter-solving_faqs: + +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +======= +Solving +======= + +#. How do I evaluate the Jacobian for a solved problem? + + Using :func:`Problem::Evaluate`. + +#. How do I choose the right linear solver? + + When using the ``TRUST_REGION`` minimizer, the choice of linear + solver is an important decision. It affects solution quality and + runtime. Here is a simple way to reason about it. + + 1. For small (a few hundred parameters) or dense problems use + ``DENSE_QR``. + + 2. For general sparse problems (i.e., the Jacobian matrix has a + substantial number of zeros) use + ``SPARSE_NORMAL_CHOLESKY``. This requires that you have + ``SuiteSparse`` or ``CXSparse`` installed. + + 3. For bundle adjustment problems with up to a hundred or so + cameras, use ``DENSE_SCHUR``. + + 4. For larger bundle adjustment problems with sparse Schur + Complement/Reduced camera matrices use ``SPARSE_SCHUR``. This + requires that you build Ceres with support for ``SuiteSparse``, + ``CXSparse`` or Eigen's sparse linear algebra libraries. + + If you do not have access to these libraries for whatever + reason, ``ITERATIVE_SCHUR`` with ``SCHUR_JACOBI`` is an + excellent alternative. + + 5. For large bundle adjustment problems (a few thousand cameras or + more) use the ``ITERATIVE_SCHUR`` solver. There are a number of + preconditioner choices here. ``SCHUR_JACOBI`` offers an + excellent balance of speed and accuracy. This is also the + recommended option if you are solving medium sized problems for + which ``DENSE_SCHUR`` is too slow but ``SuiteSparse`` is not + available. + + .. NOTE:: + + If you are solving small to medium sized problems, consider + setting ``Solver::Options::use_explicit_schur_complement`` to + ``true``, it can result in a substantial performance boost. + + If you are not satisfied with ``SCHUR_JACOBI``'s performance try + ``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL`` in that + order. They require that you have ``SuiteSparse`` + installed. Both of these preconditioners use a clustering + algorithm. Use ``SINGLE_LINKAGE`` before ``CANONICAL_VIEWS``. + +#. Use :func:`Solver::Summary::FullReport` to diagnose performance problems. + + When diagnosing Ceres performance issues - runtime and convergence, + the first place to start is by looking at the output of + ``Solver::Summary::FullReport``. Here is an example + + .. code-block:: bash + + ./bin/bundle_adjuster --input ../data/problem-16-22106-pre.txt + + iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time + 0 4.185660e+06 0.00e+00 2.16e+07 0.00e+00 0.00e+00 1.00e+04 0 7.50e-02 3.58e-01 + 1 1.980525e+05 3.99e+06 5.34e+06 2.40e+03 9.60e-01 3.00e+04 1 1.84e-01 5.42e-01 + 2 5.086543e+04 1.47e+05 2.11e+06 1.01e+03 8.22e-01 4.09e+04 1 1.53e-01 6.95e-01 + 3 1.859667e+04 3.23e+04 2.87e+05 2.64e+02 9.85e-01 1.23e+05 1 1.71e-01 8.66e-01 + 4 1.803857e+04 5.58e+02 2.69e+04 8.66e+01 9.93e-01 3.69e+05 1 1.61e-01 1.03e+00 + 5 1.803391e+04 4.66e+00 3.11e+02 1.02e+01 1.00e+00 1.11e+06 1 1.49e-01 1.18e+00 + + Ceres Solver v1.12.0 Solve Report + ---------------------------------- + Original Reduced + Parameter blocks 22122 22122 + Parameters 66462 66462 + Residual blocks 83718 83718 + Residual 167436 167436 + + Minimizer TRUST_REGION + + Sparse linear algebra library SUITE_SPARSE + Trust region strategy LEVENBERG_MARQUARDT + + Given Used + Linear solver SPARSE_SCHUR SPARSE_SCHUR + Threads 1 1 + Linear solver threads 1 1 + Linear solver ordering AUTOMATIC 22106, 16 + + Cost: + Initial 4.185660e+06 + Final 1.803391e+04 + Change 4.167626e+06 + + Minimizer iterations 5 + Successful steps 5 + Unsuccessful steps 0 + + Time (in seconds): + Preprocessor 0.283 + + Residual evaluation 0.061 + Jacobian evaluation 0.361 + Linear solver 0.382 + Minimizer 0.895 + + Postprocessor 0.002 + Total 1.220 + + Termination: NO_CONVERGENCE (Maximum number of iterations reached.) + + Let us focus on run-time performance. The relevant lines to look at + are + + + .. code-block:: bash + + Time (in seconds): + Preprocessor 0.283 + + Residual evaluation 0.061 + Jacobian evaluation 0.361 + Linear solver 0.382 + Minimizer 0.895 + + Postprocessor 0.002 + Total 1.220 + + + Which tell us that of the total 1.2 seconds, about .3 seconds was + spent in the linear solver and the rest was mostly spent in + preprocessing and jacobian evaluation. + + The preprocessing seems particularly expensive. Looking back at the + report, we observe + + .. code-block:: bash + + Linear solver ordering AUTOMATIC 22106, 16 + + Which indicates that we are using automatic ordering for the + ``SPARSE_SCHUR`` solver. This can be expensive at times. A straight + forward way to deal with this is to give the ordering manually. For + ``bundle_adjuster`` this can be done by passing the flag + ``-ordering=user``. Doing so and looking at the timing block of the + full report gives us + + .. code-block:: bash + + Time (in seconds): + Preprocessor 0.051 + + Residual evaluation 0.053 + Jacobian evaluation 0.344 + Linear solver 0.372 + Minimizer 0.854 + + Postprocessor 0.002 + Total 0.935 + + + + The preprocessor time has gone down by more than 5.5x!. diff --git a/docs/source/spivak_notation.rst b/docs/source/spivak_notation.rst new file mode 100644 index 0000000..3ac56ba --- /dev/null +++ b/docs/source/spivak_notation.rst @@ -0,0 +1,53 @@ +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-spivak_notation: + +=============== +Spivak Notation +=============== + +To preserve our collective sanities, we will use Spivak's notation for +derivatives. It is a functional notation that makes reading and +reasoning about expressions involving derivatives simple. + +For a univariate function :math:`f`, :math:`f(a)` denotes its value at +:math:`a`. :math:`Df` denotes its first derivative, and +:math:`Df(a)` is the derivative evaluated at :math:`a`, i.e + +.. math:: + Df(a) = \left . \frac{d}{dx} f(x) \right |_{x = a} + +:math:`D^kf` denotes the :math:`k^{\text{th}}` derivative of :math:`f`. + +For a bi-variate function :math:`g(x,y)`. :math:`D_1g` and +:math:`D_2g` denote the partial derivatives of :math:`g` w.r.t the +first and second variable respectively. In the classical notation this +is equivalent to saying: + +.. math:: + + D_1 g = \frac{\partial}{\partial x}g(x,y) \text{ and } D_2 g = \frac{\partial}{\partial y}g(x,y). + + +:math:`Dg` denotes the Jacobian of `g`, i.e., + +.. math:: + + Dg = \begin{bmatrix} D_1g & D_2g \end{bmatrix} + +More generally for a multivariate function :math:`g:\mathbb{R}^n +\longrightarrow \mathbb{R}^m`, :math:`Dg` denotes the :math:`m\times +n` Jacobian matrix. :math:`D_i g` is the partial derivative of +:math:`g` w.r.t the :math:`i^{\text{th}}` coordinate and the +:math:`i^{\text{th}}` column of :math:`Dg`. + +Finally, :math:`D^2_1g` and :math:`D_1D_2g` have the obvious meaning +as higher order partial derivatives. + +For more see Michael Spivak's book `Calculus on Manifolds +`_ +or a brief discussion of the `merits of this notation +`_ by +Mitchell N. Charity. diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst new file mode 100644 index 0000000..a3fd212 --- /dev/null +++ b/docs/source/tutorial.rst @@ -0,0 +1,11 @@ +.. _chapter-tutorial: + +======== +Tutorial +======== + +.. toctree:: + :maxdepth: 3 + + nnls_tutorial + gradient_tutorial diff --git a/docs/source/users.rst b/docs/source/users.rst new file mode 100644 index 0000000..42f66b9 --- /dev/null +++ b/docs/source/users.rst @@ -0,0 +1,75 @@ +.. _chapter-users: + +===== +Users +===== + +* At `Google `_, Ceres is used to: + + * Estimate the pose of `Street View`_ cars, aircrafts, and satellites. + * Build 3D models for `PhotoTours`_. + * Estimate satellite image sensor characteristics. + * Stitch `panoramas`_ on Android and iOS. + * Apply `Lens Blur`_ on Android. + * Solve `bundle adjustment`_ and `SLAM`_ problems in `Project + Tango`_. + +* `Willow Garage`_ uses Ceres to solve `SLAM`_ problems. +* `Southwest Research Institute `_ uses Ceres for + `calibrating robot-camera systems`_. +* `Blender `_ uses Ceres for `planar + tracking`_ and `bundle adjustment`_. +* `OpenMVG `_ an open source + multi-view geometry library uses Ceres for `bundle adjustment`_. +* `Microsoft Research `_ uses + Ceres for nonlinear optimization of objectives involving subdivision + surfaces under `skinned control meshes`_. +* `Matterport `_, uses Ceres for global + alignment of 3D point clouds and for pose graph optimization. +* `Obvious Engineering `_ uses Ceres for + bundle adjustment for their 3D photography app `Seene + `_. +* The `Autonomous Systems Lab `_ at ETH + Zurich uses Ceres for + + * Camera and Camera/IMU Calibration. + * Large scale optimization of visual, inertial, gps and + wheel-odometry data for long term autonomy. + +* `OpenPTrack `_ uses Ceres for camera + calibration. +* The `Intelligent Autonomous System Lab `_ + at University of Padova, Italy, uses Ceres for + + * Camera/depth sensors network calibration. + * Depth sensor distortion map estimation. + +* `Theia `_ is an open source + Structure from Motion library that uses Ceres for `bundle adjustment`_ + and camera pose estimation. + +* The `Applied Research Laboratory `_ at + Pennsylvania State University uses in their synthetic aperture Sonar + beamforming engine, called ASASIN , for estimating platform + kinematics. + +* `Colmap `_ is a an open source + structure from motion library that makes heavy use of Ceres for + bundle adjustment with support for many camera models and for other + non-linear least-squares problems (relative, absolute pose + refinement, etc.). + + + +.. _bundle adjustment: http://en.wikipedia.org/wiki/Structure_from_motion +.. _Street View: http://youtu.be/z00ORu4bU-A +.. _PhotoTours: http://google-latlong.blogspot.com/2012/04/visit-global-landmarks-with-photo-tours.html +.. _panoramas: http://www.google.com/maps/about/contribute/photosphere/ +.. _Project Tango: https://www.google.com/atap/projecttango/ +.. _planar tracking: http://mango.blender.org/development/planar-tracking-preview/ +.. _Willow Garage: https://www.willowgarage.com/blog/2013/08/09/enabling-robots-see-better-through-improved-camera-calibration +.. _Lens Blur: http://googleresearch.blogspot.com/2014/04/lens-blur-in-new-google-camera-app.html +.. _SLAM: http://en.wikipedia.org/wiki/Simultaneous_localization_and_mapping +.. _calibrating robot-camera systems: + http://rosindustrial.org/news/2014/9/24/industrial-calibration-library-update-and-presentation +.. _skinned control meshes: http://research.microsoft.com/en-us/projects/handmodelingfrommonoculardepth/ diff --git a/docs/source/version_history.rst b/docs/source/version_history.rst new file mode 100644 index 0000000..de968a9 --- /dev/null +++ b/docs/source/version_history.rst @@ -0,0 +1,1306 @@ +.. _chapter-version-history: + +=============== +Version History +=============== + +1.13.0 +====== + +New Features +------------ +#. ``LineSearchMinimizer`` and ``GradientProblemSolver`` are up to 2x + faster due to fewer function evaluations. (Sameer Agarwal) +#. ``SPARSE_NORMAL_CHOLESKY`` is significantly faster because Ceres + now computes the normal equations exploiting the static block + sparsity structure. (Cheng Wang & Sameer Agarwal) +#. Add compound with scalar operators for Jets. (Alex Stewart) +#. Enable support for AVX instructions for Jets. (Alex Stewart) + +Backward Incompatible API Changes +--------------------------------- +The enum ``CovarianceAlgorithmType`` which controls the linear algebra +algorithm used to compute the covariance used to combine the choice of +the algorithm and the choice of the sparse linear algebra library into +the enum name. So we had ``SUITE_SPARSE_QR`` and +``EIGEN_SPARSE_QR``. ``Covariance::Options`` now has a separate member +allowing the user to choose the sparse linear algebra library, just +like the solver and ``CovarianceAlgorithmType`` now takes values +``DENSE_SVD`` and ``SPARSE_QR``. This is a forward looking change that +will allow us to develop more flexible covariance estimation +algorithms with multiple linear algebra backends. + +Bug Fixes & Minor Changes +------------------------- +#. Fix ``InvertPSDMatrix`` as it was triggering an Eigen assert in + Debug mode. (Philipp Hubner) +#. Fix cmake error from CeresConfig.cmake when Ceres not found (Taylor + Braun-Jones) +#. Completely refactored ``SparseNormalCholeskySolver``. (Sameer + Agarwal) +#. Fixed time reporting in ``Summary::FullReport`` when + ``LineSearchMinimizer`` is used. (Sameer Agarwal) +#. Remove unused file: collections_port.cc. (Sameer Agarwal) +#. ``SPARSE_SCHUR`` + ``CX_SPARSE`` = Faster (Sameer Agarwal) +#. Refactored a number of linear solver tests to be more thorough and + informative. (Sameer Agarwal) +#. Pass user-specified search hints as HINTS not PATHS. (Alex Stewart) +#. Prefer Eigen installs over exported build directories. (Alex + Stewart) +#. Add OpenMP flags when compiling for C if enabled. (Alex Stewart) +#. Add a missing ``CERES_EXPORT`` to GradientChecker (Sameer Agarwal) +#. Use target_compile_features() to specify C++11 requirement if + available. (Alex Stewart) +#. Update docs: .netrc --> .gitcookies (Keir Mierle) +#. Fix implicit precission loss warning on 64-bit archs (Ricardo + Sanchez-Saez) +#. Optionally use exported Eigen CMake configuration if + available. (Alex Stewart) +#. Use ``Ceres_[SOURCE/BINARY]_DIR`` not ``CMAKE_XXX_DIR`` to support + nesting. (Alex Stewart) +#. Update ``Problem::EvaluateOptions`` documentation. (Sameer Agarwal) +#. Add public headers to CMake target for IDEs. (Devin Lane) +#. Add an article on interfacing with automatic + differentiation. (Sameer Agarwal) +#. Add default Fedora/Debian locations for CXSparse to search + paths. (Alex Stewart) +#. Add a test for ``LineSearchMinimizer`` (Sameer Agarwal) +#. Flatten the table of contents. (Sameer Agarwal) +#. Fix when ``LineSearchMinimizer`` adds the ``IterationSummary``` to + ``Solver::Summary`` (Sameer Agarwal) +#. Fix search path for miniglog headers when Ceres is exported. (Alex + Stewart) +#. Fix ambiguous reference to ``WARNING`` when using miniglog. (Alex + Stewart) +#. Fix Jet/Eigen compatibility for Eigen > 3.3 (Julien Pilet) +#. Add max severity option when ``MINIGLOG`` is enabled (Taylor + Braun-Jones) +#. Improvements to Schur template specializations (Sameer Agarwal) +#. Added an article on derivatives (Sameer Agarwal) +#. Require Eigen >= 3.3 to define ScalarBinaryOpTraits in Jet. (Alex + Stewart) +#. A hacky fix for the Eigen::FullPivLU changes. (Sameer Agarwal) +#. Specify ``ScalarBinaryOpTraits`` for Jet types. (Chris Sweeney) +#. Remove spurious conversion from doubles to Jets. (Sameer Agarwal) +#. Fix an error in the tutorial code for ``NumericDiffCostFunction`` + (Sameer Agarwal) +#. ``CERES_EXPORT`` fix to compile Ceres as DLL (Je Hyeong Hong) +#. Fix detection of deprecated Bessel function names on MSVC. (Alex + Stewart) +#. Ensure that partial evaluation of residuals triggers an error + (Sameer Agarwal) +#. Fix detection of CMake-built glog on Windows. (Alex Stewart) +#. Add additional search paths for glog & Eigen on Windows. (Alex + Stewart) +#. Various minor grammar and bug fixes to the documentation (Sameer + Agarwal, Alex Stewart, William Rucklidge) + + +1.12.0 +====== + +New Features +------------ +#. Aligned ``Jet`` matrices for improved automatic differentiation + performance. (Andrew Hunter) +#. Auto-differentiable implementations of Bessel functions, ``floor``, + and ``ceil`` (Alessandro Gentilini & Michael Vitus) +#. New 2D and 3D SLAM examples. (Michael Vitus) +#. Added ``EigenQuaternionParameterization``. (Michael Vitus) +#. Added ``Problem::IsParameterBlockConstant`` (Thomas Schneider) +#. A complete refactoring of ``TrustRegionMinimizer``. (Sameer Agarwal) +#. Gradient checking cleanup and local parameterization bugfix (David + Gossow) + + +Backward Incompatible API Changes +--------------------------------- +#. ``Solver::Options::numeric_derivative_relative_step_size`` has been + renamed to + ``Solver::Options::gradient_check_numeric_derivative_relative_step_size``. (Sameer + Agarwal) + +Bug Fixes & Minor Changes +------------------------- +#. Clear XXX_FOUND in Find.cmake prior to searching. (Alex + Stewart) +#. Fix versioning in the documentation (Sameer Agarwal) +#. Fix missing gflags imported target definition in + CeresConfig.cmake. (Alex Stewart) +#. Make gflags a public dependency of Ceres if it and glog are + found. (Alex Stewart) +#. Add support for glog exported CMake target. (Alex Stewart) +#. Use ``google::GLOG_WARNING`` instead of ``WARNING`` in tests to + support MSVC. (Alex Stewart) +#. Update gtest and gmock to + ``a2b8a8e07628e5fd60644b6dd99c1b5e7d7f1f47`` (Sameer Agarwal) +#. Add MSVC-specific ``#define`` to expose math constants in + ````. (Alex Stewart) +#. Fix typo. indepdendent -> independent (Hung Lun) +#. Fix potential invalid reset of CMAKE_FIND_LIBRARY_PREFIXES on MSVC + (Alex Stewart) +#. Fix use of alignas(0) which is not ignored on GCC (Alex Stewart) +#. Use default alignment if alignof(std::max_align_t) < 16 with C++11 + (Alex Stewart) +#. Introduce a common base class for DynamicAutoDiffCostFunction and + DynamicNumericDiffCostFunction. (Sameer Agarwal) +#. Fix an exact equality test causing breakage in + gradient_checker_test. (Sameer Agarwal) +#. Add GradientProblemSolver::Options::parameter_tolerance. (Sameer + Agarwal) +#. Add missing T() wrappers for constants. (Rob Carroll) +#. Remove two checks from rotation.h (Sameer Agarwal) +#. Relax the tolerance in QuaternionParameterizationTestHelper. (Je + Hyeong Hong) +#. Occured -> Occurred. (Sameer Agarwal) +#. Fix a test error in autodiff_test.cc. (Je Hyeong Hong) +#. Fix documentation source for templated function in ``rotation.h``. +#. Add ``package.xml`` to enable Catkin builds. (Damon Kohler) +#. Relaxing Jacobian matching in Gradient Checker test. (David Gossow) +#. Allow SubsetParameterization to hold all parameters constant + (Sameer Agarwal) +#. Fix an Intel compiler error in covariance_impl.cc (Je Hyeong Hong) +#. Removing duplicate include directive. (David Gossow) +#. Remove two DCHECKs from CubicHermiteSpline. (Sameer Agarwal) +#. Fix some compiler warnings. (Richard Trieu) +#. Update ExpectArraysClose to use ExpectClose instead of + EXPECT_NEAR. (Phillip Hubner) +#. FindWithDefault returns by value rather than reference. (@aradval) +#. Fix compiler errors on some systems. (David Gossow) +#. Note that Problem::Evaluate cannot be called from an + IterationCallback. (Sameer Agarwal) +#. Use ProductParameterization in bundle_adjuster.cc (Sameer Agarwal) +#. Enable support for OpenMP in Clang if detected. (Alex Stewart) +#. Remove duplicate entry for the NIST example in the docs. (Michael + Vitus) +#. Add additional logging for analyzing orderings (Sameer Agarwal) +#. Add readme for the sampled_function example. (Michael Vitus) +#. Use _j[0,1,n]() Bessel functions on MSVC to avoid deprecation + errors. (Alex Stewart & Kichang Kim) +#. Fix: Copy minimizer option ``is_silent`` to + ``LineSearchDirection::Options`` (Nicolai Wojke) +#. Fix typos in ``users.rst`` (Sameer Agarwal) +#. Make some Jet comparisons exact. (Sameer Agarwal) +#. Add colmap to users.rst (Sameer Agarwal) +#. Fix step norm evaluation in LineSearchMinimizer (Sameer Agarwal) +#. Remove use of -Werror when compiling Ceres. (Alex Stewart) +#. Report Ceres compile options as components in find_package(). (Alex + Stewart) +#. Fix a spelling error in nnls_modeling.rst (Timer) +#. Only use collapse() directive with OpenMP 3.0 or higher. (Keir + Mierle) +#. Fix install path for CeresConfig.cmake to be architecture-aware. +#. Fix double conversion to degrees in rotation_test (Keir Mierle) +#. Make Jet string output more readable (Keir Mierle) +#. Fix rotation_test IsClose() and related tests (Keir Mierle) +#. Loosen an exact equality in local_parameterization_test (Sameer + Agarwal) +#. make_docs: Pass the file encoding to open() (Niels Ole Salscheider) +#. Fix error message returned when using SUITE_SPARSE_QR in covariance + estimation on a ceres built without SuiteSparse support. (Simon + Rutishauser) +#. Fix CXX11 option to be available on MinGW & CygWin, but not + MSVC. (Alex Stewart) +#. Fix missing early return() in xxx_not_found() dependency + macros. (Alex Stewart) +#. Initialize ``inner_iterations_were_useful_`` correctly. (Sameer + Agarwal) +#. Add an implementation for GradientProblemSolver::Options::IsValid + (Sameer Agarwal) +#. Fix use of va_copy() if compiling with explicit C++ version < + C++11. (Alex Stewart) +#. Install CMake files to lib/cmake/Ceres (Niels Ole Salscheider) +#. Allow users to override the documentation install directory. (Niels + Ole Salscheider) +#. Add covariance matrix for a vector of parameters (Wannes Van Loock) +#. Saner tolerances & stricter LRE test. (Sameer Agarwal) +#. Fix a malformed sentence in the tutorial. (Sameer Agarwal) +#. Add logging for sparse Cholesky factorization using Eigen. (Sameer + Agarwal) +#. Use std::adjacent_find instead of std::unique. (Sameer Agarwal) +#. Improve logging in CompressedRowJacobianWriter on crash. (Sameer + Agarwal) +#. Fix free parameter block handling in covariance computation (Wannes + Van Loock) +#. Report the number of line search steps in FullReport. (Sameer + Agarwal) +#. Make CMake read Ceres version directly from + include/ceres/version.h. (Alex Stewart) +#. Lots of code style/lint changes. (William Rucklidge) +#. Fix covariance computation for constant blocks (Wannes Van Loock) +#. Add IOS_DEPLOYMENT_TARGET variable to iOS.cmake (Eduard Feicho) +#. Make miniglog threadsafe on non-windows system by using + localtime_r() instead of localtime() for time formatting (Simon + Rutishauser) + +1.11.0 +====== + +New Features +------------ +#. Adaptive numeric differentiation using Ridders' method. (Tal + Ben-Nun) +#. Add ``CubicInterpolator`` and ``BiCubicInterpolator`` to allow + smooth interpolation of sampled functions and integration with + automatic differentiation. +#. Add method to return covariance in tangent space. (Michael Vitus & + Steve Hsu) +#. Add Homogeneous vector parameterization. (Michael Vitus) +#. Add a ``ProductParameterization``, a local parameterization that + can be constructed as a cartesian product of other local + parameterization. +#. Add DynamicCostFunctionToFunctor. (David Gossow) +#. Optionally export Ceres build directory into local CMake package + registry. +#. Faster ``SPARSE_NORMAL_CHOLESKY`` in the presence of dynamic + sparsity. + +Bug Fixes & Minor Changes +------------------------- +#. Remove use of link-time optimisation (LTO) for all compilers due to + portability issues with gtest / type_info::operator== & Eigen with + Clang on OS X vs GCC 4.9+ on Linux requiring contradictory 'fixes'. +#. Use link-time optimisation (LTO) only when compiling Ceres itself, + not tests or examples, to bypass gtest / type_info::operator== + issue. +#. Use old minimum iOS version flags on Xcode < 7.0. +#. Add gtest-specific flags when building/using as a shared library. +#. Clean up iOS.cmake to use xcrun/xcodebuild & libtool. +#. Import the latest version of ``googletest``. +#. Refactored ``system_test`` into ``bundle_adjustment_test`` and + ``system_test``, where each test case is its own test. +#. Fix invalid memory access bug in + ``CompressedRowSparseMatrix::AppendRows`` when it was called with a + matrix of size zero. +#. Build position independent code when compiling Ceres statically + (Alexander Alekhin). +#. Fix a bug in DetectStructure (Johannes Schonberger). +#. Reduce memory footprint of SubsetParameterization (Johannes + Schonberger). +#. Fix for reorder program unit test when built without suitesparse + (Sergey Sharybin). +#. Fix a bug in the Schur eliminator (Werner Trobin). +#. Fix a bug in the reordering code (Bernhard Zeisl). +#. Add missing CERES_EXPORT to ComposedLoss (Simon Rutishauser). +#. Add the option to use numeric differentiation to ``nist`` and + ``more_garbow_hillstrom``. +#. Fix EIGENSPARSE option help s/t it displays in CMake ncurses GUI. +#. Fix SparseNormalCholeskySolver with dynamic sparsity (Richie + Stebbing). +#. Remove legacy dependency detection macros. +#. Fix failed if() condition expansion if gflags is not found. +#. Update all CMake to lowercase function name style. +#. Update minimum iOS version to 7.0 for shared_ptr/unordered_map. +#. Fix bug in gflags' <= 2.1.2 exported CMake configuration. +#. Remove the spec file needed for generating RPMs. +#. Fix a typo in small_blas.h (Werber Trobin). +#. Cleanup FindGflags & use installed gflags CMake config if present. +#. Add default glog install location on Windows to search paths + (bvanevery). +#. Add default Eigen install location on Windows to search paths + (bvanevery). +#. Fix explanation of config.h generation in bare config.h. +#. Fix unused parameter compiler warnings in numeric_diff.h. +#. Increase tolerance for a test in polynomial_test (Taylor Braun + Jones). +#. Fix addition of Gerrit commit hook when Ceres is a git submodule + (Chris Cooper). +#. Fix missing EIGEN_VERSION expansion typo. +#. Fix links to SuiteSparse & CXSparse (Henrique Mendonça). +#. Ensure Eigen is at least 3.1.0 for Eigen/SparseCore. +#. Add option to use C++11 (not TR1) shared_ptr & unordered_map + (Norman Goldstein). +#. Fix an incorrect usage message in bundle_adjuster.cc +#. Gracefully disable docs if Sphinx is not found. +#. Explicitly use (new) default OS X rpath policy if present. +#. Add support of EIGEN_SPARSE type in + IsSparseLinearAlgebraLibraryTypeAvailable function (Pierre Moulon). +#. Allow the LossFunction contained in a LossFunctionWrapper to be + NULL. This is consistent with how NULL LossFunctions are treated + everywhere else. (Simon Rutishauser). +#. Improve numeric differentation near zero. +#. Refactored DynamicNumericDiffCostFunction to use NumericDiff (Tal + Ben-Nun). +#. Remove use of :caption tag in Sphinx. +#. Add a small test to make sure GradientProblemSolver works correctly + (Petter Strandmark). +#. Add simple unit tests for GradientProblem (Petter Strandmark). +#. Make the robust curve fitting example robust. +#. Homogenize convergence operators in docs and code (Johannes + Schonberger). +#. Add parameter_tolerance convergence to line search minimizer + (Johannes Schonberger). +#. Fix bug where pow(JetA,JetB) returned wrong result for JetA==0 + (Russell Smith). +#. Remove duplicate step norm computation (Johannes Schonberger). +#. Enhance usability when encountering Eigen version mismatches + (Andrew Hundt). +#. Add PLY file logger before and after BA in order to ease visual + comparison (Pierre Moulon). +#. Fix CMake config file docs to include 2.8.x & 3.x styles. +#. Python3 fixes (Markus Moll). +#. Remove confusing code from DenseJacobianWriter (Michael Vitus). +#. Add documentation on CMake package installation process. +#. Revert a call to SolveUpperTriangularUsingCholesky. +#. Make CERES_EIGEN_VERSION macro independent of CMake. +#. Add versions of dependencies used to FullReport(). +#. Ensure local config.h is used if Ceres is already installed. +#. Small messaging and comment updates in CMake +#. Handle possible presence of library prefixes in MSVC (Sylvain + Duchêne). +#. Use -O2 not -O3 on MinGW to workaround issue with Eigen + (s1m3mu3@gmail.com). +#. Increase tolerance in small_blas test for Cygwin + (s1m3mu3@gmail.com). +#. Fix iOS cmake file for cmake 3.0 (Jack Feng) +#. Fix missing gflags shlwapi dependency on MinGW (s1m3mu3@gmail.com). +#. Add thread dependency & fix namespace detection on Windows for + gflags (arrigo.benedetti@gmail.com). +#. Rename macros in the public API to have a ``CERES_`` prefix. +#. Fix ``OrderedGroup::Reverse()`` when it is empty (Chris Sweeney). +#. Update the code to point to ceres-solver.org. +#. Update documentation to point to the GitHub issue tracker. +#. Disable ``LAPACK`` for iOS builds. (Greg Coombe) +#. Force use of single-thread in ``Problem::Evaluate()`` without + OpenMP. +#. Less strict check for multithreading. (Chris Sweeney) +#. Update tolerances in small_blas_test.cc (Philipp Hubner) +#. Documentation corrections (Steve Hsu) +#. Fixed ``sampled_function.cc`` (Pablo Speciale) +#. Fix example code in the documentation. (Rodney Hoskinson) +#. Improve the error handling in Conjugate Gradients. +#. Improve preconditioner documentation. +#. Remove dead code from fpclassify.h. +#. Make Android.mk threads sensitive. +#. Changed the ``CURRENT_CONFIG_INSTALL_DIR`` to be a variable local + to Ceres. (Chris Sweeney) +#. Fix typo in the comments in ``Jet.h``. (Julius Ziegler) +#. Add the ASL at ETH Zurich, Theia & OpenPTrack to the list of users. +#. Fixed a typo in the documentation. (Richard Stebbing) +#. Fixed a boundary handling bug in the BiCubic interpolation + code. (Bernhard Zeisl) +#. Fixed a ``MSVC`` compilation bug in the cubic interpolation code + (Johannes Schönberger) +#. Add covariance related files to the Android build. +#. Update Ubuntu 14.04 installation instructions. (Filippo Basso) +#. Improved logging for linear solver failures. +#. Improved crash messages in ``Problem``. +#. Hide Homebrew related variables in CMake GUI. +#. Add SuiteSparse link dependency for + compressed_col_sparse_matrix_utils_test. +#. Autodetect Homebrew install prefix on OSX. +#. Lint changes from William Rucklidge and Jim Roseborough. +#. Remove ``using namespace std:`` from ``port.h`` +#. Add note about glog not currently compiling against gflags 2.1. +#. Add explicit no sparse linear algebra library available option. +#. Improve some wording in the FAQ. (Vasily Vylkov) +#. Delete Incomplete LQ Factorization. +#. Add a pointer to MacPorts. (Markus Moll) + + +1.10.0 +====== + +New Features +------------ +#. Ceres Solver can now be used to solve general unconstrained + optimization problems. See the documentation for + ``GradientProblem`` and ``GradientProblemSolver``. +#. ``Eigen`` can now be as a sparse linear algebra backend. This can + be done by setting + ``Solver::Options::sparse_linear_algebra_library_type`` to + ``EIGEN_SPARSE``. Performance should be comparable to + ``CX_SPARSE``. + + .. NOTE:: + + Because ``Eigen`` is a header only library, and some of the code + related to sparse Cholesky factorization is LGPL, building Ceres + with support for Eigen's sparse linear algebra is disabled by + default and should be enabled explicitly. + + .. NOTE:: + + For good performance, use Eigen version 3.2.2 or later. + +#. Added ``EIGEN_SPARSE_QR`` algorithm for covariance estimation using + ``Eigen``'s sparse QR factorization. (Michael Vitus) +#. Faster inner iterations when using multiple threads. +#. Faster ``ITERATIVE_SCHUR`` + ``SCHUR_JACOBI`` for small to medium + sized problems (see documentation for + ``Solver::Options::use_explicit_schur_complement``). +#. Faster automatic Schur ordering. +#. Reduced memory usage when solving problems with dynamic sparsity. +#. ``CostFunctionToFunctor`` now supports dynamic number of residuals. +#. A complete re-write of the problem preprocessing phase. +#. ``Solver::Summary::FullReport`` now reports the build configuration + for Ceres. +#. When building on Android, the ``NDK`` version detection logic has + been improved. +#. The ``CERES_VERSION`` macro has been improved and replaced with the + ``CERES_VERSION_STRING`` macro. +#. Added ``Solver::Options::IsValid`` which allows users to validate + their solver configuration before calling ``Solve``. +#. Added ``Problem::GetCostFunctionForResidualBlock`` and + ``Problem::GetLossFunctionForResidualBlock``. +#. Added Tukey's loss function. (Michael Vitus) +#. Added RotationMatrixToQuaternion +#. Compute & report timing information for line searches. +#. Autodetect gflags namespace. +#. Expanded ``more_garbow_hillstrom.cc``. +#. Added a pointer to Tal Ben-Nun's MSVC wrapper to the docs. +#. Added the ``<2,3,6>`` Schur template specialization. (Alessandro + Dal Grande) + +Backward Incompatible API Changes +--------------------------------- +#. ``NumericDiffFunctor`` has been removed. It's API was broken, and + the implementation was an unnecessary layer of abstraction over + ``CostFunctionToFunctor``. +#. ``POLAK_RIBIRERE`` conjugate gradients direction type has been + renamed to ``POLAK_RIBIERE``. +#. ``Solver::Options::solver_log`` has been removed. If needed this + iteration callback can easily be implemented in user code. +#. The ``SPARSE_CHOLESKY`` algorithm for covariance estimation has + been removed. It is not rank revealing and numerically poorly + behaved. Sparse QR factorization is a much better way to do this. +#. The ``SPARSE_QR`` algorithm for covariance estimation has been + renamed to ``SUITE_SPARSE_QR`` to be consistent with + ``EIGEN_SPARSE_QR``. +#. ``Solver::Summary::preconditioner_type`` has been replaced with + ``Solver::Summary::preconditioner_type_given`` and + ``Solver::Summary::preconditioner_type_used`` to be more consistent + with how information about the linear solver is communicated. +#. ``CERES_VERSION`` and ``CERES_ABI_VERSION`` macros were not + terribly useful. They have been replaced with + ``CERES_VERSION_MAJOR``, ``CERES_VERSION_MINOR`` , + ``CERES_VERSION_REVISION`` and ``CERES_VERSION_ABI`` macros. In + particular the functionality of ``CERES_VERSION`` is provided by + ``CERES_VERSION_STRING`` macro. + +Bug Fixes +--------- +#. Do not try the gradient step if TR step line search fails. +#. Fix missing include in libmv_bundle_adjuster on OSX. +#. Conditionally log evaluation failure warnings. +#. Runtime uses four digits after the decimal in Summary:FullReport. +#. Better options checking for TrustRegionMinimizer. +#. Fix RotationMatrixToAngleAxis when the angle of rotation is near + PI. (Tobias Strauss) +#. Sometimes gradient norm based convergence would miss a step with a + substantial solution quality improvement. (Rodney Hoskinson) +#. Ignore warnings from within Eigen/SparseQR (3.2.2). +#. Fix empty Cache HELPSTRING parsing error on OS X 10.10 Yosemite. +#. Fix a formatting error TrustRegionMinimizer logging. +#. Add an explicit include for local_parameterization.h (cooordz) +#. Fix a number of typos in the documentation (Martin Baeuml) +#. Made the logging in TrustRegionMinimizer consistent with + LineSearchMinimizer. +#. Fix some obsolete documentation in CostFunction::Evaluate. +#. Fix CG solver options for ITERATIVE_SCHUR, which did not copy + min_num_iterations (Johannes Schönberger) +#. Remove obsolete include of numeric_diff_functor.h. (Martin Baeuml) +#. Fix max. linear solver iterations in ConjugateGradientsSolver + (Johannes Schönberger) +#. Expand check for lack of a sparse linear algebra library. (Michael + Samples and Domink Reitzle) +#. Fix Eigen Row/ColMajor bug in NumericDiffCostFunction. (Dominik + Reitzle) +#. Fix crash in Covariance if # threads > 1 requested without OpenMP. +#. Fixed Malformed regex. (Björn Piltz) +#. Fixed MSVC error C2124: divide or mod by zero. (Björn Piltz) +#. Add missing #include of for loss functions. +#. Make canned loss functions more robust. +#. Fix type of suppressed compiler warning for Eigen 3.2.0. +#. Suppress unused variable warning from Eigen 3.2.0. +#. Add "make install" to the install instructions. +#. Correct formula in documentation of + Solver::Options::function_tolerance. (Alessandro Gentilini) +#. Add release flags to iOS toolchain. +#. Fix a broken hyperlink in the documentation. (Henrique Mendonca) +#. Add fixes for multiple definitions of ERROR on Windows to docs. +#. Compile miniglog into Ceres if enabled on all platforms. +#. Add two missing files to Android.mk (Greg Coombe) +#. Fix Cmake error when using miniglog. (Greg Coombe) +#. Don't build miniglog unconditionally as a static library (Björn + Piltz) +#. Added a missing include. (Björn Piltz) +#. Conditionally disable SparseNormalCholesky. +#. Fix a memory leak in program_test.cc. + + +1.9.0 +===== + +New Features +------------ +#. Bounds constraints: Support for upper and/or lower bounds on + parameters when using the trust region minimizer. +#. Dynamic Sparsity: Problems in which the sparsity structure of the + Jacobian changes over the course of the optimization can now be + solved much more efficiently. (Richard Stebbing) +#. Improved support for Microsoft Visual C++ including the ability to + build and ship DLLs. (Björn Piltz, Alex Stewart and Sergey + Sharybin) +#. Support for building on iOS 6.0 or higher (Jack Feng). +#. Autogeneration of config.h that captures all the defines used to + build and use Ceres Solver. +#. Simpler and more informative solver termination type + reporting. (See below for more details) +#. New `website `_ based entirely on + Sphinx. +#. ``AutoDiffLocalParameterization`` allows the use of automatic + differentiation for defining ``LocalParameterization`` objects + (Alex Stewart) +#. LBFGS is faster due to fewer memory copies. +#. Parameter blocks are not restricted to be less than 32k in size, + they can be up to 2G in size. +#. Faster ``SPARSE_NORMAL_CHOLESKY`` solver when using ``CX_SPARSE`` + as the sparse linear algebra library. +#. Added ``Problem::IsParameterBlockPresent`` and + ``Problem::GetParameterization``. +#. Added the (2,4,9) and (2,4,8) template specializations. +#. An example demonstrating the use of + DynamicAutoDiffCostFunction. (Joydeep Biswas) +#. Homography estimation example from Blender demonstrating the use of + a custom ``IterationCallback``. (Sergey Sharybin) +#. Support user passing a custom CMAKE_MODULE_PATH (for BLAS / + LAPACK). + +Backward Incompatible API Changes +--------------------------------- +#. ``Solver::Options::linear_solver_ordering`` used to be a naked + pointer that Ceres took ownership of. This is error prone behaviour + which leads to problems when copying the ``Solver::Options`` struct + around. This has been replaced with a ``shared_ptr`` to handle + ownership correctly across copies. + +#. The enum used for reporting the termination/convergence status of + the solver has been renamed from ``SolverTerminationType`` to + ``TerminationType``. + + The enum values have also changed. ``FUNCTION_TOLERANCE``, + ``GRADIENT_TOLERANCE`` and ``PARAMETER_TOLERANCE`` have all been + replaced by ``CONVERGENCE``. + + ``NUMERICAL_FAILURE`` has been replaed by ``FAILURE``. + + ``USER_ABORT`` has been renamed to ``USER_FAILURE``. + + Further ``Solver::Summary::error`` has been renamed to + ``Solver::Summary::message``. It contains a more detailed + explanation for why the solver terminated. + +#. ``Solver::Options::gradient_tolerance`` used to be a relative + gradient tolerance. i.e., The solver converged when + + .. math:: \|g(x)\|_\infty < \text{gradient_tolerance} * + \|g(x_0)\|_\infty + + where :math:`g(x)` is the gradient of the objective function at + :math:`x` and :math:`x_0` is the parmeter vector at the start of + the optimization. + + This has changed to an absolute tolerance, i.e. the solver + converges when + + .. math:: \|g(x)\|_\infty < \text{gradient_tolerance} + +#. Ceres cannot be built without the line search minimizer + anymore. Thus the preprocessor define + ``CERES_NO_LINE_SEARCH_MINIMIZER`` has been removed. + +Bug Fixes +--------- +#. Disabled warning C4251. (Björn Piltz) +#. Do not propagate 3d party libs through + `IMPORTED_LINK_INTERFACE_LIBRARIES_[DEBUG/RELEASE]` mechanism when + building shared libraries. (Björn Piltz) +#. Fixed errant verbose levels (Björn Piltz) +#. Variety of code cleanups, optimizations and bug fixes to the line + search minimizer code (Alex Stewart) +#. Fixed ``BlockSparseMatrix::Transpose`` when the matrix has row and + column blocks. (Richard Bowen) +#. Better error checking when ``Problem::RemoveResidualBlock`` is + called. (Alex Stewart) +#. Fixed a memory leak in ``SchurComplementSolver``. +#. Added ``epsilon()`` method to ``NumTraits + >``. (Filippo Basso) +#. Fixed a bug in `CompressedRowSparseMatrix::AppendRows`` and + ``DeleteRows``.q +#. Handle empty problems consistently. +#. Restore the state of the ``Problem`` after a call to + ``Problem::Evaluate``. (Stefan Leutenegger) +#. Better error checking and reporting for linear solvers. +#. Use explicit formula to solve quadratic polynomials instead of the + eigenvalue solver. +#. Fix constant parameter handling in inner iterations (Mikael + Persson). +#. SuiteSparse errors do not cause a fatal crash anymore. +#. Fix ``corrector_test.cc``. +#. Relax the requirements on loss function derivatives. +#. Minor bugfix to logging.h (Scott Ettinger) +#. Updated ``gmock`` and ``gtest`` to the latest upstream version. +#. Fix build breakage on old versions of SuiteSparse. +#. Fixed build issues related to Clang / LLVM 3.4 (Johannes + Schönberger) +#. METIS_FOUND is never set. Changed the commit to fit the setting of + the other #._FOUND definitions. (Andreas Franek) +#. Variety of bug fixes and cleanups to the ``CMake`` build system + (Alex Stewart) +#. Removed fictious shared library target from the NDK build. +#. Solver::Options now uses ``shared_ptr`` to handle ownership of + ``Solver::Options::linear_solver_ordering`` and + ``Solver::Options::inner_iteration_ordering``. As a consequence the + ``NDK`` build now depends on ``libc++`` from the ``LLVM`` project. +#. Variety of lint cleanups (William Rucklidge & Jim Roseborough) +#. Various internal cleanups including dead code removal. + + +1.8.0 +===== + +New Features +------------ +#. Significant improved ``CMake`` files with better robustness, + dependency checking and GUI support. (Alex Stewart) +#. Added ``DynamicNumericDiffCostFunction`` for numerically + differentiated cost functions whose sizing is determined at run + time. +#. ``NumericDiffCostFunction`` now supports a dynamic number of + residuals just like ``AutoDiffCostFunction``. +#. ``Problem`` exposes more of its structure in its API. +#. Faster automatic differentiation (Tim Langlois) +#. Added the commonly occuring ``2_d_d`` template specialization for + the Schur Eliminator. +#. Faster ``ITERATIVE_SCHUR`` solver using template specializations. +#. Faster ``SCHUR_JACOBI`` preconditioner construction. +#. Faster ``AngleAxisRotatePoint``. +#. Faster Jacobian evaluation when a loss function is used. +#. Added support for multiple clustering algorithms in visibility + based preconditioning, including a new fast single linkage + clustering algorithm. + +Bug Fixes +--------- +#. Fix ordering of ParseCommandLineFlags() & InitGoogleTest() for + Windows. (Alex Stewart) +#. Remove DCHECK_GE checks from fixed_array.h. +#. Fix build on MSVC 2013 (Petter Strandmark) +#. Fixed ``AngleAxisToRotationMatrix`` near zero. +#. Move ``CERES_HASH_NAMESPACE`` macros to ``collections_port.h``. +#. Fix handling of unordered_map/unordered_set on OSX 10.9.0. +#. Explicitly link to libm for ``curve_fitting_c.c``. (Alex Stewart) +#. Minor type conversion fix to autodiff.h +#. Remove RuntimeNumericDiffCostFunction. +#. Fix operator= ambiguity on some versions of Clang. (Alex Stewart) +#. Various Lint cleanups (William Rucklidge & Jim Roseborough) +#. Modified installation folders for Windows. (Pablo Speciale) +#. Added librt to link libraries for SuiteSparse_config on + Linux. (Alex Stewart) +#. Check for presence of return-type-c-linkage option with + Clang. (Alex Stewart) +#. Fix Problem::RemoveParameterBlock after calling solve. (Simon + Lynen) +#. Fix a free/delete bug in covariance_impl.cc +#. Fix two build errors. (Dustin Lang) +#. Add RequireInitialization = 1 to NumTraits::Jet. +#. Update gmock/gtest to 1.7.0 +#. Added IterationSummary::gradient_norm. +#. Reduced verbosity of the inner iteration minimizer. +#. Fixed a bug in TrustRegionMinimizer. (Michael Vitus) +#. Removed android/build_android.sh. + + +1.7.0 +===== + +Backward Incompatible API Changes +--------------------------------- + +#. ``Solver::Options::sparse_linear_algebra_library`` has been renamed + to ``Solver::Options::sparse_linear_algebra_library_type``. + +New Features +------------ +#. Sparse and dense covariance estimation. +#. A new Wolfe line search. (Alex Stewart) +#. ``BFGS`` line search direction. (Alex Stewart) +#. C API +#. Speeded up the use of loss functions > 17x. +#. Faster ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR`` + solvers. +#. Support for multiple dense linear algebra backends. In particular + optimized ``BLAS`` and ``LAPACK`` implementations (e.g., Intel MKL, + ACML, OpenBLAS etc) can now be used to do the dense linear algebra + for ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR`` +#. Use of Inner iterations can now be adaptively stopped. Iteration + and runtime statistics for inner iterations are not reported in + ``Solver::Summary`` and ``Solver::Summary::FullReport``. +#. Improved inner iteration step acceptance criterion. +#. Add BlockRandomAccessCRSMatrix. +#. Speeded up automatic differentiation by 7\%. +#. Bundle adjustment example from libmv/Blender (Sergey Sharybin) +#. Shared library building is now controlled by CMake, rather than a + custom solution. Previously, Ceres had a custom option, but this is + now deprecated in favor of CMake's built in support for switching + between static and shared. Turn on BUILD_SHARED_LIBS to get shared + Ceres libraries. +#. No more dependence on Protocol Buffers. +#. Incomplete LQ factorization. +#. Ability to write trust region problems to disk. +#. Add sinh, cosh, tanh and tan functions to automatic differentiation + (Johannes Schönberger) +#. Simplifications to the cmake build file. +#. ``miniglog`` can now be used as a replacement for ``google-glog`` + on non Android platforms. (This is NOT recommended). + +Bug Fixes +--------- +#. Fix ``ITERATIVE_SCHUR`` solver to work correctly when the schur + complement is of size zero. (Soohyun Bae) +#. Fix the ``spec`` file for generating ``RPM`` packages (Brian Pitts + and Taylor Braun-Jones). +#. Fix how ceres calls CAMD (Manas Jagadev) +#. Fix breakage on old versions of SuiteSparse. (Fisher Yu) +#. Fix warning C4373 in Visual Studio (Petter Strandmark) +#. Fix compilation error caused by missing suitesparse headers and + reorganize them to be more robust. (Sergey Sharybin) +#. Check GCC Version before adding -fast compiler option on + OSX. (Steven Lovegrove) +#. Add documentation for minimizer progress output. +#. Lint and other cleanups (William Rucklidge and James Roseborough) +#. Collections port fix for MSC 2008 (Sergey Sharybin) +#. Various corrections and cleanups in the documentation. +#. Change the path where CeresConfig.cmake is installed (Pablo + Speciale) +#. Minor errors in documentation (Pablo Speciale) +#. Updated depend.cmake to follow CMake IF convention. (Joydeep + Biswas) +#. Stablize the schur ordering algorithm. +#. Update license header in split.h. +#. Enabling -O4 (link-time optimization) only if compiler/linker + support it. (Alex Stewart) +#. Consistent glog path across files. +#. ceres-solver.spec: Use cleaner, more conventional Release string + (Taylor Braun-Jones) +#. Fix compile bug on RHEL6 due to missing header (Taylor Braun-Jones) +#. CMake file is less verbose. +#. Use the latest upstream version of google-test and gmock. +#. Rationalize some of the variable names in ``Solver::Options``. +#. Improve Summary::FullReport when line search is used. +#. Expose line search parameters in ``Solver::Options``. +#. Fix update of L-BFGS history buffers after they become full. (Alex + Stewart) +#. Fix configuration error on systems without SuiteSparse installed + (Sergey Sharybin) +#. Enforce the read call returns correct value in + ``curve_fitting_c.c`` (Arnaud Gelas) +#. Fix DynamicAutoDiffCostFunction (Richard Stebbing) +#. Fix Problem::RemoveParameterBlock documentation (Johannes + Schönberger) +#. Fix a logging bug in parameter_block.h +#. Refactor the preconditioner class structure. +#. Fix an uninitialized variable warning when building with ``GCC``. +#. Fix a reallocation bug in + ``CreateJacobianBlockSparsityTranspose``. (Yuliy Schwartzburg) +#. Add a define for O_BINARY. +#. Fix miniglog-based Android NDK build; now works with NDK r9. (Scott + Ettinger) + + +1.6.0 +===== + +New Features +------------ +#. Major Performance improvements. + + a. Schur type solvers (``SPARSE_SCHUR``, ``DENSE_SCHUR``, + ``ITERATIVE_SCHUR``) are significantly faster due to custom BLAS + routines and fewer heap allocations. + + b. ``SPARSE_SCHUR`` when used with ``CX_SPARSE`` now uses a block + AMD for much improved factorization performance. + + c. The jacobian matrix is pre-ordered so that + ``SPARSE_NORMAL_CHOLESKY`` and ``SPARSE_SCHUR`` do not have to + make copies inside ``CHOLMOD``. + + d. Faster autodiff by replacing division by multplication by inverse. + + e. When compiled without threads, the schur eliminator does not pay + the penalty for locking and unlocking mutexes. + +#. Users can now use ``linear_solver_ordering`` to affect the + fill-reducing ordering used by ``SUITE_SPARSE`` for + ``SPARSE_NORMAL_CHOLESKY``. +#. ``Problem`` can now report the set of parameter blocks it knows about. +#. ``TrustRegionMinimizer`` uses the evaluator to compute the gradient + instead of a matrix vector multiply. +#. On ``Mac OS``, whole program optimization is enabled. +#. Users can now use automatic differentiation to define new + ``LocalParameterization`` objects. (Sergey Sharybin) +#. Enable larger tuple sizes for Visual Studio 2012. (Petter Strandmark) + + +Bug Fixes +--------- + +#. Update the documentation for ``CostFunction``. +#. Fixed a typo in the documentation. (Pablo Speciale) +#. Fix a typo in suitesparse.cc. +#. Bugfix in ``NumericDiffCostFunction``. (Nicolas Brodu) +#. Death to BlockSparseMatrixBase. +#. Change Minimizer::Options::min_trust_region_radius to double. +#. Update to compile with stricter gcc checks. (Joydeep Biswas) +#. Do not modify cached CMAKE_CXX_FLAGS_RELEASE. (Sergey Sharybin) +#. ```` needed for back_insert_iterator. (Petter Strandmark) +#. Lint cleanup. (William Rucklidge) +#. Documentation corrections. (Pablo Speciale) + + +1.5.0 +===== + +Backward Incompatible API Changes +--------------------------------- +#. Added ``Problem::Evaluate``. Now you can evaluate a problem or any + part of it without calling the solver. + + In light of this the following settings have been deprecated and + removed from the API. + + - ``Solver::Options::return_initial_residuals`` + - ``Solver::Options::return_initial_gradient`` + - ``Solver::Options::return_initial_jacobian`` + - ``Solver::Options::return_final_residuals`` + - ``Solver::Options::return_final_gradient`` + - ``Solver::Options::return_final_jacobian`` + + Instead we recommend using something like this. + + .. code-block:: c++ + + Problem problem; + // Build problem + + vector initial_residuals; + problem.Evaluate(Problem::EvaluateOptions(), + NULL, /* No cost */ + &initial_residuals, + NULL, /* No gradient */ + NULL /* No jacobian */ ); + + Solver::Options options; + Solver::Summary summary; + Solver::Solve(options, &problem, &summary); + + vector final_residuals; + problem.Evaluate(Problem::EvaluateOptions(), + NULL, /* No cost */ + &final_residuals, + NULL, /* No gradient */ + NULL /* No jacobian */ ); + + +New Features +------------ +#. Problem now supports removal of ParameterBlocks and + ResidualBlocks. There is a space/time tradeoff in doing this which + is controlled by + ``Problem::Options::enable_fast_parameter_block_removal``. + +#. Ceres now supports Line search based optimization algorithms in + addition to trust region algorithms. Currently there is support for + gradient descent, non-linear conjugate gradient and LBFGS search + directions. +#. Added ``Problem::Evaluate``. Now you can evaluate a problem or any + part of it without calling the solver. In light of this the + following settings have been deprecated and removed from the API. + + - ``Solver::Options::return_initial_residuals`` + - ``Solver::Options::return_initial_gradient`` + - ``Solver::Options::return_initial_jacobian`` + - ``Solver::Options::return_final_residuals`` + - ``Solver::Options::return_final_gradient`` + - ``Solver::Options::return_final_jacobian`` + +#. New, much improved HTML documentation using Sphinx. +#. Changed ``NumericDiffCostFunction`` to take functors like + ``AutoDiffCostFunction``. +#. Added support for mixing automatic, analytic and numeric + differentiation. This is done by adding ``CostFunctionToFunctor`` + and ``NumericDiffFunctor`` objects to the API. +#. Sped up the robust loss function correction logic when residual is + one dimensional. +#. Sped up ``DenseQRSolver`` by changing the way dense jacobians are + stored. This is a 200-500% improvement in linear solver performance + depending on the size of the problem. +#. ``DENSE_SCHUR`` now supports multi-threading. +#. Greatly expanded ``Summary::FullReport``: + + - Report the ordering used by the ``LinearSolver``. + - Report the ordering used by the inner iterations. + - Execution timing breakdown into evaluations and linear solves. + - Effective size of the problem solved by the solver, which now + accounts for the size of the tangent space when using a + ``LocalParameterization``. +#. Ceres when run at the ``VLOG`` level 3 or higher will report + detailed timing information about its internals. +#. Remove extraneous initial and final residual evaluations. This + speeds up the solver a bit. +#. Automatic differenatiation with a dynamic number of parameter + blocks. (Based on an idea by Thad Hughes). +#. Sped up problem construction and destruction. +#. Added matrix adapters to ``rotation.h`` so that the rotation matrix + routines can work with row and column major matrices. (Markus Moll) +#. ``SCHUR_JACOBI`` can now be used without ``SuiteSparse``. +#. A ``.spec`` file for producing RPMs. (Taylor Braun-Jones) +#. ``CMake`` can now build the sphinx documentation (Pablo Speciale) +#. Add support for creating a CMake config file during build to make + embedding Ceres in other CMake-using projects easier. (Pablo + Speciale). +#. Better error reporting in ``Problem`` for missing parameter blocks. +#. A more flexible ``Android.mk`` and a more modular build. If binary + size and/or compile time is a concern, larger parts of the solver + can be disabled at compile time. + +Bug Fixes +--------- +#. Compilation fixes for MSVC2010 (Sergey Sharybin) +#. Fixed "deprecated conversion from string constant to char*" + warnings. (Pablo Speciale) +#. Correctly propagate ifdefs when building without Schur eliminator + template specializations. +#. Correct handling of ``LIB_SUFFIX`` on Linux. (Yuliy Schwartzburg). +#. Code and signature cleanup in ``rotation.h``. +#. Make examples independent of internal code. +#. Disable unused member in ``gtest`` which results in build error on + OS X with latest Xcode. (Taylor Braun-Jones) +#. Pass the correct flags to the linker when using + ``pthreads``. (Taylor Braun-Jones) +#. Only use ``cmake28`` macro when building on RHEL6. (Taylor + Braun-Jones) +#. Remove ``-Wno-return-type-c-linkage`` when compiling with + GCC. (Taylor Braun-Jones) +#. Fix ``No previous prototype`` warnings. (Sergey Sharybin) +#. MinGW build fixes. (Sergey Sharybin) +#. Lots of minor code and lint fixes. (William Rucklidge) +#. Fixed a bug in ``solver_impl.cc`` residual evaluation. (Markus + Moll) +#. Fixed varidic evaluation bug in ``AutoDiff``. +#. Fixed ``SolverImpl`` tests. +#. Fixed a bug in ``DenseSparseMatrix::ToDenseMatrix()``. +#. Fixed an initialization bug in ``ProgramEvaluator``. +#. Fixes to Android.mk paths (Carlos Hernandez) +#. Modify ``nist.cc`` to compute accuracy based on ground truth + solution rather than the ground truth function value. +#. Fixed a memory leak in ``cxsparse.cc``. (Alexander Mordvintsev). +#. Fixed the install directory for libraries by correctly handling + ``LIB_SUFFIX``. (Taylor Braun-Jones) + +1.4.0 +===== + +Backward Incompatible API Changes +--------------------------------- +The new ordering API breaks existing code. Here the common case fixes. + +**Before** + +.. code-block:: c++ + + options.linear_solver_type = ceres::DENSE_SCHUR + options.ordering_type = ceres::SCHUR + +**After** + + +.. code-block:: c++ + + options.linear_solver_type = ceres::DENSE_SCHUR + + +**Before** + +.. code-block:: c++ + + options.linear_solver_type = ceres::DENSE_SCHUR; + options.ordering_type = ceres::USER; + for (int i = 0; i < num_points; ++i) { + options.ordering.push_back(my_points[i]) + } + for (int i = 0; i < num_cameras; ++i) { + options.ordering.push_back(my_cameras[i]) + } + options.num_eliminate_blocks = num_points; + + +**After** + +.. code-block:: c++ + + options.linear_solver_type = ceres::DENSE_SCHUR; + options.ordering = new ceres::ParameterBlockOrdering; + for (int i = 0; i < num_points; ++i) { + options.linear_solver_ordering->AddElementToGroup(my_points[i], 0); + } + for (int i = 0; i < num_cameras; ++i) { + options.linear_solver_ordering->AddElementToGroup(my_cameras[i], 1); + } + + +New Features +------------ +#. A new richer, more expressive and consistent API for ordering + parameter blocks. +#. A non-linear generalization of Ruhe & Wedin's Algorithm II. This + allows the user to use variable projection on separable and + non-separable non-linear least squares problems. With + multithreading, this results in significant improvements to the + convergence behavior of the solver at a small increase in run time. +#. An image denoising example using fields of experts. (Petter + Strandmark) +#. Defines for Ceres version and ABI version. +#. Higher precision timer code where available. (Petter Strandmark) +#. Example Makefile for users of Ceres. +#. IterationSummary now informs the user when the step is a + non-monotonic step. +#. Fewer memory allocations when using ``DenseQRSolver``. +#. GradientChecker for testing CostFunctions (William Rucklidge) +#. Add support for cost functions with 10 parameter blocks in + ``Problem``. (Fisher) +#. Add support for 10 parameter blocks in ``AutoDiffCostFunction``. + + +Bug Fixes +--------- + +#. static cast to force Eigen::Index to long conversion +#. Change LOG(ERROR) to LOG(WARNING) in ``schur_complement_solver.cc``. +#. Remove verbose logging from ``DenseQRSolve``. +#. Fix the Android NDK build. +#. Better handling of empty and constant Problems. +#. Remove an internal header that was leaking into the public API. +#. Memory leak in ``trust_region_minimizer.cc`` +#. Schur ordering was operating on the wrong object (Ricardo Martin) +#. MSVC fixes (Petter Strandmark) +#. Various fixes to ``nist.cc`` (Markus Moll) +#. Fixed a jacobian scaling bug. +#. Numerically robust computation of ``model_cost_change``. +#. Signed comparison compiler warning fixes (Ricardo Martin) +#. Various compiler warning fixes all over. +#. Inclusion guard fixes (Petter Strandmark) +#. Segfault in test code (Sergey Popov) +#. Replaced ``EXPECT/ASSERT_DEATH`` with the more portable + ``EXPECT_DEATH_IF_SUPPORTED`` macros. +#. Fixed the camera projection model in Ceres' implementation of + Snavely's camera model. (Ricardo Martin) + + +1.3.0 +===== + +New Features +------------ +#. Android Port (Scott Ettinger also contributed to the port) +#. Windows port. (Changchang Wu and Pierre Moulon also contributed to the port) +#. New subspace Dogleg Solver. (Markus Moll) +#. Trust region algorithm now supports the option of non-monotonic steps. +#. New loss functions ``ArcTanLossFunction``, ``TolerantLossFunction`` + and ``ComposedLossFunction``. (James Roseborough). +#. New ``DENSE_NORMAL_CHOLESKY`` linear solver, which uses Eigen's + LDLT factorization on the normal equations. +#. Cached symbolic factorization when using ``CXSparse``. + (Petter Strandark) +#. New example ``nist.cc`` and data from the NIST non-linear + regression test suite. (Thanks to Douglas Bates for suggesting this.) +#. The traditional Dogleg solver now uses an elliptical trust + region (Markus Moll) +#. Support for returning initial and final gradients & Jacobians. +#. Gradient computation support in the evaluators, with an eye + towards developing first order/gradient based solvers. +#. A better way to compute ``Solver::Summary::fixed_cost``. (Markus Moll) +#. ``CMake`` support for building documentation, separate examples, + installing and uninstalling the library and Gerrit hooks (Arnaud + Gelas) +#. ``SuiteSparse4`` support (Markus Moll) +#. Support for building Ceres without ``TR1`` (This leads to + slightly slower ``DENSE_SCHUR`` and ``SPARSE_SCHUR`` solvers). +#. ``BALProblem`` can now write a problem back to disk. +#. ``bundle_adjuster`` now allows the user to normalize and perturb the + problem before solving. +#. Solver progress logging to file. +#. Added ``Program::ToString`` and ``ParameterBlock::ToString`` to + help with debugging. +#. Ability to build Ceres as a shared library (MacOS and Linux only), + associated versioning and build release script changes. +#. Portable floating point classification API. + + +Bug Fixes +--------- +#. Fix how invalid step evaluations are handled. +#. Change the slop handling around zero for model cost changes to use + relative tolerances rather than absolute tolerances. +#. Fix an inadvertant integer to bool conversion. (Petter Strandmark) +#. Do not link to ``libgomp`` when building on + windows. (Petter Strandmark) +#. Include ``gflags.h`` in ``test_utils.cc``. (Petter + Strandmark) +#. Use standard random number generation routines. (Petter Strandmark) +#. ``TrustRegionMinimizer`` does not implicitly negate the + steps that it takes. (Markus Moll) +#. Diagonal scaling allows for equal upper and lower bounds. (Markus Moll) +#. TrustRegionStrategy does not misuse LinearSolver:Summary anymore. +#. Fix Eigen3 Row/Column Major storage issue. (Lena Gieseke) +#. QuaternionToAngleAxis now guarantees an angle in $[-\pi, \pi]$. (Guoxuan Zhang) +#. Added a workaround for a compiler bug in the Android NDK to the + Schur eliminator. +#. The sparse linear algebra library is only logged in + Summary::FullReport if it is used. +#. Rename the macro ``CERES_DONT_HAVE_PROTOCOL_BUFFERS`` + to ``CERES_NO_PROTOCOL_BUFFERS`` for consistency. +#. Fix how static structure detection for the Schur eliminator logs + its results. +#. Correct example code in the documentation. (Petter Strandmark) +#. Fix ``fpclassify.h`` to work with the Android NDK and STLport. +#. Fix a memory leak in the ``levenber_marquardt_strategy_test.cc`` +#. Fix an early return bug in the Dogleg solver. (Markus Moll) +#. Zero initialize Jets. +#. Moved ``internal/ceres/mock_log.h`` to ``internal/ceres/gmock/mock-log.h`` +#. Unified file path handling in tests. +#. ``data_fitting.cc`` includes ``gflags`` +#. Renamed Ceres' Mutex class and associated macros to avoid + namespace conflicts. +#. Close the BAL problem file after reading it (Markus Moll) +#. Fix IsInfinite on Jets. +#. Drop alignment requirements for Jets. +#. Fixed Jet to integer comparison. (Keith Leung) +#. Fix use of uninitialized arrays. (Sebastian Koch & Markus Moll) +#. Conditionally compile gflag dependencies.(Casey Goodlett) +#. Add ``data_fitting.cc`` to the examples ``CMake`` file. + + +1.2.3 +===== + +Bug Fixes +--------- +#. ``suitesparse_test`` is enabled even when ``-DSUITESPARSE=OFF``. +#. ``FixedArray`` internal struct did not respect ``Eigen`` + alignment requirements (Koichi Akabe & Stephan Kassemeyer). +#. Fixed ``quadratic.cc`` documentation and code mismatch + (Nick Lewycky). + +1.2.2 +===== + +Bug Fixes +--------- +#. Fix constant parameter blocks, and other minor fixes (Markus Moll) +#. Fix alignment issues when combining ``Jet`` and + ``FixedArray`` in automatic differeniation. +#. Remove obsolete ``build_defs`` file. + +1.2.1 +===== + +New Features +------------ +#. Powell's Dogleg solver +#. Documentation now has a brief overview of Trust Region methods and + how the Levenberg-Marquardt and Dogleg methods work. + +Bug Fixes +--------- +#. Destructor for ``TrustRegionStrategy`` was not virtual (Markus + Moll) +#. Invalid ``DCHECK`` in ``suitesparse.cc`` (Markus Moll) +#. Iteration callbacks were not properly invoked (Luis Alberto + Zarrabeiti) +#. Logging level changes in ConjugateGradientsSolver +#. VisibilityBasedPreconditioner setup does not account for skipped + camera pairs. This was debugging code. +#. Enable SSE support on MacOS +#. ``system_test`` was taking too long and too much memory (Koichi + Akabe) + +1.2.0 +===== + +New Features +------------ + +#. ``CXSparse`` support. +#. Block oriented fill reducing orderings. This reduces the + factorization time for sparse ``CHOLMOD`` significantly. +#. New Trust region loop with support for multiple trust region step + strategies. Currently only Levenberg-Marquardt is supported, but + this refactoring opens the door for Dog-leg, Stiehaug and others. +#. ``CMake`` file restructuring. Builds in ``Release`` mode by default, and now has platform specific tuning flags. +#. Re-organized documentation. No new content, but better + organization. + + +Bug Fixes +--------- + +#. Fixed integer overflow bug in ``block_random_access_sparse_matrix.cc``. +#. Renamed some macros to prevent name conflicts. +#. Fixed incorrent input to ``StateUpdatingCallback``. +#. Fixes to AutoDiff tests. +#. Various internal cleanups. + + +1.1.1 +===== + +Bug Fixes +--------- +#. Fix a bug in the handling of constant blocks. (Louis Simard) +#. Add an optional lower bound to the Levenberg-Marquardt regularizer + to prevent oscillating between well and ill posed linear problems. +#. Some internal refactoring and test fixes. + +1.1.0 +===== + +New Features +------------ +#. New iterative linear solver for general sparse problems - ``CGNR`` + and a block Jacobi preconditioner for it. +#. Changed the semantics of how ``SuiteSparse`` dependencies are + checked and used. Now ``SuiteSparse`` is built by default, only if + all of its dependencies are present. +#. Automatic differentiation now supports dynamic number of residuals. +#. Support for writing the linear least squares problems to disk in + text format so that they can loaded into ``MATLAB``. +#. Linear solver results are now checked for nan and infinities. +#. Added ``.gitignore`` file. +#. A better more robust build system. + + +Bug Fixes +--------- +#. Fixed a strict weak ordering bug in the schur ordering. +#. Grammar and typos in the documents and code comments. +#. Fixed tests which depended on exact equality between floating point + values. + +1.0.0 +===== +Initial open source release. Nathan Wiegand contributed to the Mac OSX +port. + + +Origins +======= + +Ceres Solver grew out of the need for general least squares solving at +Google. In early 2010, Sameer Agarwal and Fredrik Schaffalitzky +started the development of Ceres Solver. Fredrik left Google shortly +thereafter and Keir Mierle stepped in to take his place. After two +years of on-and-off development, Ceres Solver was released as open +source in May of 2012. diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt new file mode 100644 index 0000000..eef5e5e --- /dev/null +++ b/examples/CMakeLists.txt @@ -0,0 +1,113 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: keir@google.com (Keir Mierle) + +# Only Ceres itself should be compiled with CERES_BUILDING_SHARED_LIBRARY +# defined, any users of Ceres will have CERES_USING_SHARED_LIBRARY defined +# for them in Ceres' config.h if appropriate. +if (BUILD_SHARED_LIBS) + remove_definitions(-DCERES_BUILDING_SHARED_LIBRARY) +endif() + +add_executable(helloworld helloworld.cc) +target_link_libraries(helloworld ceres) + +add_executable(helloworld_numeric_diff helloworld_numeric_diff.cc) +target_link_libraries(helloworld_numeric_diff ceres) + +add_executable(helloworld_analytic_diff helloworld_analytic_diff.cc) +target_link_libraries(helloworld_analytic_diff ceres) + +add_executable(curve_fitting curve_fitting.cc) +target_link_libraries(curve_fitting ceres) + +add_executable(rosenbrock rosenbrock.cc) +target_link_libraries(rosenbrock ceres) + +add_executable(curve_fitting_c curve_fitting.c) +target_link_libraries(curve_fitting_c ceres) +# Force CMake to link curve_fitting_c using the C linker, this is important +# when Ceres was compiled using C++11 to ensure that -std=c++11 is not passed +# through. +set_target_properties(curve_fitting_c PROPERTIES LINKER_LANGUAGE C) +# As this is a C file #including we have to explicitly add the math +# library (libm). Although some compilers (dependent upon options) will accept +# the indirect link to libm via Ceres, at least GCC 4.8 on pure Debian won't. +if (NOT MSVC) + target_link_libraries(curve_fitting_c m) +endif (NOT MSVC) + +add_executable(ellipse_approximation ellipse_approximation.cc) +target_link_libraries(ellipse_approximation ceres) + +add_executable(robust_curve_fitting robust_curve_fitting.cc) +target_link_libraries(robust_curve_fitting ceres) + +add_executable(simple_bundle_adjuster simple_bundle_adjuster.cc) +target_link_libraries(simple_bundle_adjuster ceres) + +if (GFLAGS) + add_executable(powell powell.cc) + target_link_libraries(powell ceres ${GFLAGS_LIBRARIES}) + + add_executable(nist nist.cc) + target_link_libraries(nist ceres ${GFLAGS_LIBRARIES}) + + add_executable(more_garbow_hillstrom more_garbow_hillstrom.cc) + target_link_libraries(more_garbow_hillstrom ceres ${GFLAGS_LIBRARIES}) + + add_executable(circle_fit circle_fit.cc) + target_link_libraries(circle_fit ceres ${GFLAGS_LIBRARIES}) + + add_executable(bundle_adjuster + bundle_adjuster.cc + bal_problem.cc) + target_link_libraries(bundle_adjuster ceres ${GFLAGS_LIBRARIES}) + + add_executable(libmv_bundle_adjuster + libmv_bundle_adjuster.cc) + target_link_libraries(libmv_bundle_adjuster ceres ${GFLAGS_LIBRARIES}) + + add_executable(libmv_homography + libmv_homography.cc) + target_link_libraries(libmv_homography ceres ${GFLAGS_LIBRARIES}) + + add_executable(denoising + denoising.cc + fields_of_experts.cc) + target_link_libraries(denoising ceres ${GFLAGS_LIBRARIES}) + + add_executable(robot_pose_mle + robot_pose_mle.cc) + target_link_libraries(robot_pose_mle ceres ${GFLAGS_LIBRARIES}) + +endif (GFLAGS) + +add_subdirectory(sampled_function) +add_subdirectory(slam) diff --git a/examples/Makefile.example b/examples/Makefile.example new file mode 100644 index 0000000..f2b0dc0 --- /dev/null +++ b/examples/Makefile.example @@ -0,0 +1,82 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: keir@google.com (Keir Mierle) +# +# This is an example Makefile for using Ceres. In practice, the Ceres authors +# suggest using CMake instead, but if Make is needed for some reason, this +# example serves to make it easy to do so. + +# This should point to place where you unpacked or cloned Ceres. +CERES_SRC_DIR := /home/keir/wrk/ceres-extra + +# This should point to the place where you built Ceres. If you got Ceres by +# installing it, then this will likely be /usr/local/lib. +CERES_BIN_DIR := /home/keir/wrk/ceres-extra-bin + +# The place you unpacked or cloned Eigen. If Eigen was installed from packages, +# this will likely be /usr/local/include. +EIGEN_SRC_DIR := /home/keir/src/eigen-3.0.5 + +INCLUDES := -I$(CERES_SRC_DIR)/include \ + -I$(EIGEN_SRC_DIR) + +CERES_LIBRARY := -lceres +CERES_LIBRARY_PATH := -L$(CERES_BIN_DIR)/lib +CERES_LIBRARY_DEPENDENCIES = -lgflags -lglog + +# If Ceres was built with Suitesparse: +CERES_LIBRARY_DEPENDENCIES += -llapack -lcamd -lamd -lccolamd -lcolamd -lcholmod + +# If Ceres was built with CXSparse: +CERES_LIBRARY_DEPENDENCIES += -lcxsparse + +# If Ceres was built with OpenMP: +CERES_LIBRARY_DEPENDENCIES += -fopenmp -lpthread -lgomp -lm + +# The set of object files for your application. +APPLICATION_OBJS := simple_bundle_adjuster.o + +all: simple_bundle_adjuster + +simple_bundle_adjuster: $(APPLICATION_OBJS) + g++ \ + $(APPLICATION_OBJS) \ + $(CERES_LIBRARY_PATH) \ + $(CERES_LIBRARY) \ + $(CERES_LIBRARY_DEPENDENCIES) \ + -o simple_bundle_adjuster + +# Disabling debug asserts via -DNDEBUG helps make Eigen faster, at the cost of +# not getting handy assert failures when there are issues in your code. +CFLAGS := -O2 -DNDEBUG + +# If you have files ending in .cpp instead of .cc, fix the next line +# appropriately. +%.o: %.cc $(DEPS) + g++ -c -o $@ $< $(CFLAGS) $(INCLUDES) diff --git a/examples/bal_problem.cc b/examples/bal_problem.cc new file mode 100644 index 0000000..1ee3c81 --- /dev/null +++ b/examples/bal_problem.cc @@ -0,0 +1,339 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "bal_problem.h" + +#include +#include +#include +#include +#include +#include "Eigen/Core" +#include "ceres/rotation.h" +#include "glog/logging.h" +#include "random.h" + +namespace ceres { +namespace examples { +namespace { +typedef Eigen::Map VectorRef; +typedef Eigen::Map ConstVectorRef; + +template +void FscanfOrDie(FILE* fptr, const char* format, T* value) { + int num_scanned = fscanf(fptr, format, value); + if (num_scanned != 1) { + LOG(FATAL) << "Invalid UW data file."; + } +} + +void PerturbPoint3(const double sigma, double* point) { + for (int i = 0; i < 3; ++i) { + point[i] += RandNormal() * sigma; + } +} + +double Median(std::vector* data) { + int n = data->size(); + std::vector::iterator mid_point = data->begin() + n / 2; + std::nth_element(data->begin(), mid_point, data->end()); + return *mid_point; +} + +} // namespace + +BALProblem::BALProblem(const std::string& filename, bool use_quaternions) { + FILE* fptr = fopen(filename.c_str(), "r"); + + if (fptr == NULL) { + LOG(FATAL) << "Error: unable to open file " << filename; + return; + }; + + // This wil die horribly on invalid files. Them's the breaks. + FscanfOrDie(fptr, "%d", &num_cameras_); + FscanfOrDie(fptr, "%d", &num_points_); + FscanfOrDie(fptr, "%d", &num_observations_); + + VLOG(1) << "Header: " << num_cameras_ + << " " << num_points_ + << " " << num_observations_; + + point_index_ = new int[num_observations_]; + camera_index_ = new int[num_observations_]; + observations_ = new double[2 * num_observations_]; + + num_parameters_ = 9 * num_cameras_ + 3 * num_points_; + parameters_ = new double[num_parameters_]; + + for (int i = 0; i < num_observations_; ++i) { + FscanfOrDie(fptr, "%d", camera_index_ + i); + FscanfOrDie(fptr, "%d", point_index_ + i); + for (int j = 0; j < 2; ++j) { + FscanfOrDie(fptr, "%lf", observations_ + 2*i + j); + } + } + + for (int i = 0; i < num_parameters_; ++i) { + FscanfOrDie(fptr, "%lf", parameters_ + i); + } + + fclose(fptr); + + use_quaternions_ = use_quaternions; + if (use_quaternions) { + // Switch the angle-axis rotations to quaternions. + num_parameters_ = 10 * num_cameras_ + 3 * num_points_; + double* quaternion_parameters = new double[num_parameters_]; + double* original_cursor = parameters_; + double* quaternion_cursor = quaternion_parameters; + for (int i = 0; i < num_cameras_; ++i) { + AngleAxisToQuaternion(original_cursor, quaternion_cursor); + quaternion_cursor += 4; + original_cursor += 3; + for (int j = 4; j < 10; ++j) { + *quaternion_cursor++ = *original_cursor++; + } + } + // Copy the rest of the points. + for (int i = 0; i < 3 * num_points_; ++i) { + *quaternion_cursor++ = *original_cursor++; + } + // Swap in the quaternion parameters. + delete []parameters_; + parameters_ = quaternion_parameters; + } +} + +// This function writes the problem to a file in the same format that +// is read by the constructor. +void BALProblem::WriteToFile(const std::string& filename) const { + FILE* fptr = fopen(filename.c_str(), "w"); + + if (fptr == NULL) { + LOG(FATAL) << "Error: unable to open file " << filename; + return; + }; + + fprintf(fptr, "%d %d %d\n", num_cameras_, num_points_, num_observations_); + + for (int i = 0; i < num_observations_; ++i) { + fprintf(fptr, "%d %d", camera_index_[i], point_index_[i]); + for (int j = 0; j < 2; ++j) { + fprintf(fptr, " %g", observations_[2 * i + j]); + } + fprintf(fptr, "\n"); + } + + for (int i = 0; i < num_cameras(); ++i) { + double angleaxis[9]; + if (use_quaternions_) { + // Output in angle-axis format. + QuaternionToAngleAxis(parameters_ + 10 * i, angleaxis); + memcpy(angleaxis + 3, parameters_ + 10 * i + 4, 6 * sizeof(double)); + } else { + memcpy(angleaxis, parameters_ + 9 * i, 9 * sizeof(double)); + } + for (int j = 0; j < 9; ++j) { + fprintf(fptr, "%.16g\n", angleaxis[j]); + } + } + + const double* points = parameters_ + camera_block_size() * num_cameras_; + for (int i = 0; i < num_points(); ++i) { + const double* point = points + i * point_block_size(); + for (int j = 0; j < point_block_size(); ++j) { + fprintf(fptr, "%.16g\n", point[j]); + } + } + + fclose(fptr); +} + +// Write the problem to a PLY file for inspection in Meshlab or CloudCompare. +void BALProblem::WriteToPLYFile(const std::string& filename) const { + std::ofstream of(filename.c_str()); + + of << "ply" + << '\n' << "format ascii 1.0" + << '\n' << "element vertex " << num_cameras_ + num_points_ + << '\n' << "property float x" + << '\n' << "property float y" + << '\n' << "property float z" + << '\n' << "property uchar red" + << '\n' << "property uchar green" + << '\n' << "property uchar blue" + << '\n' << "end_header" << std::endl; + + // Export extrinsic data (i.e. camera centers) as green points. + double angle_axis[3]; + double center[3]; + for (int i = 0; i < num_cameras(); ++i) { + const double* camera = cameras() + camera_block_size() * i; + CameraToAngleAxisAndCenter(camera, angle_axis, center); + of << center[0] << ' ' << center[1] << ' ' << center[2] + << " 0 255 0" << '\n'; + } + + // Export the structure (i.e. 3D Points) as white points. + const double* points = parameters_ + camera_block_size() * num_cameras_; + for (int i = 0; i < num_points(); ++i) { + const double* point = points + i * point_block_size(); + for (int j = 0; j < point_block_size(); ++j) { + of << point[j] << ' '; + } + of << "255 255 255\n"; + } + of.close(); +} + +void BALProblem::CameraToAngleAxisAndCenter(const double* camera, + double* angle_axis, + double* center) const { + VectorRef angle_axis_ref(angle_axis, 3); + if (use_quaternions_) { + QuaternionToAngleAxis(camera, angle_axis); + } else { + angle_axis_ref = ConstVectorRef(camera, 3); + } + + // c = -R't + Eigen::VectorXd inverse_rotation = -angle_axis_ref; + AngleAxisRotatePoint(inverse_rotation.data(), + camera + camera_block_size() - 6, + center); + VectorRef(center, 3) *= -1.0; +} + +void BALProblem::AngleAxisAndCenterToCamera(const double* angle_axis, + const double* center, + double* camera) const { + ConstVectorRef angle_axis_ref(angle_axis, 3); + if (use_quaternions_) { + AngleAxisToQuaternion(angle_axis, camera); + } else { + VectorRef(camera, 3) = angle_axis_ref; + } + + // t = -R * c + AngleAxisRotatePoint(angle_axis, + center, + camera + camera_block_size() - 6); + VectorRef(camera + camera_block_size() - 6, 3) *= -1.0; +} + + +void BALProblem::Normalize() { + // Compute the marginal median of the geometry. + std::vector tmp(num_points_); + Eigen::Vector3d median; + double* points = mutable_points(); + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < num_points_; ++j) { + tmp[j] = points[3 * j + i]; + } + median(i) = Median(&tmp); + } + + for (int i = 0; i < num_points_; ++i) { + VectorRef point(points + 3 * i, 3); + tmp[i] = (point - median).lpNorm<1>(); + } + + const double median_absolute_deviation = Median(&tmp); + + // Scale so that the median absolute deviation of the resulting + // reconstruction is 100. + const double scale = 100.0 / median_absolute_deviation; + + VLOG(2) << "median: " << median.transpose(); + VLOG(2) << "median absolute deviation: " << median_absolute_deviation; + VLOG(2) << "scale: " << scale; + + // X = scale * (X - median) + for (int i = 0; i < num_points_; ++i) { + VectorRef point(points + 3 * i, 3); + point = scale * (point - median); + } + + double* cameras = mutable_cameras(); + double angle_axis[3]; + double center[3]; + for (int i = 0; i < num_cameras_; ++i) { + double* camera = cameras + camera_block_size() * i; + CameraToAngleAxisAndCenter(camera, angle_axis, center); + // center = scale * (center - median) + VectorRef(center, 3) = scale * (VectorRef(center, 3) - median); + AngleAxisAndCenterToCamera(angle_axis, center, camera); + } +} + +void BALProblem::Perturb(const double rotation_sigma, + const double translation_sigma, + const double point_sigma) { + CHECK_GE(point_sigma, 0.0); + CHECK_GE(rotation_sigma, 0.0); + CHECK_GE(translation_sigma, 0.0); + + double* points = mutable_points(); + if (point_sigma > 0) { + for (int i = 0; i < num_points_; ++i) { + PerturbPoint3(point_sigma, points + 3 * i); + } + } + + for (int i = 0; i < num_cameras_; ++i) { + double* camera = mutable_cameras() + camera_block_size() * i; + + double angle_axis[3]; + double center[3]; + // Perturb in the rotation of the camera in the angle-axis + // representation. + CameraToAngleAxisAndCenter(camera, angle_axis, center); + if (rotation_sigma > 0.0) { + PerturbPoint3(rotation_sigma, angle_axis); + } + AngleAxisAndCenterToCamera(angle_axis, center, camera); + + if (translation_sigma > 0.0) { + PerturbPoint3(translation_sigma, camera + camera_block_size() - 6); + } + } +} + +BALProblem::~BALProblem() { + delete []point_index_; + delete []camera_index_; + delete []observations_; + delete []parameters_; +} + +} // namespace examples +} // namespace ceres diff --git a/examples/bal_problem.h b/examples/bal_problem.h new file mode 100644 index 0000000..e9a348e --- /dev/null +++ b/examples/bal_problem.h @@ -0,0 +1,109 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Class for loading and holding in memory bundle adjustment problems +// from the BAL (Bundle Adjustment in the Large) dataset from the +// University of Washington. +// +// For more details see http://grail.cs.washington.edu/projects/bal/ + +#ifndef CERES_EXAMPLES_BAL_PROBLEM_H_ +#define CERES_EXAMPLES_BAL_PROBLEM_H_ + +#include + +namespace ceres { +namespace examples { + +class BALProblem { + public: + explicit BALProblem(const std::string& filename, bool use_quaternions); + ~BALProblem(); + + void WriteToFile(const std::string& filename) const; + void WriteToPLYFile(const std::string& filename) const; + + // Move the "center" of the reconstruction to the origin, where the + // center is determined by computing the marginal median of the + // points. The reconstruction is then scaled so that the median + // absolute deviation of the points measured from the origin is + // 100.0. + // + // The reprojection error of the problem remains the same. + void Normalize(); + + // Perturb the camera pose and the geometry with random normal + // numbers with corresponding standard deviations. + void Perturb(const double rotation_sigma, + const double translation_sigma, + const double point_sigma); + + int camera_block_size() const { return use_quaternions_ ? 10 : 9; } + int point_block_size() const { return 3; } + int num_cameras() const { return num_cameras_; } + int num_points() const { return num_points_; } + int num_observations() const { return num_observations_; } + int num_parameters() const { return num_parameters_; } + const int* point_index() const { return point_index_; } + const int* camera_index() const { return camera_index_; } + const double* observations() const { return observations_; } + const double* parameters() const { return parameters_; } + const double* cameras() const { return parameters_; } + double* mutable_cameras() { return parameters_; } + double* mutable_points() { + return parameters_ + camera_block_size() * num_cameras_; + } + + private: + void CameraToAngleAxisAndCenter(const double* camera, + double* angle_axis, + double* center) const; + + void AngleAxisAndCenterToCamera(const double* angle_axis, + const double* center, + double* camera) const; + int num_cameras_; + int num_points_; + int num_observations_; + int num_parameters_; + bool use_quaternions_; + + int* point_index_; + int* camera_index_; + double* observations_; + // The parameter vector is laid out as follows + // [camera_1, ..., camera_n, point_1, ..., point_m] + double* parameters_; +}; + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_BAL_PROBLEM_H_ diff --git a/examples/bundle_adjuster.cc b/examples/bundle_adjuster.cc new file mode 100644 index 0000000..e21c4ee --- /dev/null +++ b/examples/bundle_adjuster.cc @@ -0,0 +1,343 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// An example of solving a dynamically sized problem with various +// solvers and loss functions. +// +// For a simpler bare bones example of doing bundle adjustment with +// Ceres, please see simple_bundle_adjuster.cc. +// +// NOTE: This example will not compile without gflags and SuiteSparse. +// +// The problem being solved here is known as a Bundle Adjustment +// problem in computer vision. Given a set of 3d points X_1, ..., X_n, +// a set of cameras P_1, ..., P_m. If the point X_i is visible in +// image j, then there is a 2D observation u_ij that is the expected +// projection of X_i using P_j. The aim of this optimization is to +// find values of X_i and P_j such that the reprojection error +// +// E(X,P) = sum_ij |u_ij - P_j X_i|^2 +// +// is minimized. +// +// The problem used here comes from a collection of bundle adjustment +// problems published at University of Washington. +// http://grail.cs.washington.edu/projects/bal + +#include +#include +#include +#include +#include +#include + +#include "bal_problem.h" +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "snavely_reprojection_error.h" + +DEFINE_string(input, "", "Input File name"); +DEFINE_string(trust_region_strategy, "levenberg_marquardt", + "Options are: levenberg_marquardt, dogleg."); +DEFINE_string(dogleg, "traditional_dogleg", "Options are: traditional_dogleg," + "subspace_dogleg."); + +DEFINE_bool(inner_iterations, false, "Use inner iterations to non-linearly " + "refine each successful trust region step."); + +DEFINE_string(blocks_for_inner_iterations, "automatic", "Options are: " + "automatic, cameras, points, cameras,points, points,cameras"); + +DEFINE_string(linear_solver, "sparse_schur", "Options are: " + "sparse_schur, dense_schur, iterative_schur, sparse_normal_cholesky, " + "dense_qr, dense_normal_cholesky and cgnr."); +DEFINE_bool(explicit_schur_complement, false, "If using ITERATIVE_SCHUR " + "then explicitly compute the Schur complement."); +DEFINE_string(preconditioner, "jacobi", "Options are: " + "identity, jacobi, schur_jacobi, cluster_jacobi, " + "cluster_tridiagonal."); +DEFINE_string(visibility_clustering, "canonical_views", + "single_linkage, canonical_views"); + +DEFINE_string(sparse_linear_algebra_library, "suite_sparse", + "Options are: suite_sparse and cx_sparse."); +DEFINE_string(dense_linear_algebra_library, "eigen", + "Options are: eigen and lapack."); +DEFINE_string(ordering, "automatic", "Options are: automatic, user."); + +DEFINE_bool(use_quaternions, false, "If true, uses quaternions to represent " + "rotations. If false, angle axis is used."); +DEFINE_bool(use_local_parameterization, false, "For quaternions, use a local " + "parameterization."); +DEFINE_bool(robustify, false, "Use a robust loss function."); + +DEFINE_double(eta, 1e-2, "Default value for eta. Eta determines the " + "accuracy of each linear solve of the truncated newton step. " + "Changing this parameter can affect solve performance."); + +DEFINE_int32(num_threads, 1, "Number of threads."); +DEFINE_int32(num_iterations, 5, "Number of iterations."); +DEFINE_double(max_solver_time, 1e32, "Maximum solve time in seconds."); +DEFINE_bool(nonmonotonic_steps, false, "Trust region algorithm can use" + " nonmonotic steps."); + +DEFINE_double(rotation_sigma, 0.0, "Standard deviation of camera rotation " + "perturbation."); +DEFINE_double(translation_sigma, 0.0, "Standard deviation of the camera " + "translation perturbation."); +DEFINE_double(point_sigma, 0.0, "Standard deviation of the point " + "perturbation."); +DEFINE_int32(random_seed, 38401, "Random seed used to set the state " + "of the pseudo random number generator used to generate " + "the pertubations."); +DEFINE_bool(line_search, false, "Use a line search instead of trust region " + "algorithm."); +DEFINE_string(initial_ply, "", "Export the BAL file data as a PLY file."); +DEFINE_string(final_ply, "", "Export the refined BAL file data as a PLY " + "file."); + +namespace ceres { +namespace examples { + +void SetLinearSolver(Solver::Options* options) { + CHECK(StringToLinearSolverType(FLAGS_linear_solver, + &options->linear_solver_type)); + CHECK(StringToPreconditionerType(FLAGS_preconditioner, + &options->preconditioner_type)); + CHECK(StringToVisibilityClusteringType(FLAGS_visibility_clustering, + &options->visibility_clustering_type)); + CHECK(StringToSparseLinearAlgebraLibraryType( + FLAGS_sparse_linear_algebra_library, + &options->sparse_linear_algebra_library_type)); + CHECK(StringToDenseLinearAlgebraLibraryType( + FLAGS_dense_linear_algebra_library, + &options->dense_linear_algebra_library_type)); + options->num_linear_solver_threads = FLAGS_num_threads; + options->use_explicit_schur_complement = FLAGS_explicit_schur_complement; +} + +void SetOrdering(BALProblem* bal_problem, Solver::Options* options) { + const int num_points = bal_problem->num_points(); + const int point_block_size = bal_problem->point_block_size(); + double* points = bal_problem->mutable_points(); + + const int num_cameras = bal_problem->num_cameras(); + const int camera_block_size = bal_problem->camera_block_size(); + double* cameras = bal_problem->mutable_cameras(); + + if (options->use_inner_iterations) { + if (FLAGS_blocks_for_inner_iterations == "cameras") { + LOG(INFO) << "Camera blocks for inner iterations"; + options->inner_iteration_ordering.reset(new ParameterBlockOrdering); + for (int i = 0; i < num_cameras; ++i) { + options->inner_iteration_ordering->AddElementToGroup(cameras + camera_block_size * i, 0); + } + } else if (FLAGS_blocks_for_inner_iterations == "points") { + LOG(INFO) << "Point blocks for inner iterations"; + options->inner_iteration_ordering.reset(new ParameterBlockOrdering); + for (int i = 0; i < num_points; ++i) { + options->inner_iteration_ordering->AddElementToGroup(points + point_block_size * i, 0); + } + } else if (FLAGS_blocks_for_inner_iterations == "cameras,points") { + LOG(INFO) << "Camera followed by point blocks for inner iterations"; + options->inner_iteration_ordering.reset(new ParameterBlockOrdering); + for (int i = 0; i < num_cameras; ++i) { + options->inner_iteration_ordering->AddElementToGroup(cameras + camera_block_size * i, 0); + } + for (int i = 0; i < num_points; ++i) { + options->inner_iteration_ordering->AddElementToGroup(points + point_block_size * i, 1); + } + } else if (FLAGS_blocks_for_inner_iterations == "points,cameras") { + LOG(INFO) << "Point followed by camera blocks for inner iterations"; + options->inner_iteration_ordering.reset(new ParameterBlockOrdering); + for (int i = 0; i < num_cameras; ++i) { + options->inner_iteration_ordering->AddElementToGroup(cameras + camera_block_size * i, 1); + } + for (int i = 0; i < num_points; ++i) { + options->inner_iteration_ordering->AddElementToGroup(points + point_block_size * i, 0); + } + } else if (FLAGS_blocks_for_inner_iterations == "automatic") { + LOG(INFO) << "Choosing automatic blocks for inner iterations"; + } else { + LOG(FATAL) << "Unknown block type for inner iterations: " + << FLAGS_blocks_for_inner_iterations; + } + } + + // Bundle adjustment problems have a sparsity structure that makes + // them amenable to more specialized and much more efficient + // solution strategies. The SPARSE_SCHUR, DENSE_SCHUR and + // ITERATIVE_SCHUR solvers make use of this specialized + // structure. + // + // This can either be done by specifying Options::ordering_type = + // ceres::SCHUR, in which case Ceres will automatically determine + // the right ParameterBlock ordering, or by manually specifying a + // suitable ordering vector and defining + // Options::num_eliminate_blocks. + if (FLAGS_ordering == "automatic") { + return; + } + + ceres::ParameterBlockOrdering* ordering = + new ceres::ParameterBlockOrdering; + + // The points come before the cameras. + for (int i = 0; i < num_points; ++i) { + ordering->AddElementToGroup(points + point_block_size * i, 0); + } + + for (int i = 0; i < num_cameras; ++i) { + // When using axis-angle, there is a single parameter block for + // the entire camera. + ordering->AddElementToGroup(cameras + camera_block_size * i, 1); + } + + options->linear_solver_ordering.reset(ordering); +} + +void SetMinimizerOptions(Solver::Options* options) { + options->max_num_iterations = FLAGS_num_iterations; + options->minimizer_progress_to_stdout = true; + options->num_threads = FLAGS_num_threads; + options->eta = FLAGS_eta; + options->max_solver_time_in_seconds = FLAGS_max_solver_time; + options->use_nonmonotonic_steps = FLAGS_nonmonotonic_steps; + if (FLAGS_line_search) { + options->minimizer_type = ceres::LINE_SEARCH; + } + + CHECK(StringToTrustRegionStrategyType(FLAGS_trust_region_strategy, + &options->trust_region_strategy_type)); + CHECK(StringToDoglegType(FLAGS_dogleg, &options->dogleg_type)); + options->use_inner_iterations = FLAGS_inner_iterations; +} + +void SetSolverOptionsFromFlags(BALProblem* bal_problem, + Solver::Options* options) { + SetMinimizerOptions(options); + SetLinearSolver(options); + SetOrdering(bal_problem, options); +} + +void BuildProblem(BALProblem* bal_problem, Problem* problem) { + const int point_block_size = bal_problem->point_block_size(); + const int camera_block_size = bal_problem->camera_block_size(); + double* points = bal_problem->mutable_points(); + double* cameras = bal_problem->mutable_cameras(); + + // Observations is 2*num_observations long array observations = + // [u_1, u_2, ... , u_n], where each u_i is two dimensional, the x + // and y positions of the observation. + const double* observations = bal_problem->observations(); + for (int i = 0; i < bal_problem->num_observations(); ++i) { + CostFunction* cost_function; + // Each Residual block takes a point and a camera as input and + // outputs a 2 dimensional residual. + cost_function = + (FLAGS_use_quaternions) + ? SnavelyReprojectionErrorWithQuaternions::Create( + observations[2 * i + 0], + observations[2 * i + 1]) + : SnavelyReprojectionError::Create( + observations[2 * i + 0], + observations[2 * i + 1]); + + // If enabled use Huber's loss function. + LossFunction* loss_function = FLAGS_robustify ? new HuberLoss(1.0) : NULL; + + // Each observation correponds to a pair of a camera and a point + // which are identified by camera_index()[i] and point_index()[i] + // respectively. + double* camera = + cameras + camera_block_size * bal_problem->camera_index()[i]; + double* point = points + point_block_size * bal_problem->point_index()[i]; + problem->AddResidualBlock(cost_function, loss_function, camera, point); + } + + if (FLAGS_use_quaternions && FLAGS_use_local_parameterization) { + LocalParameterization* camera_parameterization = + new ProductParameterization( + new QuaternionParameterization(), + new IdentityParameterization(6)); + for (int i = 0; i < bal_problem->num_cameras(); ++i) { + problem->SetParameterization(cameras + camera_block_size * i, + camera_parameterization); + } + } +} + +void SolveProblem(const char* filename) { + BALProblem bal_problem(filename, FLAGS_use_quaternions); + + if (!FLAGS_initial_ply.empty()) { + bal_problem.WriteToPLYFile(FLAGS_initial_ply); + } + + Problem problem; + + srand(FLAGS_random_seed); + bal_problem.Normalize(); + bal_problem.Perturb(FLAGS_rotation_sigma, + FLAGS_translation_sigma, + FLAGS_point_sigma); + + BuildProblem(&bal_problem, &problem); + Solver::Options options; + SetSolverOptionsFromFlags(&bal_problem, &options); + options.gradient_tolerance = 1e-16; + options.function_tolerance = 1e-16; + Solver::Summary summary; + Solve(options, &problem, &summary); + std::cout << summary.FullReport() << "\n"; + + if (!FLAGS_final_ply.empty()) { + bal_problem.WriteToPLYFile(FLAGS_final_ply); + } +} + +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + if (FLAGS_input.empty()) { + LOG(ERROR) << "Usage: bundle_adjuster --input=bal_problem"; + return 1; + } + + CHECK(FLAGS_use_quaternions || !FLAGS_use_local_parameterization) + << "--use_local_parameterization can only be used with " + << "--use_quaternions."; + ceres::examples::SolveProblem(FLAGS_input.c_str()); + return 0; +} diff --git a/examples/circle_fit.cc b/examples/circle_fit.cc new file mode 100644 index 0000000..b58ce4e --- /dev/null +++ b/examples/circle_fit.cc @@ -0,0 +1,164 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// This fits circles to a collection of points, where the error is related to +// the distance of a point from the circle. This uses auto-differentiation to +// take the derivatives. +// +// The input format is simple text. Feed on standard in: +// +// x_initial y_initial r_initial +// x1 y1 +// x2 y2 +// y3 y3 +// ... +// +// And the result after solving will be printed to stdout: +// +// x y r +// +// There are closed form solutions [1] to this problem which you may want to +// consider instead of using this one. If you already have a decent guess, Ceres +// can squeeze down the last bit of error. +// +// [1] http://www.mathworks.com/matlabcentral/fileexchange/5557-circle-fit/content/circfit.m + +#include +#include + +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" + +using ceres::AutoDiffCostFunction; +using ceres::CauchyLoss; +using ceres::CostFunction; +using ceres::LossFunction; +using ceres::Problem; +using ceres::Solve; +using ceres::Solver; + +DEFINE_double(robust_threshold, 0.0, "Robust loss parameter. Set to 0 for " + "normal squared error (no robustification)."); + +// The cost for a single sample. The returned residual is related to the +// distance of the point from the circle (passed in as x, y, m parameters). +// +// Note that the radius is parameterized as r = m^2 to constrain the radius to +// positive values. +class DistanceFromCircleCost { + public: + DistanceFromCircleCost(double xx, double yy) : xx_(xx), yy_(yy) {} + template bool operator()(const T* const x, + const T* const y, + const T* const m, // r = m^2 + T* residual) const { + // Since the radius is parameterized as m^2, unpack m to get r. + T r = *m * *m; + + // Get the position of the sample in the circle's coordinate system. + T xp = xx_ - *x; + T yp = yy_ - *y; + + // It is tempting to use the following cost: + // + // residual[0] = r - sqrt(xp*xp + yp*yp); + // + // which is the distance of the sample from the circle. This works + // reasonably well, but the sqrt() adds strong nonlinearities to the cost + // function. Instead, a different cost is used, which while not strictly a + // distance in the metric sense (it has units distance^2) it produces more + // robust fits when there are outliers. This is because the cost surface is + // more convex. + residual[0] = r*r - xp*xp - yp*yp; + return true; + } + + private: + // The measured x,y coordinate that should be on the circle. + double xx_, yy_; +}; + +int main(int argc, char** argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + + double x, y, r; + if (scanf("%lg %lg %lg", &x, &y, &r) != 3) { + fprintf(stderr, "Couldn't read first line.\n"); + return 1; + } + fprintf(stderr, "Got x, y, r %lg, %lg, %lg\n", x, y, r); + + // Save initial values for comparison. + double initial_x = x; + double initial_y = y; + double initial_r = r; + + // Parameterize r as m^2 so that it can't be negative. + double m = sqrt(r); + + Problem problem; + + // Configure the loss function. + LossFunction* loss = NULL; + if (FLAGS_robust_threshold) { + loss = new CauchyLoss(FLAGS_robust_threshold); + } + + // Add the residuals. + double xx, yy; + int num_points = 0; + while (scanf("%lf %lf\n", &xx, &yy) == 2) { + CostFunction *cost = + new AutoDiffCostFunction( + new DistanceFromCircleCost(xx, yy)); + problem.AddResidualBlock(cost, loss, &x, &y, &m); + num_points++; + } + + std::cout << "Got " << num_points << " points.\n"; + + // Build and solve the problem. + Solver::Options options; + options.max_num_iterations = 500; + options.linear_solver_type = ceres::DENSE_QR; + Solver::Summary summary; + Solve(options, &problem, &summary); + + // Recover r from m. + r = m * m; + + std::cout << summary.BriefReport() << "\n"; + std::cout << "x : " << initial_x << " -> " << x << "\n"; + std::cout << "y : " << initial_y << " -> " << y << "\n"; + std::cout << "r : " << initial_r << " -> " << r << "\n"; + return 0; +} diff --git a/examples/curve_fitting.c b/examples/curve_fitting.c new file mode 100644 index 0000000..0027aa8 --- /dev/null +++ b/examples/curve_fitting.c @@ -0,0 +1,187 @@ +/* Ceres Solver - A fast non-linear least squares minimizer + * Copyright 2015 Google Inc. All rights reserved. + * http://ceres-solver.org/ + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither the name of Google Inc. nor the names of its contributors may be + * used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * Author: mierle@gmail.com (Keir Mierle) + * + * This is a port of curve_fitting.cc to the minimal C API for Ceres. + */ + +#include +#include +#include // For NULL +#include "ceres/c_api.h" + +/* Data generated using the following octave code. + * + * randn('seed', 23497); + * m = 0.3; + * c = 0.1; + * x=[0:0.075:5]; + * y = exp(m * x + c); + * noise = randn(size(x)) * 0.2; + * y_observed = y + noise; + * data = [x', y_observed']; + * + */ + +int num_observations = 67; +double data[] = { + 0.000000e+00, 1.133898e+00, + 7.500000e-02, 1.334902e+00, + 1.500000e-01, 1.213546e+00, + 2.250000e-01, 1.252016e+00, + 3.000000e-01, 1.392265e+00, + 3.750000e-01, 1.314458e+00, + 4.500000e-01, 1.472541e+00, + 5.250000e-01, 1.536218e+00, + 6.000000e-01, 1.355679e+00, + 6.750000e-01, 1.463566e+00, + 7.500000e-01, 1.490201e+00, + 8.250000e-01, 1.658699e+00, + 9.000000e-01, 1.067574e+00, + 9.750000e-01, 1.464629e+00, + 1.050000e+00, 1.402653e+00, + 1.125000e+00, 1.713141e+00, + 1.200000e+00, 1.527021e+00, + 1.275000e+00, 1.702632e+00, + 1.350000e+00, 1.423899e+00, + 1.425000e+00, 1.543078e+00, + 1.500000e+00, 1.664015e+00, + 1.575000e+00, 1.732484e+00, + 1.650000e+00, 1.543296e+00, + 1.725000e+00, 1.959523e+00, + 1.800000e+00, 1.685132e+00, + 1.875000e+00, 1.951791e+00, + 1.950000e+00, 2.095346e+00, + 2.025000e+00, 2.361460e+00, + 2.100000e+00, 2.169119e+00, + 2.175000e+00, 2.061745e+00, + 2.250000e+00, 2.178641e+00, + 2.325000e+00, 2.104346e+00, + 2.400000e+00, 2.584470e+00, + 2.475000e+00, 1.914158e+00, + 2.550000e+00, 2.368375e+00, + 2.625000e+00, 2.686125e+00, + 2.700000e+00, 2.712395e+00, + 2.775000e+00, 2.499511e+00, + 2.850000e+00, 2.558897e+00, + 2.925000e+00, 2.309154e+00, + 3.000000e+00, 2.869503e+00, + 3.075000e+00, 3.116645e+00, + 3.150000e+00, 3.094907e+00, + 3.225000e+00, 2.471759e+00, + 3.300000e+00, 3.017131e+00, + 3.375000e+00, 3.232381e+00, + 3.450000e+00, 2.944596e+00, + 3.525000e+00, 3.385343e+00, + 3.600000e+00, 3.199826e+00, + 3.675000e+00, 3.423039e+00, + 3.750000e+00, 3.621552e+00, + 3.825000e+00, 3.559255e+00, + 3.900000e+00, 3.530713e+00, + 3.975000e+00, 3.561766e+00, + 4.050000e+00, 3.544574e+00, + 4.125000e+00, 3.867945e+00, + 4.200000e+00, 4.049776e+00, + 4.275000e+00, 3.885601e+00, + 4.350000e+00, 4.110505e+00, + 4.425000e+00, 4.345320e+00, + 4.500000e+00, 4.161241e+00, + 4.575000e+00, 4.363407e+00, + 4.650000e+00, 4.161576e+00, + 4.725000e+00, 4.619728e+00, + 4.800000e+00, 4.737410e+00, + 4.875000e+00, 4.727863e+00, + 4.950000e+00, 4.669206e+00, +}; + +/* This is the equivalent of a use-defined CostFunction in the C++ Ceres API. + * This is passed as a callback to the Ceres C API, which internally converts + * the callback into a CostFunction. */ +int exponential_residual(void* user_data, + double** parameters, + double* residuals, + double** jacobians) { + double* measurement = (double*) user_data; + double x = measurement[0]; + double y = measurement[1]; + double m = parameters[0][0]; + double c = parameters[1][0]; + + residuals[0] = y - exp(m * x + c); + if (jacobians == NULL) { + return 1; + } + if (jacobians[0] != NULL) { + jacobians[0][0] = - x * exp(m * x + c); /* dr/dm */ + } + if (jacobians[1] != NULL) { + jacobians[1][0] = - exp(m * x + c); /* dr/dc */ + } + return 1; +} + +int main(int argc, char** argv) { + /* Note: Typically it is better to compact m and c into one block, + * but in this case use separate blocks to illustrate the use of + * multiple parameter blocks. */ + double m = 0.0; + double c = 0.0; + + double *parameter_pointers[] = { &m, &c }; + int parameter_sizes[] = { 1, 1 }; + int i; + + ceres_problem_t* problem; + + /* Ceres has some internal stuff that needs to get initialized. */ + ceres_init(); + + problem = ceres_create_problem(); + + /* Add all the residuals. */ + for (i = 0; i < num_observations; ++i) { + ceres_problem_add_residual_block( + problem, + exponential_residual, /* Cost function */ + &data[2 * i], /* Points to the (x,y) measurement */ + NULL, /* No loss function */ + NULL, /* No loss function user data */ + 1, /* Number of residuals */ + 2, /* Number of parameter blocks */ + parameter_sizes, + parameter_pointers); + } + + ceres_solve(problem); + ceres_free_problem(problem); + + printf("Initial m: 0.0, c: 0.0\n"); + printf("Final m: %g, c: %g\n", m, c); + return 0; +} diff --git a/examples/curve_fitting.cc b/examples/curve_fitting.cc new file mode 100644 index 0000000..3f577f8 --- /dev/null +++ b/examples/curve_fitting.cc @@ -0,0 +1,163 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/ceres.h" +#include "glog/logging.h" + +using ceres::AutoDiffCostFunction; +using ceres::CostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +// Data generated using the following octave code. +// randn('seed', 23497); +// m = 0.3; +// c = 0.1; +// x=[0:0.075:5]; +// y = exp(m * x + c); +// noise = randn(size(x)) * 0.2; +// y_observed = y + noise; +// data = [x', y_observed']; + +const int kNumObservations = 67; +const double data[] = { + 0.000000e+00, 1.133898e+00, + 7.500000e-02, 1.334902e+00, + 1.500000e-01, 1.213546e+00, + 2.250000e-01, 1.252016e+00, + 3.000000e-01, 1.392265e+00, + 3.750000e-01, 1.314458e+00, + 4.500000e-01, 1.472541e+00, + 5.250000e-01, 1.536218e+00, + 6.000000e-01, 1.355679e+00, + 6.750000e-01, 1.463566e+00, + 7.500000e-01, 1.490201e+00, + 8.250000e-01, 1.658699e+00, + 9.000000e-01, 1.067574e+00, + 9.750000e-01, 1.464629e+00, + 1.050000e+00, 1.402653e+00, + 1.125000e+00, 1.713141e+00, + 1.200000e+00, 1.527021e+00, + 1.275000e+00, 1.702632e+00, + 1.350000e+00, 1.423899e+00, + 1.425000e+00, 1.543078e+00, + 1.500000e+00, 1.664015e+00, + 1.575000e+00, 1.732484e+00, + 1.650000e+00, 1.543296e+00, + 1.725000e+00, 1.959523e+00, + 1.800000e+00, 1.685132e+00, + 1.875000e+00, 1.951791e+00, + 1.950000e+00, 2.095346e+00, + 2.025000e+00, 2.361460e+00, + 2.100000e+00, 2.169119e+00, + 2.175000e+00, 2.061745e+00, + 2.250000e+00, 2.178641e+00, + 2.325000e+00, 2.104346e+00, + 2.400000e+00, 2.584470e+00, + 2.475000e+00, 1.914158e+00, + 2.550000e+00, 2.368375e+00, + 2.625000e+00, 2.686125e+00, + 2.700000e+00, 2.712395e+00, + 2.775000e+00, 2.499511e+00, + 2.850000e+00, 2.558897e+00, + 2.925000e+00, 2.309154e+00, + 3.000000e+00, 2.869503e+00, + 3.075000e+00, 3.116645e+00, + 3.150000e+00, 3.094907e+00, + 3.225000e+00, 2.471759e+00, + 3.300000e+00, 3.017131e+00, + 3.375000e+00, 3.232381e+00, + 3.450000e+00, 2.944596e+00, + 3.525000e+00, 3.385343e+00, + 3.600000e+00, 3.199826e+00, + 3.675000e+00, 3.423039e+00, + 3.750000e+00, 3.621552e+00, + 3.825000e+00, 3.559255e+00, + 3.900000e+00, 3.530713e+00, + 3.975000e+00, 3.561766e+00, + 4.050000e+00, 3.544574e+00, + 4.125000e+00, 3.867945e+00, + 4.200000e+00, 4.049776e+00, + 4.275000e+00, 3.885601e+00, + 4.350000e+00, 4.110505e+00, + 4.425000e+00, 4.345320e+00, + 4.500000e+00, 4.161241e+00, + 4.575000e+00, 4.363407e+00, + 4.650000e+00, 4.161576e+00, + 4.725000e+00, 4.619728e+00, + 4.800000e+00, 4.737410e+00, + 4.875000e+00, 4.727863e+00, + 4.950000e+00, 4.669206e+00, +}; + +struct ExponentialResidual { + ExponentialResidual(double x, double y) + : x_(x), y_(y) {} + + template bool operator()(const T* const m, + const T* const c, + T* residual) const { + residual[0] = y_ - exp(m[0] * x_ + c[0]); + return true; + } + + private: + const double x_; + const double y_; +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + double m = 0.0; + double c = 0.0; + + Problem problem; + for (int i = 0; i < kNumObservations; ++i) { + problem.AddResidualBlock( + new AutoDiffCostFunction( + new ExponentialResidual(data[2 * i], data[2 * i + 1])), + NULL, + &m, &c); + } + + Solver::Options options; + options.max_num_iterations = 25; + options.linear_solver_type = ceres::DENSE_QR; + options.minimizer_progress_to_stdout = true; + + Solver::Summary summary; + Solve(options, &problem, &summary); + std::cout << summary.BriefReport() << "\n"; + std::cout << "Initial m: " << 0.0 << " c: " << 0.0 << "\n"; + std::cout << "Final m: " << m << " c: " << c << "\n"; + return 0; +} diff --git a/examples/denoising.cc b/examples/denoising.cc new file mode 100644 index 0000000..a8bdd7c --- /dev/null +++ b/examples/denoising.cc @@ -0,0 +1,220 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) +// +// Denoising using Fields of Experts and the Ceres minimizer. +// +// Note that for good denoising results the weighting between the data term +// and the Fields of Experts term needs to be adjusted. This is discussed +// in [1]. This program assumes Gaussian noise. The noise model can be changed +// by substituing another function for QuadraticCostFunction. +// +// [1] S. Roth and M.J. Black. "Fields of Experts." International Journal of +// Computer Vision, 82(2):205--229, 2009. + +#include +#include +#include +#include +#include +#include + +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" + +#include "fields_of_experts.h" +#include "pgm_image.h" + +DEFINE_string(input, "", "File to which the output image should be written"); +DEFINE_string(foe_file, "", "FoE file to use"); +DEFINE_string(output, "", "File to which the output image should be written"); +DEFINE_double(sigma, 20.0, "Standard deviation of noise"); +DEFINE_bool(verbose, false, "Prints information about the solver progress."); +DEFINE_bool(line_search, false, "Use a line search instead of trust region " + "algorithm."); + +namespace ceres { +namespace examples { + +// This cost function is used to build the data term. +// +// f_i(x) = a * (x_i - b)^2 +// +class QuadraticCostFunction : public ceres::SizedCostFunction<1, 1> { + public: + QuadraticCostFunction(double a, double b) + : sqrta_(std::sqrt(a)), b_(b) {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + const double x = parameters[0][0]; + residuals[0] = sqrta_ * (x - b_); + if (jacobians != NULL && jacobians[0] != NULL) { + jacobians[0][0] = sqrta_; + } + return true; + } + private: + double sqrta_, b_; +}; + +// Creates a Fields of Experts MAP inference problem. +void CreateProblem(const FieldsOfExperts& foe, + const PGMImage& image, + Problem* problem, + PGMImage* solution) { + // Create the data term + CHECK_GT(FLAGS_sigma, 0.0); + const double coefficient = 1 / (2.0 * FLAGS_sigma * FLAGS_sigma); + for (unsigned index = 0; index < image.NumPixels(); ++index) { + ceres::CostFunction* cost_function = + new QuadraticCostFunction(coefficient, + image.PixelFromLinearIndex(index)); + problem->AddResidualBlock(cost_function, + NULL, + solution->MutablePixelFromLinearIndex(index)); + } + + // Create Ceres cost and loss functions for regularization. One is needed for + // each filter. + std::vector loss_function(foe.NumFilters()); + std::vector cost_function(foe.NumFilters()); + for (int alpha_index = 0; alpha_index < foe.NumFilters(); ++alpha_index) { + loss_function[alpha_index] = foe.NewLossFunction(alpha_index); + cost_function[alpha_index] = foe.NewCostFunction(alpha_index); + } + + // Add FoE regularization for each patch in the image. + for (int x = 0; x < image.width() - (foe.Size() - 1); ++x) { + for (int y = 0; y < image.height() - (foe.Size() - 1); ++y) { + // Build a vector with the pixel indices of this patch. + std::vector pixels; + const std::vector& x_delta_indices = foe.GetXDeltaIndices(); + const std::vector& y_delta_indices = foe.GetYDeltaIndices(); + for (int i = 0; i < foe.NumVariables(); ++i) { + double* pixel = solution->MutablePixel(x + x_delta_indices[i], + y + y_delta_indices[i]); + pixels.push_back(pixel); + } + // For this patch with coordinates (x, y), we will add foe.NumFilters() + // terms to the objective function. + for (int alpha_index = 0; alpha_index < foe.NumFilters(); ++alpha_index) { + problem->AddResidualBlock(cost_function[alpha_index], + loss_function[alpha_index], + pixels); + } + } + } +} + +// Solves the FoE problem using Ceres and post-processes it to make sure the +// solution stays within [0, 255]. +void SolveProblem(Problem* problem, PGMImage* solution) { + // These parameters may be experimented with. For example, ceres::DOGLEG tends + // to be faster for 2x2 filters, but gives solutions with slightly higher + // objective function value. + ceres::Solver::Options options; + options.max_num_iterations = 100; + if (FLAGS_verbose) { + options.minimizer_progress_to_stdout = true; + } + + if (FLAGS_line_search) { + options.minimizer_type = ceres::LINE_SEARCH; + } + + options.linear_solver_type = ceres::SPARSE_NORMAL_CHOLESKY; + options.function_tolerance = 1e-3; // Enough for denoising. + + ceres::Solver::Summary summary; + ceres::Solve(options, problem, &summary); + if (FLAGS_verbose) { + std::cout << summary.FullReport() << "\n"; + } + + // Make the solution stay in [0, 255]. + for (int x = 0; x < solution->width(); ++x) { + for (int y = 0; y < solution->height(); ++y) { + *solution->MutablePixel(x, y) = + std::min(255.0, std::max(0.0, solution->Pixel(x, y))); + } + } +} +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + using namespace ceres::examples; + std::string + usage("This program denoises an image using Ceres. Sample usage:\n"); + usage += argv[0]; + usage += " --input= --foe_file="; + CERES_GFLAGS_NAMESPACE::SetUsageMessage(usage); + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + + if (FLAGS_input.empty()) { + std::cerr << "Please provide an image file name.\n"; + return 1; + } + + if (FLAGS_foe_file.empty()) { + std::cerr << "Please provide a Fields of Experts file name.\n"; + return 1; + } + + // Load the Fields of Experts filters from file. + FieldsOfExperts foe; + if (!foe.LoadFromFile(FLAGS_foe_file)) { + std::cerr << "Loading \"" << FLAGS_foe_file << "\" failed.\n"; + return 2; + } + + // Read the images + PGMImage image(FLAGS_input); + if (image.width() == 0) { + std::cerr << "Reading \"" << FLAGS_input << "\" failed.\n"; + return 3; + } + PGMImage solution(image.width(), image.height()); + solution.Set(0.0); + + ceres::Problem problem; + CreateProblem(foe, image, &problem, &solution); + + SolveProblem(&problem, &solution); + + if (!FLAGS_output.empty()) { + CHECK(solution.WriteToFile(FLAGS_output)) + << "Writing \"" << FLAGS_output << "\" failed."; + } + + return 0; +} diff --git a/examples/ellipse_approximation.cc b/examples/ellipse_approximation.cc new file mode 100644 index 0000000..f519f0c --- /dev/null +++ b/examples/ellipse_approximation.cc @@ -0,0 +1,452 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) +// +// This fits points randomly distributed on an ellipse with an approximate +// line segment contour. This is done by jointly optimizing the control points +// of the line segment contour along with the preimage positions for the data +// points. The purpose of this example is to show an example use case for +// dynamic_sparsity, and how it can benefit problems which are numerically +// dense but dynamically sparse. + +#include +#include +#include "ceres/ceres.h" +#include "glog/logging.h" + +// Data generated with the following Python code. +// import numpy as np +// np.random.seed(1337) +// t = np.linspace(0.0, 2.0 * np.pi, 212, endpoint=False) +// t += 2.0 * np.pi * 0.01 * np.random.randn(t.size) +// theta = np.deg2rad(15) +// a, b = np.cos(theta), np.sin(theta) +// R = np.array([[a, -b], +// [b, a]]) +// Y = np.dot(np.c_[4.0 * np.cos(t), np.sin(t)], R.T) + +const int kYRows = 212; +const int kYCols = 2; +const double kYData[kYRows * kYCols] = { + +3.871364e+00, +9.916027e-01, + +3.864003e+00, +1.034148e+00, + +3.850651e+00, +1.072202e+00, + +3.868350e+00, +1.014408e+00, + +3.796381e+00, +1.153021e+00, + +3.857138e+00, +1.056102e+00, + +3.787532e+00, +1.162215e+00, + +3.704477e+00, +1.227272e+00, + +3.564711e+00, +1.294959e+00, + +3.754363e+00, +1.191948e+00, + +3.482098e+00, +1.322725e+00, + +3.602777e+00, +1.279658e+00, + +3.585433e+00, +1.286858e+00, + +3.347505e+00, +1.356415e+00, + +3.220855e+00, +1.378914e+00, + +3.558808e+00, +1.297174e+00, + +3.403618e+00, +1.343809e+00, + +3.179828e+00, +1.384721e+00, + +3.054789e+00, +1.398759e+00, + +3.294153e+00, +1.366808e+00, + +3.247312e+00, +1.374813e+00, + +2.988547e+00, +1.404247e+00, + +3.114508e+00, +1.392698e+00, + +2.899226e+00, +1.409802e+00, + +2.533256e+00, +1.414778e+00, + +2.654773e+00, +1.415909e+00, + +2.565100e+00, +1.415313e+00, + +2.976456e+00, +1.405118e+00, + +2.484200e+00, +1.413640e+00, + +2.324751e+00, +1.407476e+00, + +1.930468e+00, +1.378221e+00, + +2.329017e+00, +1.407688e+00, + +1.760640e+00, +1.360319e+00, + +2.147375e+00, +1.396603e+00, + +1.741989e+00, +1.358178e+00, + +1.743859e+00, +1.358394e+00, + +1.557372e+00, +1.335208e+00, + +1.280551e+00, +1.295087e+00, + +1.429880e+00, +1.317546e+00, + +1.213485e+00, +1.284400e+00, + +9.168172e-01, +1.232870e+00, + +1.311141e+00, +1.299839e+00, + +1.231969e+00, +1.287382e+00, + +7.453773e-01, +1.200049e+00, + +6.151587e-01, +1.173683e+00, + +5.935666e-01, +1.169193e+00, + +2.538707e-01, +1.094227e+00, + +6.806136e-01, +1.187089e+00, + +2.805447e-01, +1.100405e+00, + +6.184807e-01, +1.174371e+00, + +1.170550e-01, +1.061762e+00, + +2.890507e-01, +1.102365e+00, + +3.834234e-01, +1.123772e+00, + +3.980161e-04, +1.033061e+00, + -3.651680e-01, +9.370367e-01, + -8.386351e-01, +7.987201e-01, + -8.105704e-01, +8.073702e-01, + -8.735139e-01, +7.878886e-01, + -9.913836e-01, +7.506100e-01, + -8.784011e-01, +7.863636e-01, + -1.181440e+00, +6.882566e-01, + -1.229556e+00, +6.720191e-01, + -1.035839e+00, +7.362765e-01, + -8.031520e-01, +8.096470e-01, + -1.539136e+00, +5.629549e-01, + -1.755423e+00, +4.817306e-01, + -1.337589e+00, +6.348763e-01, + -1.836966e+00, +4.499485e-01, + -1.913367e+00, +4.195617e-01, + -2.126467e+00, +3.314900e-01, + -1.927625e+00, +4.138238e-01, + -2.339862e+00, +2.379074e-01, + -1.881736e+00, +4.322152e-01, + -2.116753e+00, +3.356163e-01, + -2.255733e+00, +2.754930e-01, + -2.555834e+00, +1.368473e-01, + -2.770277e+00, +2.895711e-02, + -2.563376e+00, +1.331890e-01, + -2.826715e+00, -9.000818e-04, + -2.978191e+00, -8.457804e-02, + -3.115855e+00, -1.658786e-01, + -2.982049e+00, -8.678322e-02, + -3.307892e+00, -2.902083e-01, + -3.038346e+00, -1.194222e-01, + -3.190057e+00, -2.122060e-01, + -3.279086e+00, -2.705777e-01, + -3.322028e+00, -2.999889e-01, + -3.122576e+00, -1.699965e-01, + -3.551973e+00, -4.768674e-01, + -3.581866e+00, -5.032175e-01, + -3.497799e+00, -4.315203e-01, + -3.565384e+00, -4.885602e-01, + -3.699493e+00, -6.199815e-01, + -3.585166e+00, -5.061925e-01, + -3.758914e+00, -6.918275e-01, + -3.741104e+00, -6.689131e-01, + -3.688331e+00, -6.077239e-01, + -3.810425e+00, -7.689015e-01, + -3.791829e+00, -7.386911e-01, + -3.789951e+00, -7.358189e-01, + -3.823100e+00, -7.918398e-01, + -3.857021e+00, -8.727074e-01, + -3.858250e+00, -8.767645e-01, + -3.872100e+00, -9.563174e-01, + -3.864397e+00, -1.032630e+00, + -3.846230e+00, -1.081669e+00, + -3.834799e+00, -1.102536e+00, + -3.866684e+00, -1.022901e+00, + -3.808643e+00, -1.139084e+00, + -3.868840e+00, -1.011569e+00, + -3.791071e+00, -1.158615e+00, + -3.797999e+00, -1.151267e+00, + -3.696278e+00, -1.232314e+00, + -3.779007e+00, -1.170504e+00, + -3.622855e+00, -1.270793e+00, + -3.647249e+00, -1.259166e+00, + -3.655412e+00, -1.255042e+00, + -3.573218e+00, -1.291696e+00, + -3.638019e+00, -1.263684e+00, + -3.498409e+00, -1.317750e+00, + -3.304143e+00, -1.364970e+00, + -3.183001e+00, -1.384295e+00, + -3.202456e+00, -1.381599e+00, + -3.244063e+00, -1.375332e+00, + -3.233308e+00, -1.377019e+00, + -3.060112e+00, -1.398264e+00, + -3.078187e+00, -1.396517e+00, + -2.689594e+00, -1.415761e+00, + -2.947662e+00, -1.407039e+00, + -2.854490e+00, -1.411860e+00, + -2.660499e+00, -1.415900e+00, + -2.875955e+00, -1.410930e+00, + -2.675385e+00, -1.415848e+00, + -2.813155e+00, -1.413363e+00, + -2.417673e+00, -1.411512e+00, + -2.725461e+00, -1.415373e+00, + -2.148334e+00, -1.396672e+00, + -2.108972e+00, -1.393738e+00, + -2.029905e+00, -1.387302e+00, + -2.046214e+00, -1.388687e+00, + -2.057402e+00, -1.389621e+00, + -1.650250e+00, -1.347160e+00, + -1.806764e+00, -1.365469e+00, + -1.206973e+00, -1.283343e+00, + -8.029259e-01, -1.211308e+00, + -1.229551e+00, -1.286993e+00, + -1.101507e+00, -1.265754e+00, + -9.110645e-01, -1.231804e+00, + -1.110046e+00, -1.267211e+00, + -8.465274e-01, -1.219677e+00, + -7.594163e-01, -1.202818e+00, + -8.023823e-01, -1.211203e+00, + -3.732519e-01, -1.121494e+00, + -1.918373e-01, -1.079668e+00, + -4.671988e-01, -1.142253e+00, + -4.033645e-01, -1.128215e+00, + -1.920740e-01, -1.079724e+00, + -3.022157e-01, -1.105389e+00, + -1.652831e-01, -1.073354e+00, + +4.671625e-01, -9.085886e-01, + +5.940178e-01, -8.721832e-01, + +3.147557e-01, -9.508290e-01, + +6.383631e-01, -8.591867e-01, + +9.888923e-01, -7.514088e-01, + +7.076339e-01, -8.386023e-01, + +1.326682e+00, -6.386698e-01, + +1.149834e+00, -6.988221e-01, + +1.257742e+00, -6.624207e-01, + +1.492352e+00, -5.799632e-01, + +1.595574e+00, -5.421766e-01, + +1.240173e+00, -6.684113e-01, + +1.706612e+00, -5.004442e-01, + +1.873984e+00, -4.353002e-01, + +1.985633e+00, -3.902561e-01, + +1.722880e+00, -4.942329e-01, + +2.095182e+00, -3.447402e-01, + +2.018118e+00, -3.768991e-01, + +2.422702e+00, -1.999563e-01, + +2.370611e+00, -2.239326e-01, + +2.152154e+00, -3.205250e-01, + +2.525121e+00, -1.516499e-01, + +2.422116e+00, -2.002280e-01, + +2.842806e+00, +9.536372e-03, + +3.030128e+00, +1.146027e-01, + +2.888424e+00, +3.433444e-02, + +2.991609e+00, +9.226409e-02, + +2.924807e+00, +5.445844e-02, + +3.007772e+00, +1.015875e-01, + +2.781973e+00, -2.282382e-02, + +3.164737e+00, +1.961781e-01, + +3.237671e+00, +2.430139e-01, + +3.046123e+00, +1.240014e-01, + +3.414834e+00, +3.669060e-01, + +3.436591e+00, +3.833600e-01, + +3.626207e+00, +5.444311e-01, + +3.223325e+00, +2.336361e-01, + +3.511963e+00, +4.431060e-01, + +3.698380e+00, +6.187442e-01, + +3.670244e+00, +5.884943e-01, + +3.558833e+00, +4.828230e-01, + +3.661807e+00, +5.797689e-01, + +3.767261e+00, +7.030893e-01, + +3.801065e+00, +7.532650e-01, + +3.828523e+00, +8.024454e-01, + +3.840719e+00, +8.287032e-01, + +3.848748e+00, +8.485921e-01, + +3.865801e+00, +9.066551e-01, + +3.870983e+00, +9.404873e-01, + +3.870263e+00, +1.001884e+00, + +3.864462e+00, +1.032374e+00, + +3.870542e+00, +9.996121e-01, + +3.865424e+00, +1.028474e+00 +}; +ceres::ConstMatrixRef kY(kYData, kYRows, kYCols); + +class PointToLineSegmentContourCostFunction : public ceres::CostFunction { + public: + PointToLineSegmentContourCostFunction(const int num_segments, + const Eigen::Vector2d& y) + : num_segments_(num_segments), y_(y) { + // The first parameter is the preimage position. + mutable_parameter_block_sizes()->push_back(1); + // The next parameters are the control points for the line segment contour. + for (int i = 0; i < num_segments_; ++i) { + mutable_parameter_block_sizes()->push_back(2); + } + set_num_residuals(2); + } + + virtual bool Evaluate(const double* const* x, + double* residuals, + double** jacobians) const { + // Convert the preimage position `t` into a segment index `i0` and the + // line segment interpolation parameter `u`. `i1` is the index of the next + // control point. + const double t = ModuloNumSegments(*x[0]); + CHECK_GE(t, 0.0); + CHECK_LT(t, num_segments_); + const int i0 = floor(t), i1 = (i0 + 1) % num_segments_; + const double u = t - i0; + + // Linearly interpolate between control points `i0` and `i1`. + residuals[0] = y_[0] - ((1.0 - u) * x[1 + i0][0] + u * x[1 + i1][0]); + residuals[1] = y_[1] - ((1.0 - u) * x[1 + i0][1] + u * x[1 + i1][1]); + + if (jacobians == NULL) { + return true; + } + + if (jacobians[0] != NULL) { + jacobians[0][0] = x[1 + i0][0] - x[1 + i1][0]; + jacobians[0][1] = x[1 + i0][1] - x[1 + i1][1]; + } + for (int i = 0; i < num_segments_; ++i) { + if (jacobians[i + 1] != NULL) { + ceres::MatrixRef(jacobians[i + 1], 2, 2).setZero(); + if (i == i0) { + jacobians[i + 1][0] = -(1.0 - u); + jacobians[i + 1][3] = -(1.0 - u); + } else if (i == i1) { + jacobians[i + 1][0] = -u; + jacobians[i + 1][3] = -u; + } + } + } + return true; + } + + static ceres::CostFunction* Create(const int num_segments, + const Eigen::Vector2d& y) { + return new PointToLineSegmentContourCostFunction(num_segments, y); + } + + private: + inline double ModuloNumSegments(const double t) const { + return t - num_segments_ * floor(t / num_segments_); + } + + const int num_segments_; + const Eigen::Vector2d y_; +}; + +class EuclideanDistanceFunctor { + public: + explicit EuclideanDistanceFunctor(const double& sqrt_weight) + : sqrt_weight_(sqrt_weight) {} + + template + bool operator()(const T* x0, const T* x1, T* residuals) const { + residuals[0] = sqrt_weight_ * (x0[0] - x1[0]); + residuals[1] = sqrt_weight_ * (x0[1] - x1[1]); + return true; + } + + static ceres::CostFunction* Create(const double sqrt_weight) { + return new ceres::AutoDiffCostFunction( + new EuclideanDistanceFunctor(sqrt_weight)); + } + + private: + const double sqrt_weight_; +}; + +bool SolveWithFullReport(ceres::Solver::Options options, + ceres::Problem* problem, + bool dynamic_sparsity) { + options.dynamic_sparsity = dynamic_sparsity; + + ceres::Solver::Summary summary; + ceres::Solve(options, problem, &summary); + + std::cout << "####################" << std::endl; + std::cout << "dynamic_sparsity = " << dynamic_sparsity << std::endl; + std::cout << "####################" << std::endl; + std::cout << summary.FullReport() << std::endl; + + return summary.termination_type == ceres::CONVERGENCE; +} + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // Problem configuration. + const int num_segments = 151; + const double regularization_weight = 1e-2; + + // Eigen::MatrixXd is column major so we define our own MatrixXd which is + // row major. Eigen::VectorXd can be used directly. + typedef Eigen::Matrix MatrixXd; + using Eigen::VectorXd; + + // `X` is the matrix of control points which make up the contour of line + // segments. The number of control points is equal to the number of line + // segments because the contour is closed. + // + // Initialize `X` to points on the unit circle. + VectorXd w(num_segments + 1); + w.setLinSpaced(num_segments + 1, 0.0, 2.0 * M_PI); + w.conservativeResize(num_segments); + MatrixXd X(num_segments, 2); + X.col(0) = w.array().cos(); + X.col(1) = w.array().sin(); + + // Each data point has an associated preimage position on the line segment + // contour. For each data point we initialize the preimage positions to + // the index of the closest control point. + const int num_observations = kY.rows(); + VectorXd t(num_observations); + for (int i = 0; i < num_observations; ++i) { + (X.rowwise() - kY.row(i)).rowwise().squaredNorm().minCoeff(&t[i]); + } + + ceres::Problem problem; + + // For each data point add a residual which measures its distance to its + // corresponding position on the line segment contour. + std::vector parameter_blocks(1 + num_segments); + parameter_blocks[0] = NULL; + for (int i = 0; i < num_segments; ++i) { + parameter_blocks[i + 1] = X.data() + 2 * i; + } + for (int i = 0; i < num_observations; ++i) { + parameter_blocks[0] = &t[i]; + problem.AddResidualBlock( + PointToLineSegmentContourCostFunction::Create(num_segments, kY.row(i)), + NULL, + parameter_blocks); + } + + // Add regularization to minimize the length of the line segment contour. + for (int i = 0; i < num_segments; ++i) { + problem.AddResidualBlock( + EuclideanDistanceFunctor::Create(sqrt(regularization_weight)), + NULL, + X.data() + 2 * i, + X.data() + 2 * ((i + 1) % num_segments)); + } + + ceres::Solver::Options options; + options.max_num_iterations = 100; + options.linear_solver_type = ceres::SPARSE_NORMAL_CHOLESKY; + + // First, solve `X` and `t` jointly with dynamic_sparsity = true. + MatrixXd X0 = X; + VectorXd t0 = t; + CHECK(SolveWithFullReport(options, &problem, true)); + + // Second, solve with dynamic_sparsity = false. + X = X0; + t = t0; + CHECK(SolveWithFullReport(options, &problem, false)); + + return 0; +} diff --git a/examples/fields_of_experts.cc b/examples/fields_of_experts.cc new file mode 100644 index 0000000..60d179a --- /dev/null +++ b/examples/fields_of_experts.cc @@ -0,0 +1,152 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) +// +// Class for loading the data required for descibing a Fields of Experts (FoE) +// model. + +#include "fields_of_experts.h" + +#include +#include + +#include "pgm_image.h" + +namespace ceres { +namespace examples { + +FieldsOfExpertsCost::FieldsOfExpertsCost(const std::vector& filter) + : filter_(filter) { + set_num_residuals(1); + for (int i = 0; i < filter_.size(); ++i) { + mutable_parameter_block_sizes()->push_back(1); + } +} + +// This is a dot product between a the scalar parameters and a vector of filter +// coefficients. +bool FieldsOfExpertsCost::Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + int num_variables = filter_.size(); + residuals[0] = 0; + for (int i = 0; i < num_variables; ++i) { + residuals[0] += filter_[i] * parameters[i][0]; + } + + if (jacobians != NULL) { + for (int i = 0; i < num_variables; ++i) { + if (jacobians[i] != NULL) { + jacobians[i][0] = filter_[i]; + } + } + } + + return true; +} + +// This loss function builds the FoE terms and is equal to +// +// f(x) = alpha_i * log(1 + (1/2)s) +// +void FieldsOfExpertsLoss::Evaluate(double sq_norm, double rho[3]) const { + const double c = 0.5; + const double sum = 1.0 + sq_norm * c; + const double inv = 1.0 / sum; + // 'sum' and 'inv' are always positive, assuming that 's' is. + rho[0] = alpha_ * log(sum); + rho[1] = alpha_ * c * inv; + rho[2] = - alpha_ * c * c * inv * inv; +} + +FieldsOfExperts::FieldsOfExperts() + : size_(0), num_filters_(0) { +} + +bool FieldsOfExperts::LoadFromFile(const std::string& filename) { + std::ifstream foe_file(filename.c_str()); + foe_file >> size_; + foe_file >> num_filters_; + if (size_ < 0 || num_filters_ < 0) { + return false; + } + const int num_variables = NumVariables(); + + x_delta_indices_.resize(num_variables); + for (int i = 0; i < num_variables; ++i) { + foe_file >> x_delta_indices_[i]; + } + + y_delta_indices_.resize(NumVariables()); + for (int i = 0; i < num_variables; ++i) { + foe_file >> y_delta_indices_[i]; + } + + alpha_.resize(num_filters_); + for (int i = 0; i < num_filters_; ++i) { + foe_file >> alpha_[i]; + } + + filters_.resize(num_filters_); + for (int i = 0; i < num_filters_; ++i) { + filters_[i].resize(num_variables); + for (int j = 0; j < num_variables; ++j) { + foe_file >> filters_[i][j]; + } + } + + // If any read failed, return failure. + if (!foe_file) { + size_ = 0; + return false; + } + + // There cannot be anything else in the file. Try reading another number and + // return failure if that succeeded. + double temp; + foe_file >> temp; + if (foe_file) { + size_ = 0; + return false; + } + + return true; +} + +ceres::CostFunction* FieldsOfExperts::NewCostFunction(int alpha_index) const { + return new FieldsOfExpertsCost(filters_[alpha_index]); +} + +ceres::LossFunction* FieldsOfExperts::NewLossFunction(int alpha_index) const { + return new FieldsOfExpertsLoss(alpha_[alpha_index]); +} + + +} // namespace examples +} // namespace ceres diff --git a/examples/fields_of_experts.h b/examples/fields_of_experts.h new file mode 100644 index 0000000..210ca69 --- /dev/null +++ b/examples/fields_of_experts.h @@ -0,0 +1,145 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) +// +// Class for loading the data required for descibing a Fields of Experts (FoE) +// model. The Fields of Experts regularization consists of terms of the type +// +// alpha * log(1 + (1/2)*sum(F .* X)^2), +// +// where F is a d-by-d image patch and alpha is a constant. This is implemented +// by a FieldsOfExpertsSum object which represents the dot product between the +// image patches and a FieldsOfExpertsLoss which implements the log(1 + (1/2)s) +// part. +// +// [1] S. Roth and M.J. Black. "Fields of Experts." International Journal of +// Computer Vision, 82(2):205--229, 2009. + +#ifndef CERES_EXAMPLES_FIELDS_OF_EXPERTS_H_ +#define CERES_EXAMPLES_FIELDS_OF_EXPERTS_H_ + +#include +#include + +#include "ceres/loss_function.h" +#include "ceres/cost_function.h" +#include "ceres/sized_cost_function.h" + +#include "pgm_image.h" + +namespace ceres { +namespace examples { + +// One sum in the FoE regularizer. This is a dot product between a filter and an +// image patch. It simply calculates the dot product between the filter +// coefficients given in the constructor and the scalar parameters passed to it. +class FieldsOfExpertsCost : public ceres::CostFunction { + public: + explicit FieldsOfExpertsCost(const std::vector& filter); + // The number of scalar parameters passed to Evaluate must equal the number of + // filter coefficients passed to the constructor. + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + + private: + const std::vector& filter_; +}; + +// The loss function used to build the correct regularization. See above. +// +// f(x) = alpha_i * log(1 + (1/2)s) +// +class FieldsOfExpertsLoss : public ceres::LossFunction { + public: + explicit FieldsOfExpertsLoss(double alpha) : alpha_(alpha) { } + virtual void Evaluate(double, double*) const; + + private: + const double alpha_; +}; + +// This class loads a set of filters and coefficients from file. Then the users +// obtains the correct loss and cost functions through NewCostFunction and +// NewLossFunction. +class FieldsOfExperts { + public: + // Creates an empty object with size() == 0. + FieldsOfExperts(); + // Attempts to load filters from a file. If unsuccessful it returns false and + // sets size() == 0. + bool LoadFromFile(const std::string& filename); + + // Side length of a square filter in this FoE. They are all of the same size. + int Size() const { + return size_; + } + + // Total number of pixels the filter covers. + int NumVariables() const { + return size_ * size_; + } + + // Number of filters used by the FoE. + int NumFilters() const { + return num_filters_; + } + + // Creates a new cost function. The caller is responsible for deallocating the + // memory. alpha_index specifies which filter is used in the cost function. + ceres::CostFunction* NewCostFunction(int alpha_index) const; + // Creates a new loss function. The caller is responsible for deallocating the + // memory. alpha_index specifies which filter this loss function is for. + ceres::LossFunction* NewLossFunction(int alpha_index) const; + + // Gets the delta pixel indices for all pixels in a patch. + const std::vector& GetXDeltaIndices() const { + return x_delta_indices_; + } + const std::vector& GetYDeltaIndices() const { + return y_delta_indices_; + } + + private: + // The side length of a square filter. + int size_; + // The number of different filters used. + int num_filters_; + // Pixel offsets for all variables. + std::vector x_delta_indices_, y_delta_indices_; + // The coefficients in front of each term. + std::vector alpha_; + // The filters used for the dot product with image patches. + std::vector > filters_; +}; + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_FIELDS_OF_EXPERTS_H_ diff --git a/examples/helloworld.cc b/examples/helloworld.cc new file mode 100644 index 0000000..22dff55 --- /dev/null +++ b/examples/helloworld.cc @@ -0,0 +1,83 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A simple example of using the Ceres minimizer. +// +// Minimize 0.5 (10 - x)^2 using jacobian matrix computed using +// automatic differentiation. + +#include "ceres/ceres.h" +#include "glog/logging.h" + +using ceres::AutoDiffCostFunction; +using ceres::CostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +// A templated cost functor that implements the residual r = 10 - +// x. The method operator() is templated so that we can then use an +// automatic differentiation wrapper around it to generate its +// derivatives. +struct CostFunctor { + template bool operator()(const T* const x, T* residual) const { + residual[0] = 10.0 - x[0]; + return true; + } +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // The variable to solve for with its initial value. It will be + // mutated in place by the solver. + double x = 0.5; + const double initial_x = x; + + // Build the problem. + Problem problem; + + // Set up the only cost function (also known as residual). This uses + // auto-differentiation to obtain the derivative (jacobian). + CostFunction* cost_function = + new AutoDiffCostFunction(new CostFunctor); + problem.AddResidualBlock(cost_function, NULL, &x); + + // Run the solver! + Solver::Options options; + options.minimizer_progress_to_stdout = true; + Solver::Summary summary; + Solve(options, &problem, &summary); + + std::cout << summary.BriefReport() << "\n"; + std::cout << "x : " << initial_x + << " -> " << x << "\n"; + return 0; +} diff --git a/examples/helloworld_analytic_diff.cc b/examples/helloworld_analytic_diff.cc new file mode 100644 index 0000000..9dbbc76 --- /dev/null +++ b/examples/helloworld_analytic_diff.cc @@ -0,0 +1,107 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A simple example of using the Ceres minimizer. +// +// Minimize 0.5 (10 - x)^2 using analytic jacobian matrix. + +#include +#include "ceres/ceres.h" +#include "glog/logging.h" + +using ceres::CostFunction; +using ceres::SizedCostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +// A CostFunction implementing analytically derivatives for the +// function f(x) = 10 - x. +class QuadraticCostFunction + : public SizedCostFunction<1 /* number of residuals */, + 1 /* size of first parameter */> { + public: + virtual ~QuadraticCostFunction() {} + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + double x = parameters[0][0]; + + // f(x) = 10 - x. + residuals[0] = 10 - x; + + // f'(x) = -1. Since there's only 1 parameter and that parameter + // has 1 dimension, there is only 1 element to fill in the + // jacobians. + // + // Since the Evaluate function can be called with the jacobians + // pointer equal to NULL, the Evaluate function must check to see + // if jacobians need to be computed. + // + // For this simple problem it is overkill to check if jacobians[0] + // is NULL, but in general when writing more complex + // CostFunctions, it is possible that Ceres may only demand the + // derivatives w.r.t. a subset of the parameter blocks. + if (jacobians != NULL && jacobians[0] != NULL) { + jacobians[0][0] = -1; + } + + return true; + } +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // The variable to solve for with its initial value. It will be + // mutated in place by the solver. + double x = 0.5; + const double initial_x = x; + + // Build the problem. + Problem problem; + + // Set up the only cost function (also known as residual). + CostFunction* cost_function = new QuadraticCostFunction; + problem.AddResidualBlock(cost_function, NULL, &x); + + // Run the solver! + Solver::Options options; + options.minimizer_progress_to_stdout = true; + Solver::Summary summary; + Solve(options, &problem, &summary); + + std::cout << summary.BriefReport() << "\n"; + std::cout << "x : " << initial_x + << " -> " << x << "\n"; + + return 0; +} diff --git a/examples/helloworld_numeric_diff.cc b/examples/helloworld_numeric_diff.cc new file mode 100644 index 0000000..0810f47 --- /dev/null +++ b/examples/helloworld_numeric_diff.cc @@ -0,0 +1,79 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Minimize 0.5 (10 - x)^2 using jacobian matrix computed using +// numeric differentiation. + +#include "ceres/ceres.h" +#include "glog/logging.h" + +using ceres::NumericDiffCostFunction; +using ceres::CENTRAL; +using ceres::CostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +// A cost functor that implements the residual r = 10 - x. +struct CostFunctor { + bool operator()(const double* const x, double* residual) const { + residual[0] = 10.0 - x[0]; + return true; + } +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // The variable to solve for with its initial value. It will be + // mutated in place by the solver. + double x = 0.5; + const double initial_x = x; + + // Build the problem. + Problem problem; + + // Set up the only cost function (also known as residual). This uses + // numeric differentiation to obtain the derivative (jacobian). + CostFunction* cost_function = + new NumericDiffCostFunction (new CostFunctor); + problem.AddResidualBlock(cost_function, NULL, &x); + + // Run the solver! + Solver::Options options; + options.minimizer_progress_to_stdout = true; + Solver::Summary summary; + Solve(options, &problem, &summary); + + std::cout << summary.BriefReport() << "\n"; + std::cout << "x : " << initial_x + << " -> " << x << "\n"; + return 0; +} diff --git a/examples/libmv_bundle_adjuster.cc b/examples/libmv_bundle_adjuster.cc new file mode 100644 index 0000000..47d0cd7 --- /dev/null +++ b/examples/libmv_bundle_adjuster.cc @@ -0,0 +1,843 @@ +// Copyright (c) 2013 libmv authors. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to +// deal in the Software without restriction, including without limitation the +// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +// IN THE SOFTWARE. +// +// Author: mierle@gmail.com (Keir Mierle) +// sergey.vfx@gmail.com (Sergey Sharybin) +// +// This is an example application which contains bundle adjustment code used +// in the Libmv library and Blender. It reads problems from files passed via +// the command line and runs the bundle adjuster on the problem. +// +// File with problem a binary file, for which it is crucial to know in which +// order bytes of float values are stored in. This information is provided +// by a single character in the beginning of the file. There're two possible +// values of this byte: +// - V, which means values in the file are stored with big endian type +// - v, which means values in the file are stored with little endian type +// +// The rest of the file contains data in the following order: +// - Space in which markers' coordinates are stored in +// - Camera intrinsics +// - Number of cameras +// - Cameras +// - Number of 3D points +// - 3D points +// - Number of markers +// - Markers +// +// Markers' space could either be normalized or image (pixels). This is defined +// by the single character in the file. P means markers in the file is in image +// space, and N means markers are in normalized space. +// +// Camera intrinsics are 8 described by 8 float 8. +// This values goes in the following order: +// +// - Focal length, principal point X, principal point Y, k1, k2, k3, p1, p2 +// +// Every camera is described by: +// +// - Image for which camera belongs to (single 4 bytes integer value). +// - Column-major camera rotation matrix, 9 float values. +// - Camera translation, 3-component vector of float values. +// +// Image number shall be greater or equal to zero. Order of cameras does not +// matter and gaps are possible. +// +// Every 3D point is decribed by: +// +// - Track number point belongs to (single 4 bytes integer value). +// - 3D position vector, 3-component vector of float values. +// +// Track number shall be greater or equal to zero. Order of tracks does not +// matter and gaps are possible. +// +// Finally every marker is described by: +// +// - Image marker belongs to single 4 bytes integer value). +// - Track marker belongs to single 4 bytes integer value). +// - 2D marker position vector, (two float values). +// +// Marker's space is used a default value for refine_intrinsics command line +// flag. This means if there's no refine_intrinsics flag passed via command +// line, camera intrinsics will be refined if markers in the problem are +// stored in image space and camera intrinsics will not be refined if markers +// are in normalized space. +// +// Passing refine_intrinsics command line flag defines explicitly whether +// refinement of intrinsics will happen. Currently, only none and all +// intrinsics refinement is supported. +// +// There're existing problem files dumped from blender stored in folder +// ../data/libmv-ba-problems. + +#include +#include +#include +#include +#include + +#ifdef _MSC_VER +# include +# define open _open +# define close _close +typedef unsigned __int32 uint32_t; +#else +#include +#include + +// O_BINARY is not defined on unix like platforms, as there is no +// difference between binary and text files. +#define O_BINARY 0 + +#endif + +#include "ceres/ceres.h" +#include "ceres/rotation.h" +#include "gflags/gflags.h" +#include "glog/logging.h" + +typedef Eigen::Matrix Mat3; +typedef Eigen::Matrix Vec6; +typedef Eigen::Vector3d Vec3; +typedef Eigen::Vector4d Vec4; + +using std::vector; + +DEFINE_string(input, "", "Input File name"); +DEFINE_string(refine_intrinsics, "", "Camera intrinsics to be refined. " + "Options are: none, radial."); + +namespace { + +// A EuclideanCamera is the location and rotation of the camera +// viewing an image. +// +// image identifies which image this camera represents. +// R is a 3x3 matrix representing the rotation of the camera. +// t is a translation vector representing its positions. +struct EuclideanCamera { + EuclideanCamera() : image(-1) {} + EuclideanCamera(const EuclideanCamera &c) : image(c.image), R(c.R), t(c.t) {} + + int image; + Mat3 R; + Vec3 t; +}; + +// A Point is the 3D location of a track. +// +// track identifies which track this point corresponds to. +// X represents the 3D position of the track. +struct EuclideanPoint { + EuclideanPoint() : track(-1) {} + EuclideanPoint(const EuclideanPoint &p) : track(p.track), X(p.X) {} + int track; + Vec3 X; +}; + +// A Marker is the 2D location of a tracked point in an image. +// +// x and y is the position of the marker in pixels from the top left corner +// in the image identified by an image. All markers for to the same target +// form a track identified by a common track number. +struct Marker { + int image; + int track; + double x, y; +}; + +// Cameras intrinsics to be bundled. +// +// BUNDLE_RADIAL actually implies bundling of k1 and k2 coefficients only, +// no bundling of k3 is possible at this moment. +enum BundleIntrinsics { + BUNDLE_NO_INTRINSICS = 0, + BUNDLE_FOCAL_LENGTH = 1, + BUNDLE_PRINCIPAL_POINT = 2, + BUNDLE_RADIAL_K1 = 4, + BUNDLE_RADIAL_K2 = 8, + BUNDLE_RADIAL = 12, + BUNDLE_TANGENTIAL_P1 = 16, + BUNDLE_TANGENTIAL_P2 = 32, + BUNDLE_TANGENTIAL = 48, +}; + +// Denotes which blocks to keep constant during bundling. +// For example it is useful to keep camera translations constant +// when bundling tripod motions. +enum BundleConstraints { + BUNDLE_NO_CONSTRAINTS = 0, + BUNDLE_NO_TRANSLATION = 1, +}; + +// The intrinsics need to get combined into a single parameter block; use these +// enums to index instead of numeric constants. +enum { + OFFSET_FOCAL_LENGTH, + OFFSET_PRINCIPAL_POINT_X, + OFFSET_PRINCIPAL_POINT_Y, + OFFSET_K1, + OFFSET_K2, + OFFSET_K3, + OFFSET_P1, + OFFSET_P2, +}; + +// Returns a pointer to the camera corresponding to a image. +EuclideanCamera *CameraForImage(vector *all_cameras, + const int image) { + if (image < 0 || image >= all_cameras->size()) { + return NULL; + } + EuclideanCamera *camera = &(*all_cameras)[image]; + if (camera->image == -1) { + return NULL; + } + return camera; +} + +const EuclideanCamera *CameraForImage( + const vector &all_cameras, + const int image) { + if (image < 0 || image >= all_cameras.size()) { + return NULL; + } + const EuclideanCamera *camera = &all_cameras[image]; + if (camera->image == -1) { + return NULL; + } + return camera; +} + +// Returns maximal image number at which marker exists. +int MaxImage(const vector &all_markers) { + if (all_markers.size() == 0) { + return -1; + } + + int max_image = all_markers[0].image; + for (int i = 1; i < all_markers.size(); i++) { + max_image = std::max(max_image, all_markers[i].image); + } + return max_image; +} + +// Returns a pointer to the point corresponding to a track. +EuclideanPoint *PointForTrack(vector *all_points, + const int track) { + if (track < 0 || track >= all_points->size()) { + return NULL; + } + EuclideanPoint *point = &(*all_points)[track]; + if (point->track == -1) { + return NULL; + } + return point; +} + +// Reader of binary file which makes sure possibly needed endian +// conversion happens when loading values like floats and integers. +// +// File's endian type is reading from a first character of file, which +// could either be V for big endian or v for little endian. This +// means you need to design file format assuming first character +// denotes file endianness in this way. +class EndianAwareFileReader { + public: + EndianAwareFileReader(void) : file_descriptor_(-1) { + // Get an endian type of the host machine. + union { + unsigned char bytes[4]; + uint32_t value; + } endian_test = { { 0, 1, 2, 3 } }; + host_endian_type_ = endian_test.value; + file_endian_type_ = host_endian_type_; + } + + ~EndianAwareFileReader(void) { + if (file_descriptor_ > 0) { + close(file_descriptor_); + } + } + + bool OpenFile(const std::string &file_name) { + file_descriptor_ = open(file_name.c_str(), O_RDONLY | O_BINARY); + if (file_descriptor_ < 0) { + return false; + } + // Get an endian tpye of data in the file. + unsigned char file_endian_type_flag = Read(); + if (file_endian_type_flag == 'V') { + file_endian_type_ = kBigEndian; + } else if (file_endian_type_flag == 'v') { + file_endian_type_ = kLittleEndian; + } else { + LOG(FATAL) << "Problem file is stored in unknown endian type."; + } + return true; + } + + // Read value from the file, will switch endian if needed. + template + T Read(void) const { + T value; + CHECK_GT(read(file_descriptor_, &value, sizeof(value)), 0); + // Switch endian type if file contains data in different type + // that current machine. + if (file_endian_type_ != host_endian_type_) { + value = SwitchEndian(value); + } + return value; + } + private: + static const long int kLittleEndian = 0x03020100ul; + static const long int kBigEndian = 0x00010203ul; + + // Switch endian type between big to little. + template + T SwitchEndian(const T value) const { + if (sizeof(T) == 4) { + unsigned int temp_value = static_cast(value); + return ((temp_value >> 24)) | + ((temp_value << 8) & 0x00ff0000) | + ((temp_value >> 8) & 0x0000ff00) | + ((temp_value << 24)); + } else if (sizeof(T) == 1) { + return value; + } else { + LOG(FATAL) << "Entered non-implemented part of endian switching function."; + } + } + + int host_endian_type_; + int file_endian_type_; + int file_descriptor_; +}; + +// Read 3x3 column-major matrix from the file +void ReadMatrix3x3(const EndianAwareFileReader &file_reader, + Mat3 *matrix) { + for (int i = 0; i < 9; i++) { + (*matrix)(i % 3, i / 3) = file_reader.Read(); + } +} + +// Read 3-vector from file +void ReadVector3(const EndianAwareFileReader &file_reader, + Vec3 *vector) { + for (int i = 0; i < 3; i++) { + (*vector)(i) = file_reader.Read(); + } +} + +// Reads a bundle adjustment problem from the file. +// +// file_name denotes from which file to read the problem. +// camera_intrinsics will contain initial camera intrinsics values. +// +// all_cameras is a vector of all reconstructed cameras to be optimized, +// vector element with number i will contain camera for image i. +// +// all_points is a vector of all reconstructed 3D points to be optimized, +// vector element with number i will contain point for track i. +// +// all_markers is a vector of all tracked markers existing in +// the problem. Only used for reprojection error calculation, stay +// unchanged during optimization. +// +// Returns false if any kind of error happened during +// reading. +bool ReadProblemFromFile(const std::string &file_name, + double camera_intrinsics[8], + vector *all_cameras, + vector *all_points, + bool *is_image_space, + vector *all_markers) { + EndianAwareFileReader file_reader; + if (!file_reader.OpenFile(file_name)) { + return false; + } + + // Read markers' space flag. + unsigned char is_image_space_flag = file_reader.Read(); + if (is_image_space_flag == 'P') { + *is_image_space = true; + } else if (is_image_space_flag == 'N') { + *is_image_space = false; + } else { + LOG(FATAL) << "Problem file contains markers stored in unknown space."; + } + + // Read camera intrinsics. + for (int i = 0; i < 8; i++) { + camera_intrinsics[i] = file_reader.Read(); + } + + // Read all cameras. + int number_of_cameras = file_reader.Read(); + for (int i = 0; i < number_of_cameras; i++) { + EuclideanCamera camera; + + camera.image = file_reader.Read(); + ReadMatrix3x3(file_reader, &camera.R); + ReadVector3(file_reader, &camera.t); + + if (camera.image >= all_cameras->size()) { + all_cameras->resize(camera.image + 1); + } + + (*all_cameras)[camera.image].image = camera.image; + (*all_cameras)[camera.image].R = camera.R; + (*all_cameras)[camera.image].t = camera.t; + } + + LOG(INFO) << "Read " << number_of_cameras << " cameras."; + + // Read all reconstructed 3D points. + int number_of_points = file_reader.Read(); + for (int i = 0; i < number_of_points; i++) { + EuclideanPoint point; + + point.track = file_reader.Read(); + ReadVector3(file_reader, &point.X); + + if (point.track >= all_points->size()) { + all_points->resize(point.track + 1); + } + + (*all_points)[point.track].track = point.track; + (*all_points)[point.track].X = point.X; + } + + LOG(INFO) << "Read " << number_of_points << " points."; + + // And finally read all markers. + int number_of_markers = file_reader.Read(); + for (int i = 0; i < number_of_markers; i++) { + Marker marker; + + marker.image = file_reader.Read(); + marker.track = file_reader.Read(); + marker.x = file_reader.Read(); + marker.y = file_reader.Read(); + + all_markers->push_back(marker); + } + + LOG(INFO) << "Read " << number_of_markers << " markers."; + + return true; +} + +// Apply camera intrinsics to the normalized point to get image coordinates. +// This applies the radial lens distortion to a point which is in normalized +// camera coordinates (i.e. the principal point is at (0, 0)) to get image +// coordinates in pixels. Templated for use with autodifferentiation. +template +inline void ApplyRadialDistortionCameraIntrinsics(const T &focal_length_x, + const T &focal_length_y, + const T &principal_point_x, + const T &principal_point_y, + const T &k1, + const T &k2, + const T &k3, + const T &p1, + const T &p2, + const T &normalized_x, + const T &normalized_y, + T *image_x, + T *image_y) { + T x = normalized_x; + T y = normalized_y; + + // Apply distortion to the normalized points to get (xd, yd). + T r2 = x*x + y*y; + T r4 = r2 * r2; + T r6 = r4 * r2; + T r_coeff = 1.0 + k1 * r2 + k2 * r4 + k3 * r6; + T xd = x * r_coeff + 2.0 * p1 * x * y + p2 * (r2 + 2.0 * x * x); + T yd = y * r_coeff + 2.0 * p2 * x * y + p1 * (r2 + 2.0 * y * y); + + // Apply focal length and principal point to get the final image coordinates. + *image_x = focal_length_x * xd + principal_point_x; + *image_y = focal_length_y * yd + principal_point_y; +} + +// Cost functor which computes reprojection error of 3D point X +// on camera defined by angle-axis rotation and it's translation +// (which are in the same block due to optimization reasons). +// +// This functor uses a radial distortion model. +struct OpenCVReprojectionError { + OpenCVReprojectionError(const double observed_x, const double observed_y) + : observed_x(observed_x), observed_y(observed_y) {} + + template + bool operator()(const T* const intrinsics, + const T* const R_t, // Rotation denoted by angle axis + // followed with translation + const T* const X, // Point coordinates 3x1. + T* residuals) const { + // Unpack the intrinsics. + const T& focal_length = intrinsics[OFFSET_FOCAL_LENGTH]; + const T& principal_point_x = intrinsics[OFFSET_PRINCIPAL_POINT_X]; + const T& principal_point_y = intrinsics[OFFSET_PRINCIPAL_POINT_Y]; + const T& k1 = intrinsics[OFFSET_K1]; + const T& k2 = intrinsics[OFFSET_K2]; + const T& k3 = intrinsics[OFFSET_K3]; + const T& p1 = intrinsics[OFFSET_P1]; + const T& p2 = intrinsics[OFFSET_P2]; + + // Compute projective coordinates: x = RX + t. + T x[3]; + + ceres::AngleAxisRotatePoint(R_t, X, x); + x[0] += R_t[3]; + x[1] += R_t[4]; + x[2] += R_t[5]; + + // Compute normalized coordinates: x /= x[2]. + T xn = x[0] / x[2]; + T yn = x[1] / x[2]; + + T predicted_x, predicted_y; + + // Apply distortion to the normalized points to get (xd, yd). + // TODO(keir): Do early bailouts for zero distortion; these are expensive + // jet operations. + ApplyRadialDistortionCameraIntrinsics(focal_length, + focal_length, + principal_point_x, + principal_point_y, + k1, k2, k3, + p1, p2, + xn, yn, + &predicted_x, + &predicted_y); + + // The error is the difference between the predicted and observed position. + residuals[0] = predicted_x - observed_x; + residuals[1] = predicted_y - observed_y; + + return true; + } + + const double observed_x; + const double observed_y; +}; + +// Print a message to the log which camera intrinsics are gonna to be optimized. +void BundleIntrinsicsLogMessage(const int bundle_intrinsics) { + if (bundle_intrinsics == BUNDLE_NO_INTRINSICS) { + LOG(INFO) << "Bundling only camera positions."; + } else { + std::string bundling_message = ""; + +#define APPEND_BUNDLING_INTRINSICS(name, flag) \ + if (bundle_intrinsics & flag) { \ + if (!bundling_message.empty()) { \ + bundling_message += ", "; \ + } \ + bundling_message += name; \ + } (void)0 + + APPEND_BUNDLING_INTRINSICS("f", BUNDLE_FOCAL_LENGTH); + APPEND_BUNDLING_INTRINSICS("px, py", BUNDLE_PRINCIPAL_POINT); + APPEND_BUNDLING_INTRINSICS("k1", BUNDLE_RADIAL_K1); + APPEND_BUNDLING_INTRINSICS("k2", BUNDLE_RADIAL_K2); + APPEND_BUNDLING_INTRINSICS("p1", BUNDLE_TANGENTIAL_P1); + APPEND_BUNDLING_INTRINSICS("p2", BUNDLE_TANGENTIAL_P2); + + LOG(INFO) << "Bundling " << bundling_message << "."; + } +} + +// Print a message to the log containing all the camera intriniscs values. +void PrintCameraIntrinsics(const char *text, const double *camera_intrinsics) { + std::ostringstream intrinsics_output; + + intrinsics_output << "f=" << camera_intrinsics[OFFSET_FOCAL_LENGTH]; + + intrinsics_output << + " cx=" << camera_intrinsics[OFFSET_PRINCIPAL_POINT_X] << + " cy=" << camera_intrinsics[OFFSET_PRINCIPAL_POINT_Y]; + +#define APPEND_DISTORTION_COEFFICIENT(name, offset) \ + { \ + if (camera_intrinsics[offset] != 0.0) { \ + intrinsics_output << " " name "=" << camera_intrinsics[offset]; \ + } \ + } (void)0 + + APPEND_DISTORTION_COEFFICIENT("k1", OFFSET_K1); + APPEND_DISTORTION_COEFFICIENT("k2", OFFSET_K2); + APPEND_DISTORTION_COEFFICIENT("k3", OFFSET_K3); + APPEND_DISTORTION_COEFFICIENT("p1", OFFSET_P1); + APPEND_DISTORTION_COEFFICIENT("p2", OFFSET_P2); + +#undef APPEND_DISTORTION_COEFFICIENT + + LOG(INFO) << text << intrinsics_output.str(); +} + +// Get a vector of camera's rotations denoted by angle axis +// conjuncted with translations into single block +// +// Element with index i matches to a rotation+translation for +// camera at image i. +vector PackCamerasRotationAndTranslation( + const vector &all_markers, + const vector &all_cameras) { + vector all_cameras_R_t; + int max_image = MaxImage(all_markers); + + all_cameras_R_t.resize(max_image + 1); + + for (int i = 0; i <= max_image; i++) { + const EuclideanCamera *camera = CameraForImage(all_cameras, i); + + if (!camera) { + continue; + } + + ceres::RotationMatrixToAngleAxis(&camera->R(0, 0), + &all_cameras_R_t[i](0)); + all_cameras_R_t[i].tail<3>() = camera->t; + } + + return all_cameras_R_t; +} + +// Convert cameras rotations fro mangle axis back to rotation matrix. +void UnpackCamerasRotationAndTranslation( + const vector &all_markers, + const vector &all_cameras_R_t, + vector *all_cameras) { + int max_image = MaxImage(all_markers); + + for (int i = 0; i <= max_image; i++) { + EuclideanCamera *camera = CameraForImage(all_cameras, i); + + if (!camera) { + continue; + } + + ceres::AngleAxisToRotationMatrix(&all_cameras_R_t[i](0), + &camera->R(0, 0)); + camera->t = all_cameras_R_t[i].tail<3>(); + } +} + +void EuclideanBundleCommonIntrinsics(const vector &all_markers, + const int bundle_intrinsics, + const int bundle_constraints, + double *camera_intrinsics, + vector *all_cameras, + vector *all_points) { + PrintCameraIntrinsics("Original intrinsics: ", camera_intrinsics); + + ceres::Problem::Options problem_options; + ceres::Problem problem(problem_options); + + // Convert cameras rotations to angle axis and merge with translation + // into single parameter block for maximal minimization speed + // + // Block for minimization has got the following structure: + // <3 elements for angle-axis> <3 elements for translation> + vector all_cameras_R_t = + PackCamerasRotationAndTranslation(all_markers, *all_cameras); + + // Parameterization used to restrict camera motion for modal solvers. + ceres::SubsetParameterization *constant_transform_parameterization = NULL; + if (bundle_constraints & BUNDLE_NO_TRANSLATION) { + std::vector constant_translation; + + // First three elements are rotation, last three are translation. + constant_translation.push_back(3); + constant_translation.push_back(4); + constant_translation.push_back(5); + + constant_transform_parameterization = + new ceres::SubsetParameterization(6, constant_translation); + } + + int num_residuals = 0; + bool have_locked_camera = false; + for (int i = 0; i < all_markers.size(); ++i) { + const Marker &marker = all_markers[i]; + EuclideanCamera *camera = CameraForImage(all_cameras, marker.image); + EuclideanPoint *point = PointForTrack(all_points, marker.track); + if (camera == NULL || point == NULL) { + continue; + } + + // Rotation of camera denoted in angle axis followed with + // camera translaiton. + double *current_camera_R_t = &all_cameras_R_t[camera->image](0); + + problem.AddResidualBlock(new ceres::AutoDiffCostFunction< + OpenCVReprojectionError, 2, 8, 6, 3>( + new OpenCVReprojectionError( + marker.x, + marker.y)), + NULL, + camera_intrinsics, + current_camera_R_t, + &point->X(0)); + + // We lock the first camera to better deal with scene orientation ambiguity. + if (!have_locked_camera) { + problem.SetParameterBlockConstant(current_camera_R_t); + have_locked_camera = true; + } + + if (bundle_constraints & BUNDLE_NO_TRANSLATION) { + problem.SetParameterization(current_camera_R_t, + constant_transform_parameterization); + } + + num_residuals++; + } + LOG(INFO) << "Number of residuals: " << num_residuals; + + if (!num_residuals) { + LOG(INFO) << "Skipping running minimizer with zero residuals"; + return; + } + + BundleIntrinsicsLogMessage(bundle_intrinsics); + + if (bundle_intrinsics == BUNDLE_NO_INTRINSICS) { + // No camera intrinsics are being refined, + // set the whole parameter block as constant for best performance. + problem.SetParameterBlockConstant(camera_intrinsics); + } else { + // Set the camera intrinsics that are not to be bundled as + // constant using some macro trickery. + + std::vector constant_intrinsics; +#define MAYBE_SET_CONSTANT(bundle_enum, offset) \ + if (!(bundle_intrinsics & bundle_enum)) { \ + constant_intrinsics.push_back(offset); \ + } + MAYBE_SET_CONSTANT(BUNDLE_FOCAL_LENGTH, OFFSET_FOCAL_LENGTH); + MAYBE_SET_CONSTANT(BUNDLE_PRINCIPAL_POINT, OFFSET_PRINCIPAL_POINT_X); + MAYBE_SET_CONSTANT(BUNDLE_PRINCIPAL_POINT, OFFSET_PRINCIPAL_POINT_Y); + MAYBE_SET_CONSTANT(BUNDLE_RADIAL_K1, OFFSET_K1); + MAYBE_SET_CONSTANT(BUNDLE_RADIAL_K2, OFFSET_K2); + MAYBE_SET_CONSTANT(BUNDLE_TANGENTIAL_P1, OFFSET_P1); + MAYBE_SET_CONSTANT(BUNDLE_TANGENTIAL_P2, OFFSET_P2); +#undef MAYBE_SET_CONSTANT + + // Always set K3 constant, it's not used at the moment. + constant_intrinsics.push_back(OFFSET_K3); + + ceres::SubsetParameterization *subset_parameterization = + new ceres::SubsetParameterization(8, constant_intrinsics); + + problem.SetParameterization(camera_intrinsics, subset_parameterization); + } + + // Configure the solver. + ceres::Solver::Options options; + options.use_nonmonotonic_steps = true; + options.preconditioner_type = ceres::SCHUR_JACOBI; + options.linear_solver_type = ceres::ITERATIVE_SCHUR; + options.use_inner_iterations = true; + options.max_num_iterations = 100; + options.minimizer_progress_to_stdout = true; + + // Solve! + ceres::Solver::Summary summary; + ceres::Solve(options, &problem, &summary); + + std::cout << "Final report:\n" << summary.FullReport(); + + // Copy rotations and translations back. + UnpackCamerasRotationAndTranslation(all_markers, + all_cameras_R_t, + all_cameras); + + PrintCameraIntrinsics("Final intrinsics: ", camera_intrinsics); +} +} // namespace + +int main(int argc, char **argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + + if (FLAGS_input.empty()) { + LOG(ERROR) << "Usage: libmv_bundle_adjuster --input=blender_problem"; + return EXIT_FAILURE; + } + + double camera_intrinsics[8]; + vector all_cameras; + vector all_points; + bool is_image_space; + vector all_markers; + + if (!ReadProblemFromFile(FLAGS_input, + camera_intrinsics, + &all_cameras, + &all_points, + &is_image_space, + &all_markers)) { + LOG(ERROR) << "Error reading problem file"; + return EXIT_FAILURE; + } + + // If there's no refine_intrinsics passed via command line + // (in this case FLAGS_refine_intrinsics will be an empty string) + // we use problem's settings to detect whether intrinsics + // shall be refined or not. + // + // Namely, if problem has got markers stored in image (pixel) + // space, we do full intrinsics refinement. If markers are + // stored in normalized space, and refine_intrinsics is not + // set, no refining will happen. + // + // Using command line argument refine_intrinsics will explicitly + // declare which intrinsics need to be refined and in this case + // refining flags does not depend on problem at all. + int bundle_intrinsics = BUNDLE_NO_INTRINSICS; + if (FLAGS_refine_intrinsics.empty()) { + if (is_image_space) { + bundle_intrinsics = BUNDLE_FOCAL_LENGTH | BUNDLE_RADIAL; + } + } else { + if (FLAGS_refine_intrinsics == "radial") { + bundle_intrinsics = BUNDLE_FOCAL_LENGTH | BUNDLE_RADIAL; + } else if (FLAGS_refine_intrinsics != "none") { + LOG(ERROR) << "Unsupported value for refine-intrinsics"; + return EXIT_FAILURE; + } + } + + // Run the bundler. + EuclideanBundleCommonIntrinsics(all_markers, + bundle_intrinsics, + BUNDLE_NO_CONSTRAINTS, + camera_intrinsics, + &all_cameras, + &all_points); + + return EXIT_SUCCESS; +} diff --git a/examples/libmv_homography.cc b/examples/libmv_homography.cc new file mode 100644 index 0000000..6e74fcd --- /dev/null +++ b/examples/libmv_homography.cc @@ -0,0 +1,414 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Copyright (c) 2014 libmv authors. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to +// deal in the Software without restriction, including without limitation the +// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or +// sell copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +// IN THE SOFTWARE. +// +// Author: sergey.vfx@gmail.com (Sergey Sharybin) +// +// This file demonstrates solving for a homography between two sets of points. +// A homography describes a transformation between a sets of points on a plane, +// perspectively projected into two images. The first step is to solve a +// homogeneous system of equations via singular value decompposition, giving an +// algebraic solution for the homography, then solving for a final solution by +// minimizing the symmetric transfer error in image space with Ceres (called the +// Gold Standard Solution in "Multiple View Geometry"). The routines are based on +// the routines from the Libmv library. +// +// This example demonstrates custom exit criterion by having a callback check +// for image-space error. + +#include "ceres/ceres.h" +#include "glog/logging.h" + +typedef Eigen::NumTraits EigenDouble; + +typedef Eigen::MatrixXd Mat; +typedef Eigen::VectorXd Vec; +typedef Eigen::Matrix Mat3; +typedef Eigen::Matrix Vec2; +typedef Eigen::Matrix MatX8; +typedef Eigen::Vector3d Vec3; + +namespace { + +// This structure contains options that controls how the homography +// estimation operates. +// +// Defaults should be suitable for a wide range of use cases, but +// better performance and accuracy might require tweaking. +struct EstimateHomographyOptions { + // Default settings for homography estimation which should be suitable + // for a wide range of use cases. + EstimateHomographyOptions() + : max_num_iterations(50), + expected_average_symmetric_distance(1e-16) {} + + // Maximal number of iterations for the refinement step. + int max_num_iterations; + + // Expected average of symmetric geometric distance between + // actual destination points and original ones transformed by + // estimated homography matrix. + // + // Refinement will finish as soon as average of symmetric + // geometric distance is less or equal to this value. + // + // This distance is measured in the same units as input points are. + double expected_average_symmetric_distance; +}; + +// Calculate symmetric geometric cost terms: +// +// forward_error = D(H * x1, x2) +// backward_error = D(H^-1 * x2, x1) +// +// Templated to be used with autodifferenciation. +template +void SymmetricGeometricDistanceTerms(const Eigen::Matrix &H, + const Eigen::Matrix &x1, + const Eigen::Matrix &x2, + T forward_error[2], + T backward_error[2]) { + typedef Eigen::Matrix Vec3; + Vec3 x(x1(0), x1(1), T(1.0)); + Vec3 y(x2(0), x2(1), T(1.0)); + + Vec3 H_x = H * x; + Vec3 Hinv_y = H.inverse() * y; + + H_x /= H_x(2); + Hinv_y /= Hinv_y(2); + + forward_error[0] = H_x(0) - y(0); + forward_error[1] = H_x(1) - y(1); + backward_error[0] = Hinv_y(0) - x(0); + backward_error[1] = Hinv_y(1) - x(1); +} + +// Calculate symmetric geometric cost: +// +// D(H * x1, x2)^2 + D(H^-1 * x2, x1)^2 +// +double SymmetricGeometricDistance(const Mat3 &H, + const Vec2 &x1, + const Vec2 &x2) { + Vec2 forward_error, backward_error; + SymmetricGeometricDistanceTerms(H, + x1, + x2, + forward_error.data(), + backward_error.data()); + return forward_error.squaredNorm() + + backward_error.squaredNorm(); +} + +// A parameterization of the 2D homography matrix that uses 8 parameters so +// that the matrix is normalized (H(2,2) == 1). +// The homography matrix H is built from a list of 8 parameters (a, b,...g, h) +// as follows +// +// |a b c| +// H = |d e f| +// |g h 1| +// +template +class Homography2DNormalizedParameterization { + public: + typedef Eigen::Matrix Parameters; // a, b, ... g, h + typedef Eigen::Matrix Parameterized; // H + + // Convert from the 8 parameters to a H matrix. + static void To(const Parameters &p, Parameterized *h) { + *h << p(0), p(1), p(2), + p(3), p(4), p(5), + p(6), p(7), 1.0; + } + + // Convert from a H matrix to the 8 parameters. + static void From(const Parameterized &h, Parameters *p) { + *p << h(0, 0), h(0, 1), h(0, 2), + h(1, 0), h(1, 1), h(1, 2), + h(2, 0), h(2, 1); + } +}; + +// 2D Homography transformation estimation in the case that points are in +// euclidean coordinates. +// +// x = H y +// +// x and y vector must have the same direction, we could write +// +// crossproduct(|x|, * H * |y| ) = |0| +// +// | 0 -1 x2| |a b c| |y1| |0| +// | 1 0 -x1| * |d e f| * |y2| = |0| +// |-x2 x1 0| |g h 1| |1 | |0| +// +// That gives: +// +// (-d+x2*g)*y1 + (-e+x2*h)*y2 + -f+x2 |0| +// (a-x1*g)*y1 + (b-x1*h)*y2 + c-x1 = |0| +// (-x2*a+x1*d)*y1 + (-x2*b+x1*e)*y2 + -x2*c+x1*f |0| +// +bool Homography2DFromCorrespondencesLinearEuc( + const Mat &x1, + const Mat &x2, + Mat3 *H, + double expected_precision) { + assert(2 == x1.rows()); + assert(4 <= x1.cols()); + assert(x1.rows() == x2.rows()); + assert(x1.cols() == x2.cols()); + + int n = x1.cols(); + MatX8 L = Mat::Zero(n * 3, 8); + Mat b = Mat::Zero(n * 3, 1); + for (int i = 0; i < n; ++i) { + int j = 3 * i; + L(j, 0) = x1(0, i); // a + L(j, 1) = x1(1, i); // b + L(j, 2) = 1.0; // c + L(j, 6) = -x2(0, i) * x1(0, i); // g + L(j, 7) = -x2(0, i) * x1(1, i); // h + b(j, 0) = x2(0, i); // i + + ++j; + L(j, 3) = x1(0, i); // d + L(j, 4) = x1(1, i); // e + L(j, 5) = 1.0; // f + L(j, 6) = -x2(1, i) * x1(0, i); // g + L(j, 7) = -x2(1, i) * x1(1, i); // h + b(j, 0) = x2(1, i); // i + + // This ensures better stability + // TODO(julien) make a lite version without this 3rd set + ++j; + L(j, 0) = x2(1, i) * x1(0, i); // a + L(j, 1) = x2(1, i) * x1(1, i); // b + L(j, 2) = x2(1, i); // c + L(j, 3) = -x2(0, i) * x1(0, i); // d + L(j, 4) = -x2(0, i) * x1(1, i); // e + L(j, 5) = -x2(0, i); // f + } + // Solve Lx=B + const Vec h = L.fullPivLu().solve(b); + Homography2DNormalizedParameterization::To(h, H); + return (L * h).isApprox(b, expected_precision); +} + +// Cost functor which computes symmetric geometric distance +// used for homography matrix refinement. +class HomographySymmetricGeometricCostFunctor { + public: + HomographySymmetricGeometricCostFunctor(const Vec2 &x, + const Vec2 &y) + : x_(x), y_(y) { } + + template + bool operator()(const T* homography_parameters, T* residuals) const { + typedef Eigen::Matrix Mat3; + typedef Eigen::Matrix Vec2; + + Mat3 H(homography_parameters); + Vec2 x(T(x_(0)), T(x_(1))); + Vec2 y(T(y_(0)), T(y_(1))); + + SymmetricGeometricDistanceTerms(H, + x, + y, + &residuals[0], + &residuals[2]); + return true; + } + + const Vec2 x_; + const Vec2 y_; +}; + +// Termination checking callback. This is needed to finish the +// optimization when an absolute error threshold is met, as opposed +// to Ceres's function_tolerance, which provides for finishing when +// successful steps reduce the cost function by a fractional amount. +// In this case, the callback checks for the absolute average reprojection +// error and terminates when it's below a threshold (for example all +// points < 0.5px error). +class TerminationCheckingCallback : public ceres::IterationCallback { + public: + TerminationCheckingCallback(const Mat &x1, const Mat &x2, + const EstimateHomographyOptions &options, + Mat3 *H) + : options_(options), x1_(x1), x2_(x2), H_(H) {} + + virtual ceres::CallbackReturnType operator()( + const ceres::IterationSummary& summary) { + // If the step wasn't successful, there's nothing to do. + if (!summary.step_is_successful) { + return ceres::SOLVER_CONTINUE; + } + + // Calculate average of symmetric geometric distance. + double average_distance = 0.0; + for (int i = 0; i < x1_.cols(); i++) { + average_distance += SymmetricGeometricDistance(*H_, + x1_.col(i), + x2_.col(i)); + } + average_distance /= x1_.cols(); + + if (average_distance <= options_.expected_average_symmetric_distance) { + return ceres::SOLVER_TERMINATE_SUCCESSFULLY; + } + + return ceres::SOLVER_CONTINUE; + } + + private: + const EstimateHomographyOptions &options_; + const Mat &x1_; + const Mat &x2_; + Mat3 *H_; +}; + +bool EstimateHomography2DFromCorrespondences( + const Mat &x1, + const Mat &x2, + const EstimateHomographyOptions &options, + Mat3 *H) { + assert(2 == x1.rows()); + assert(4 <= x1.cols()); + assert(x1.rows() == x2.rows()); + assert(x1.cols() == x2.cols()); + + // Step 1: Algebraic homography estimation. + // Assume algebraic estimation always succeeds. + Homography2DFromCorrespondencesLinearEuc(x1, + x2, + H, + EigenDouble::dummy_precision()); + + LOG(INFO) << "Estimated matrix after algebraic estimation:\n" << *H; + + // Step 2: Refine matrix using Ceres minimizer. + ceres::Problem problem; + for (int i = 0; i < x1.cols(); i++) { + HomographySymmetricGeometricCostFunctor + *homography_symmetric_geometric_cost_function = + new HomographySymmetricGeometricCostFunctor(x1.col(i), + x2.col(i)); + + problem.AddResidualBlock( + new ceres::AutoDiffCostFunction< + HomographySymmetricGeometricCostFunctor, + 4, // num_residuals + 9>(homography_symmetric_geometric_cost_function), + NULL, + H->data()); + } + + // Configure the solve. + ceres::Solver::Options solver_options; + solver_options.linear_solver_type = ceres::DENSE_QR; + solver_options.max_num_iterations = options.max_num_iterations; + solver_options.update_state_every_iteration = true; + + // Terminate if the average symmetric distance is good enough. + TerminationCheckingCallback callback(x1, x2, options, H); + solver_options.callbacks.push_back(&callback); + + // Run the solve. + ceres::Solver::Summary summary; + ceres::Solve(solver_options, &problem, &summary); + + LOG(INFO) << "Summary:\n" << summary.FullReport(); + LOG(INFO) << "Final refined matrix:\n" << *H; + + return summary.IsSolutionUsable(); +} + +} // namespace libmv + +int main(int argc, char **argv) { + google::InitGoogleLogging(argv[0]); + + Mat x1(2, 100); + for (int i = 0; i < x1.cols(); ++i) { + x1(0, i) = rand() % 1024; + x1(1, i) = rand() % 1024; + } + + Mat3 homography_matrix; + // This matrix has been dumped from a Blender test file of plane tracking. + homography_matrix << 1.243715, -0.461057, -111.964454, + 0.0, 0.617589, -192.379252, + 0.0, -0.000983, 1.0; + + Mat x2 = x1; + for (int i = 0; i < x2.cols(); ++i) { + Vec3 homogenous_x1 = Vec3(x1(0, i), x1(1, i), 1.0); + Vec3 homogenous_x2 = homography_matrix * homogenous_x1; + x2(0, i) = homogenous_x2(0) / homogenous_x2(2); + x2(1, i) = homogenous_x2(1) / homogenous_x2(2); + + // Apply some noise so algebraic estimation is not good enough. + x2(0, i) += static_cast(rand() % 1000) / 5000.0; + x2(1, i) += static_cast(rand() % 1000) / 5000.0; + } + + Mat3 estimated_matrix; + + EstimateHomographyOptions options; + options.expected_average_symmetric_distance = 0.02; + EstimateHomography2DFromCorrespondences(x1, x2, options, &estimated_matrix); + + // Normalize the matrix for easier comparison. + estimated_matrix /= estimated_matrix(2 ,2); + + std::cout << "Original matrix:\n" << homography_matrix << "\n"; + std::cout << "Estimated matrix:\n" << estimated_matrix << "\n"; + + return EXIT_SUCCESS; +} diff --git a/examples/more_garbow_hillstrom.cc b/examples/more_garbow_hillstrom.cc new file mode 100644 index 0000000..02169cd --- /dev/null +++ b/examples/more_garbow_hillstrom.cc @@ -0,0 +1,674 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Test problems from the paper +// +// Testing Unconstrained Optimization Software +// Jorge J. More, Burton S. Garbow and Kenneth E. Hillstrom +// ACM Transactions on Mathematical Software, 7(1), pp. 17-41, 1981 +// +// A subset of these problems were augmented with bounds and used for +// testing bounds constrained optimization algorithms by +// +// A Trust Region Approach to Linearly Constrained Optimization +// David M. Gay +// Numerical Analysis (Griffiths, D.F., ed.), pp. 72-105 +// Lecture Notes in Mathematics 1066, Springer Verlag, 1984. +// +// The latter paper is behind a paywall. We obtained the bounds on the +// variables and the function values at the global minimums from +// +// http://www.mat.univie.ac.at/~neum/glopt/bounds.html +// +// A problem is considered solved if of the log relative error of its +// objective function is at least 4. + + +#include +#include // NOLINT +#include // NOLINT +#include +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" + +DEFINE_string(problem, "all", "Which problem to solve"); +DEFINE_bool(use_numeric_diff, false, + "Use numeric differentiation instead of automatic " + "differentiation."); +DEFINE_string(numeric_diff_method, "ridders", "When using numeric " + "differentiation, selects algorithm. Options are: central, " + "forward, ridders."); +DEFINE_int32(ridders_extrapolations, 3, "Maximal number of extrapolations in " + "Ridders' method."); + +namespace ceres { +namespace examples { + +const double kDoubleMax = std::numeric_limits::max(); + +static void SetNumericDiffOptions(ceres::NumericDiffOptions* options) { + options->max_num_ridders_extrapolations = FLAGS_ridders_extrapolations; +} + +#define BEGIN_MGH_PROBLEM(name, num_parameters, num_residuals) \ + struct name { \ + static const int kNumParameters = num_parameters; \ + static const double initial_x[kNumParameters]; \ + static const double lower_bounds[kNumParameters]; \ + static const double upper_bounds[kNumParameters]; \ + static const double constrained_optimal_cost; \ + static const double unconstrained_optimal_cost; \ + static CostFunction* Create() { \ + if (FLAGS_use_numeric_diff) { \ + ceres::NumericDiffOptions options; \ + SetNumericDiffOptions(&options); \ + if (FLAGS_numeric_diff_method == "central") { \ + return new NumericDiffCostFunction( \ + new name, ceres::TAKE_OWNERSHIP, num_residuals, options); \ + } else if (FLAGS_numeric_diff_method == "forward") { \ + return new NumericDiffCostFunction( \ + new name, ceres::TAKE_OWNERSHIP, num_residuals, options); \ + } else if (FLAGS_numeric_diff_method == "ridders") { \ + return new NumericDiffCostFunction( \ + new name, ceres::TAKE_OWNERSHIP, num_residuals, options); \ + } else { \ + LOG(ERROR) << "Invalid numeric diff method specified"; \ + return NULL; \ + } \ + } else { \ + return new AutoDiffCostFunction(new name); \ + } \ + } \ + template \ + bool operator()(const T* const x, T* residual) const { + +#define END_MGH_PROBLEM return true; } }; // NOLINT + +// Rosenbrock function. +BEGIN_MGH_PROBLEM(TestProblem1, 2, 2) + const T x1 = x[0]; + const T x2 = x[1]; + residual[0] = 10.0 * (x2 - x1 * x1); + residual[1] = 1.0 - x1; +END_MGH_PROBLEM; + +const double TestProblem1::initial_x[] = {-1.2, 1.0}; +const double TestProblem1::lower_bounds[] = {-kDoubleMax, -kDoubleMax}; +const double TestProblem1::upper_bounds[] = {kDoubleMax, kDoubleMax}; +const double TestProblem1::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem1::unconstrained_optimal_cost = 0.0; + +// Freudenstein and Roth function. +BEGIN_MGH_PROBLEM(TestProblem2, 2, 2) + const T x1 = x[0]; + const T x2 = x[1]; + residual[0] = -13.0 + x1 + ((5.0 - x2) * x2 - 2.0) * x2; + residual[1] = -29.0 + x1 + ((x2 + 1.0) * x2 - 14.0) * x2; +END_MGH_PROBLEM; + +const double TestProblem2::initial_x[] = {0.5, -2.0}; +const double TestProblem2::lower_bounds[] = {-kDoubleMax, -kDoubleMax}; +const double TestProblem2::upper_bounds[] = {kDoubleMax, kDoubleMax}; +const double TestProblem2::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem2::unconstrained_optimal_cost = 0.0; + +// Powell badly scaled function. +BEGIN_MGH_PROBLEM(TestProblem3, 2, 2) + const T x1 = x[0]; + const T x2 = x[1]; + residual[0] = 10000.0 * x1 * x2 - 1.0; + residual[1] = exp(-x1) + exp(-x2) - 1.0001; +END_MGH_PROBLEM; + +const double TestProblem3::initial_x[] = {0.0, 1.0}; +const double TestProblem3::lower_bounds[] = {0.0, 1.0}; +const double TestProblem3::upper_bounds[] = {1.0, 9.0}; +const double TestProblem3::constrained_optimal_cost = 0.15125900e-9; +const double TestProblem3::unconstrained_optimal_cost = 0.0; + +// Brown badly scaled function. +BEGIN_MGH_PROBLEM(TestProblem4, 2, 3) + const T x1 = x[0]; + const T x2 = x[1]; + residual[0] = x1 - 1000000.0; + residual[1] = x2 - 0.000002; + residual[2] = x1 * x2 - 2.0; +END_MGH_PROBLEM; + +const double TestProblem4::initial_x[] = {1.0, 1.0}; +const double TestProblem4::lower_bounds[] = {0.0, 0.00003}; +const double TestProblem4::upper_bounds[] = {1000000.0, 100.0}; +const double TestProblem4::constrained_optimal_cost = 0.78400000e3; +const double TestProblem4::unconstrained_optimal_cost = 0.0; + +// Beale function. +BEGIN_MGH_PROBLEM(TestProblem5, 2, 3) + const T x1 = x[0]; + const T x2 = x[1]; + residual[0] = 1.5 - x1 * (1.0 - x2); + residual[1] = 2.25 - x1 * (1.0 - x2 * x2); + residual[2] = 2.625 - x1 * (1.0 - x2 * x2 * x2); +END_MGH_PROBLEM; + +const double TestProblem5::initial_x[] = {1.0, 1.0}; +const double TestProblem5::lower_bounds[] = {0.6, 0.5}; +const double TestProblem5::upper_bounds[] = {10.0, 100.0}; +const double TestProblem5::constrained_optimal_cost = 0.0; +const double TestProblem5::unconstrained_optimal_cost = 0.0; + +// Jennrich and Sampson function. +BEGIN_MGH_PROBLEM(TestProblem6, 2, 10) + const T x1 = x[0]; + const T x2 = x[1]; + for (int i = 1; i <= 10; ++i) { + residual[i - 1] = 2.0 + 2.0 * i - + (exp(static_cast(i) * x1) + + exp(static_cast(i) * x2)); + } +END_MGH_PROBLEM; + +const double TestProblem6::initial_x[] = {1.0, 1.0}; +const double TestProblem6::lower_bounds[] = {-kDoubleMax, -kDoubleMax}; +const double TestProblem6::upper_bounds[] = {kDoubleMax, kDoubleMax}; +const double TestProblem6::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem6::unconstrained_optimal_cost = 124.362; + +// Helical valley function. +BEGIN_MGH_PROBLEM(TestProblem7, 3, 3) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T theta = (0.5 / M_PI) * atan(x2 / x1) + (x1 > 0.0 ? 0.0 : 0.5); + residual[0] = 10.0 * (x3 - 10.0 * theta); + residual[1] = 10.0 * (sqrt(x1 * x1 + x2 * x2) - 1.0); + residual[2] = x3; +END_MGH_PROBLEM; + +const double TestProblem7::initial_x[] = {-1.0, 0.0, 0.0}; +const double TestProblem7::lower_bounds[] = {-100.0, -1.0, -1.0}; +const double TestProblem7::upper_bounds[] = {0.8, 1.0, 1.0}; +const double TestProblem7::constrained_optimal_cost = 0.99042212; +const double TestProblem7::unconstrained_optimal_cost = 0.0; + +// Bard function +BEGIN_MGH_PROBLEM(TestProblem8, 3, 15) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + + double y[] = {0.14, 0.18, 0.22, 0.25, + 0.29, 0.32, 0.35, 0.39, 0.37, 0.58, + 0.73, 0.96, 1.34, 2.10, 4.39}; + + for (int i = 1; i <=15; ++i) { + const double u = i; + const double v = 16 - i; + const double w = std::min(i, 16 - i); + residual[i - 1] = y[i - 1] - (x1 + u / (v * x2 + w * x3)); + } +END_MGH_PROBLEM; + +const double TestProblem8::initial_x[] = {1.0, 1.0, 1.0}; +const double TestProblem8::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem8::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem8::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem8::unconstrained_optimal_cost = 8.21487e-3; + +// Gaussian function. +BEGIN_MGH_PROBLEM(TestProblem9, 3, 15) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + + const double y[] = {0.0009, 0.0044, 0.0175, 0.0540, 0.1295, 0.2420, 0.3521, + 0.3989, + 0.3521, 0.2420, 0.1295, 0.0540, 0.0175, 0.0044, 0.0009}; + for (int i = 0; i < 15; ++i) { + const double t_i = (8.0 - i - 1.0) / 2.0; + residual[i] = x1 * exp(-x2 * (t_i - x3) * (t_i - x3) / 2.0) - y[i]; + } +END_MGH_PROBLEM; + +const double TestProblem9::initial_x[] = {0.4, 1.0, 0.0}; +const double TestProblem9::lower_bounds[] = {0.398, 1.0, -0.5}; +const double TestProblem9::upper_bounds[] = {4.2, 2.0, 0.1}; +const double TestProblem9::constrained_optimal_cost = 0.11279300e-7; +const double TestProblem9::unconstrained_optimal_cost = 0.112793e-7; + +// Meyer function. +BEGIN_MGH_PROBLEM(TestProblem10, 3, 16) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + + const double y[] = {34780, 28610, 23650, 19630, 16370, 13720, 11540, 9744, + 8261, 7030, 6005, 5147, 4427, 3820, 3307, 2872}; + + for (int i = 0; i < 16; ++i) { + const double ti = 45.0 + 5.0 * (i + 1); + residual[i] = x1 * exp(x2 / (ti + x3)) - y[i]; + } +END_MGH_PROBLEM + +const double TestProblem10::initial_x[] = {0.02, 4000, 250}; +const double TestProblem10::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem10::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem10::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem10::unconstrained_optimal_cost = 87.9458; + +// Gulf research and development function +BEGIN_MGH_PROBLEM(TestProblem11, 3, 100) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + for (int i = 1; i <= 100; ++i) { + const double ti = i / 100.0; + const double yi = 25.0 + pow(-50.0 * log(ti), 2.0 / 3.0); + residual[i - 1] = exp(-pow(abs((yi * 100.0 * i) * x2), x3) / x1) - ti; + } +END_MGH_PROBLEM + +const double TestProblem11::initial_x[] = {5.0, 2.5, 0.15}; +const double TestProblem11::lower_bounds[] = {1e-16, 0.0, 0.0}; +const double TestProblem11::upper_bounds[] = {10.0, 10.0, 10.0}; +const double TestProblem11::constrained_optimal_cost = 0.58281431e-4; +const double TestProblem11::unconstrained_optimal_cost = 0.0; + +// Box three-dimensional function. +BEGIN_MGH_PROBLEM(TestProblem12, 3, 3) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + + const double t1 = 0.1; + const double t2 = 0.2; + const double t3 = 0.3; + + residual[0] = exp(-t1 * x1) - exp(-t1 * x2) - x3 * (exp(-t1) - exp(-10.0 * t1)); + residual[1] = exp(-t2 * x1) - exp(-t2 * x2) - x3 * (exp(-t2) - exp(-10.0 * t2)); + residual[2] = exp(-t3 * x1) - exp(-t3 * x2) - x3 * (exp(-t3) - exp(-10.0 * t3)); +END_MGH_PROBLEM + +const double TestProblem12::initial_x[] = {0.0, 10.0, 20.0}; +const double TestProblem12::lower_bounds[] = {0.0, 5.0, 0.0}; +const double TestProblem12::upper_bounds[] = {2.0, 9.5, 20.0}; +const double TestProblem12::constrained_optimal_cost = 0.30998153e-5; +const double TestProblem12::unconstrained_optimal_cost = 0.0; + +// Powell Singular function. +BEGIN_MGH_PROBLEM(TestProblem13, 4, 4) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + + residual[0] = x1 + 10.0 * x2; + residual[1] = sqrt(5.0) * (x3 - x4); + residual[2] = (x2 - 2.0 * x3) * (x2 - 2.0 * x3); + residual[3] = sqrt(10.0) * (x1 - x4) * (x1 - x4); +END_MGH_PROBLEM + +const double TestProblem13::initial_x[] = {3.0, -1.0, 0.0, 1.0}; +const double TestProblem13::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem13::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem13::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem13::unconstrained_optimal_cost = 0.0; + +// Wood function. +BEGIN_MGH_PROBLEM(TestProblem14, 4, 6) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + + residual[0] = 10.0 * (x2 - x1 * x1); + residual[1] = 1.0 - x1; + residual[2] = sqrt(90.0) * (x4 - x3 * x3); + residual[3] = 1.0 - x3; + residual[4] = sqrt(10.0) * (x2 + x4 - 2.0); + residual[5] = 1.0 / sqrt(10.0) * (x2 - x4); +END_MGH_PROBLEM; + + const double TestProblem14::initial_x[] = {-3.0, -1.0, -3.0, -1.0}; + const double TestProblem14::lower_bounds[] = {-100.0, -100.0, -100.0, -100.0}; + const double TestProblem14::upper_bounds[] = {0.0, 10.0, 100.0, 100.0}; + const double TestProblem14::constrained_optimal_cost = 0.15567008e1; + const double TestProblem14::unconstrained_optimal_cost = 0.0; + + // Kowalik and Osborne function. + BEGIN_MGH_PROBLEM(TestProblem15, 4, 11) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + + const double y[] = {0.1957, 0.1947, 0.1735, 0.1600, 0.0844, 0.0627, + 0.0456, 0.0342, 0.0323, 0.0235, 0.0246}; + const double u[] = {4.0, 2.0, 1.0, 0.5, 0.25, 0.167, 0.125, 0.1, + 0.0833, 0.0714, 0.0625}; + + for (int i = 0; i < 11; ++i) { + residual[i] = y[i] - x1 * (u[i] * u[i] + u[i] * x2) / + (u[i] * u[i] + u[i] * x3 + x4); + } +END_MGH_PROBLEM; + +const double TestProblem15::initial_x[] = {0.25, 0.39, 0.415, 0.39}; +const double TestProblem15::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem15::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem15::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem15::unconstrained_optimal_cost = 3.07505e-4; + +// Brown and Dennis function. +BEGIN_MGH_PROBLEM(TestProblem16, 4, 20) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + + for (int i = 0; i < 20; ++i) { + const double ti = (i + 1) / 5.0; + residual[i] = (x1 + ti * x2 - exp(ti)) * (x1 + ti * x2 - exp(ti)) + + (x3 + x4 * sin(ti) - cos(ti)) * (x3 + x4 * sin(ti) - cos(ti)); + } +END_MGH_PROBLEM; + +const double TestProblem16::initial_x[] = {25.0, 5.0, -5.0, -1.0}; +const double TestProblem16::lower_bounds[] = {-10.0, 0.0, -100.0, -20.0}; +const double TestProblem16::upper_bounds[] = {100.0, 15.0, 0.0, 0.2}; +const double TestProblem16::constrained_optimal_cost = 0.88860479e5; +const double TestProblem16::unconstrained_optimal_cost = 85822.2; + +// Osborne 1 function. +BEGIN_MGH_PROBLEM(TestProblem17, 5, 33) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + const T x5 = x[4]; + + const double y[] = {0.844, 0.908, 0.932, 0.936, 0.925, 0.908, 0.881, 0.850, 0.818, + 0.784, 0.751, 0.718, 0.685, 0.658, 0.628, 0.603, 0.580, 0.558, + 0.538, 0.522, 0.506, 0.490, 0.478, 0.467, 0.457, 0.448, 0.438, + 0.431, 0.424, 0.420, 0.414, 0.411, 0.406}; + + for (int i = 0; i < 33; ++i) { + const double ti = 10.0 * i; + residual[i] = y[i] - (x1 + x2 * exp(-ti * x4) + x3 * exp(-ti * x5)); + } +END_MGH_PROBLEM; + +const double TestProblem17::initial_x[] = {0.5, 1.5, -1.0, 0.01, 0.02}; +const double TestProblem17::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem17::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem17::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem17::unconstrained_optimal_cost = 5.46489e-5; + +// Biggs EXP6 function. +BEGIN_MGH_PROBLEM(TestProblem18, 6, 13) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + const T x5 = x[4]; + const T x6 = x[5]; + + for (int i = 0; i < 13; ++i) { + const double ti = 0.1 * (i + 1.0); + const double yi = exp(-ti) - 5.0 * exp(-10.0 * ti) + 3.0 * exp(-4.0 * ti); + residual[i] = + x3 * exp(-ti * x1) - x4 * exp(-ti * x2) + x6 * exp(-ti * x5) - yi; + } + END_MGH_PROBLEM + + const double TestProblem18::initial_x[] = {1.0, 2.0, 1.0, 1.0, 1.0, 1.0}; + const double TestProblem18::lower_bounds[] = {0.0, 0.0, 0.0, 1.0, 0.0, 0.0}; + const double TestProblem18::upper_bounds[] = {2.0, 8.0, 1.0, 7.0, 5.0, 5.0}; + const double TestProblem18::constrained_optimal_cost = 0.53209865e-3; + const double TestProblem18::unconstrained_optimal_cost = 0.0; + + // Osborne 2 function. + BEGIN_MGH_PROBLEM(TestProblem19, 11, 65) + const T x1 = x[0]; + const T x2 = x[1]; + const T x3 = x[2]; + const T x4 = x[3]; + const T x5 = x[4]; + const T x6 = x[5]; + const T x7 = x[6]; + const T x8 = x[7]; + const T x9 = x[8]; + const T x10 = x[9]; + const T x11 = x[10]; + + const double y[] = {1.366, 1.191, 1.112, 1.013, 0.991, + 0.885, 0.831, 0.847, 0.786, 0.725, + 0.746, 0.679, 0.608, 0.655, 0.616, + 0.606, 0.602, 0.626, 0.651, 0.724, + 0.649, 0.649, 0.694, 0.644, 0.624, + 0.661, 0.612, 0.558, 0.533, 0.495, + 0.500, 0.423, 0.395, 0.375, 0.372, + 0.391, 0.396, 0.405, 0.428, 0.429, + 0.523, 0.562, 0.607, 0.653, 0.672, + 0.708, 0.633, 0.668, 0.645, 0.632, + 0.591, 0.559, 0.597, 0.625, 0.739, + 0.710, 0.729, 0.720, 0.636, 0.581, + 0.428, 0.292, 0.162, 0.098, 0.054}; + + for (int i = 0; i < 65; ++i) { + const double ti = i / 10.0; + residual[i] = y[i] - (x1 * exp(-(ti * x5)) + + x2 * exp(-(ti - x9) * (ti - x9) * x6) + + x3 * exp(-(ti - x10) * (ti - x10) * x7) + + x4 * exp(-(ti - x11) * (ti - x11) * x8)); + } +END_MGH_PROBLEM; + +const double TestProblem19::initial_x[] = {1.3, 0.65, 0.65, 0.7, 0.6, + 3.0, 5.0, 7.0, 2.0, 4.5, 5.5}; +const double TestProblem19::lower_bounds[] = { + -kDoubleMax, -kDoubleMax, -kDoubleMax, -kDoubleMax}; +const double TestProblem19::upper_bounds[] = { + kDoubleMax, kDoubleMax, kDoubleMax, kDoubleMax}; +const double TestProblem19::constrained_optimal_cost = + std::numeric_limits::quiet_NaN(); +const double TestProblem19::unconstrained_optimal_cost = 4.01377e-2; + + +#undef BEGIN_MGH_PROBLEM +#undef END_MGH_PROBLEM + +template bool Solve(bool is_constrained, int trial) { + double x[TestProblem::kNumParameters]; + for (int i = 0; i < TestProblem::kNumParameters; ++i) { + x[i] = pow(10, trial) * TestProblem::initial_x[i]; + } + + Problem problem; + problem.AddResidualBlock(TestProblem::Create(), NULL, x); + double optimal_cost = TestProblem::unconstrained_optimal_cost; + + if (is_constrained) { + for (int i = 0; i < TestProblem::kNumParameters; ++i) { + problem.SetParameterLowerBound(x, i, TestProblem::lower_bounds[i]); + problem.SetParameterUpperBound(x, i, TestProblem::upper_bounds[i]); + } + optimal_cost = TestProblem::constrained_optimal_cost; + } + + Solver::Options options; + options.parameter_tolerance = 1e-18; + options.function_tolerance = 1e-18; + options.gradient_tolerance = 1e-18; + options.max_num_iterations = 1000; + options.linear_solver_type = DENSE_QR; + Solver::Summary summary; + Solve(options, &problem, &summary); + + const double kMinLogRelativeError = 4.0; + const double log_relative_error = -std::log10( + std::abs(2.0 * summary.final_cost - optimal_cost) / + (optimal_cost > 0.0 ? optimal_cost : 1.0)); + + const bool success = log_relative_error >= kMinLogRelativeError; + LOG(INFO) << "Expected : " << optimal_cost + << " actual: " << 2.0 * summary.final_cost + << " " << success + << " in " << summary.total_time_in_seconds + << " seconds"; + return success; +} + +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + + using ceres::examples::Solve; + + int unconstrained_problems = 0; + int unconstrained_successes = 0; + int constrained_problems = 0; + int constrained_successes = 0; + std::stringstream ss; + +#define UNCONSTRAINED_SOLVE(n) \ + ss << "Unconstrained Problem " << n << " : "; \ + if (FLAGS_problem == #n || FLAGS_problem == "all") { \ + unconstrained_problems += 3; \ + if (Solve(false, 0)) { \ + unconstrained_successes += 1; \ + ss << "Yes "; \ + } else { \ + ss << "No "; \ + } \ + if (Solve(false, 1)) { \ + unconstrained_successes += 1; \ + ss << "Yes "; \ + } else { \ + ss << "No "; \ + } \ + if (Solve(false, 2)) { \ + unconstrained_successes += 1; \ + ss << "Yes "; \ + } else { \ + ss << "No "; \ + } \ + } \ + ss << std::endl; + + UNCONSTRAINED_SOLVE(1); + UNCONSTRAINED_SOLVE(2); + UNCONSTRAINED_SOLVE(3); + UNCONSTRAINED_SOLVE(4); + UNCONSTRAINED_SOLVE(5); + UNCONSTRAINED_SOLVE(6); + UNCONSTRAINED_SOLVE(7); + UNCONSTRAINED_SOLVE(8); + UNCONSTRAINED_SOLVE(9); + UNCONSTRAINED_SOLVE(10); + UNCONSTRAINED_SOLVE(11); + UNCONSTRAINED_SOLVE(12); + UNCONSTRAINED_SOLVE(13); + UNCONSTRAINED_SOLVE(14); + UNCONSTRAINED_SOLVE(15); + UNCONSTRAINED_SOLVE(16); + UNCONSTRAINED_SOLVE(17); + UNCONSTRAINED_SOLVE(18); + UNCONSTRAINED_SOLVE(19); + + ss << "Unconstrained : " + << unconstrained_successes + << "/" + << unconstrained_problems << std::endl; + +#define CONSTRAINED_SOLVE(n) \ + ss << "Constrained Problem " << n << " : "; \ + if (FLAGS_problem == #n || FLAGS_problem == "all") { \ + constrained_problems += 1; \ + if (Solve(true, 0)) { \ + constrained_successes += 1; \ + ss << "Yes "; \ + } else { \ + ss << "No "; \ + } \ + } \ + ss << std::endl; + + CONSTRAINED_SOLVE(3); + CONSTRAINED_SOLVE(4); + CONSTRAINED_SOLVE(5); + CONSTRAINED_SOLVE(7); + CONSTRAINED_SOLVE(9); + CONSTRAINED_SOLVE(11); + CONSTRAINED_SOLVE(12); + CONSTRAINED_SOLVE(14); + CONSTRAINED_SOLVE(16); + CONSTRAINED_SOLVE(18); + ss << "Constrained : " + << constrained_successes + << "/" + << constrained_problems << std::endl; + + std::cout << ss.str(); + return 0; +} diff --git a/examples/nist.cc b/examples/nist.cc new file mode 100644 index 0000000..55a3c7c --- /dev/null +++ b/examples/nist.cc @@ -0,0 +1,646 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// The National Institute of Standards and Technology has released a +// set of problems to test non-linear least squares solvers. +// +// More information about the background on these problems and +// suggested evaluation methodology can be found at: +// +// http://www.itl.nist.gov/div898/strd/nls/nls_info.shtml +// +// The problem data themselves can be found at +// +// http://www.itl.nist.gov/div898/strd/nls/nls_main.shtml +// +// The problems are divided into three levels of difficulty, Easy, +// Medium and Hard. For each problem there are two starting guesses, +// the first one far away from the global minimum and the second +// closer to it. +// +// A problem is considered successfully solved, if every components of +// the solution matches the globally optimal solution in at least 4 +// digits or more. +// +// This dataset was used for an evaluation of Non-linear least squares +// solvers: +// +// P. F. Mondragon & B. Borchers, A Comparison of Nonlinear Regression +// Codes, Journal of Modern Applied Statistical Methods, 4(1):343-351, +// 2005. +// +// The results from Mondragon & Borchers can be summarized as +// Excel Gnuplot GaussFit HBN MinPack +// Average LRE 2.3 4.3 4.0 6.8 4.4 +// Winner 1 5 12 29 12 +// +// Where the row Winner counts, the number of problems for which the +// solver had the highest LRE. + +// In this file, we implement the same evaluation methodology using +// Ceres. Currently using Levenberg-Marquardt with DENSE_QR, we get +// +// Excel Gnuplot GaussFit HBN MinPack Ceres +// Average LRE 2.3 4.3 4.0 6.8 4.4 9.4 +// Winner 0 0 5 11 2 41 + +#include +#include +#include +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "Eigen/Core" + +DEFINE_string(nist_data_dir, "", "Directory containing the NIST non-linear" + "regression examples"); +DEFINE_string(minimizer, "trust_region", + "Minimizer type to use, choices are: line_search & trust_region"); +DEFINE_string(trust_region_strategy, "levenberg_marquardt", + "Options are: levenberg_marquardt, dogleg"); +DEFINE_string(dogleg, "traditional_dogleg", + "Options are: traditional_dogleg, subspace_dogleg"); +DEFINE_string(linear_solver, "dense_qr", "Options are: " + "sparse_cholesky, dense_qr, dense_normal_cholesky and" + "cgnr"); +DEFINE_string(preconditioner, "jacobi", "Options are: " + "identity, jacobi"); +DEFINE_string(line_search, "wolfe", + "Line search algorithm to use, choices are: armijo and wolfe."); +DEFINE_string(line_search_direction, "lbfgs", + "Line search direction algorithm to use, choices: lbfgs, bfgs"); +DEFINE_int32(max_line_search_iterations, 20, + "Maximum number of iterations for each line search."); +DEFINE_int32(max_line_search_restarts, 10, + "Maximum number of restarts of line search direction algorithm."); +DEFINE_string(line_search_interpolation, "cubic", + "Degree of polynomial aproximation in line search, " + "choices are: bisection, quadratic & cubic."); +DEFINE_int32(lbfgs_rank, 20, + "Rank of L-BFGS inverse Hessian approximation in line search."); +DEFINE_bool(approximate_eigenvalue_bfgs_scaling, false, + "Use approximate eigenvalue scaling in (L)BFGS line search."); +DEFINE_double(sufficient_decrease, 1.0e-4, + "Line search Armijo sufficient (function) decrease factor."); +DEFINE_double(sufficient_curvature_decrease, 0.9, + "Line search Wolfe sufficient curvature decrease factor."); +DEFINE_int32(num_iterations, 10000, "Number of iterations"); +DEFINE_bool(nonmonotonic_steps, false, "Trust region algorithm can use" + " nonmonotic steps"); +DEFINE_double(initial_trust_region_radius, 1e4, "Initial trust region radius"); +DEFINE_bool(use_numeric_diff, false, + "Use numeric differentiation instead of automatic " + "differentiation."); +DEFINE_string(numeric_diff_method, "ridders", "When using numeric " + "differentiation, selects algorithm. Options are: central, " + "forward, ridders."); +DEFINE_double(ridders_step_size, 1e-9, "Initial step size for Ridders " + "numeric differentiation."); +DEFINE_int32(ridders_extrapolations, 3, "Maximal number of Ridders " + "extrapolations."); + +namespace ceres { +namespace examples { + +using Eigen::Dynamic; +using Eigen::RowMajor; +typedef Eigen::Matrix Vector; +typedef Eigen::Matrix Matrix; + +using std::atof; +using std::atoi; +using std::cout; +using std::ifstream; +using std::string; +using std::vector; + +void SplitStringUsingChar(const string& full, + const char delim, + vector* result) { + std::back_insert_iterator< vector > it(*result); + + const char* p = full.data(); + const char* end = p + full.size(); + while (p != end) { + if (*p == delim) { + ++p; + } else { + const char* start = p; + while (++p != end && *p != delim) { + // Skip to the next occurence of the delimiter. + } + *it++ = string(start, p - start); + } + } +} + +bool GetAndSplitLine(ifstream& ifs, vector* pieces) { + pieces->clear(); + char buf[256]; + ifs.getline(buf, 256); + SplitStringUsingChar(string(buf), ' ', pieces); + return true; +} + +void SkipLines(ifstream& ifs, int num_lines) { + char buf[256]; + for (int i = 0; i < num_lines; ++i) { + ifs.getline(buf, 256); + } +} + +class NISTProblem { + public: + explicit NISTProblem(const string& filename) { + ifstream ifs(filename.c_str(), ifstream::in); + CHECK(ifs) << "Unable to open : " << filename; + + vector pieces; + SkipLines(ifs, 24); + GetAndSplitLine(ifs, &pieces); + const int kNumResponses = atoi(pieces[1].c_str()); + + GetAndSplitLine(ifs, &pieces); + const int kNumPredictors = atoi(pieces[0].c_str()); + + GetAndSplitLine(ifs, &pieces); + const int kNumObservations = atoi(pieces[0].c_str()); + + SkipLines(ifs, 4); + GetAndSplitLine(ifs, &pieces); + const int kNumParameters = atoi(pieces[0].c_str()); + SkipLines(ifs, 8); + + // Get the first line of initial and final parameter values to + // determine the number of tries. + GetAndSplitLine(ifs, &pieces); + const int kNumTries = pieces.size() - 4; + + predictor_.resize(kNumObservations, kNumPredictors); + response_.resize(kNumObservations, kNumResponses); + initial_parameters_.resize(kNumTries, kNumParameters); + final_parameters_.resize(1, kNumParameters); + + // Parse the line for parameter b1. + int parameter_id = 0; + for (int i = 0; i < kNumTries; ++i) { + initial_parameters_(i, parameter_id) = atof(pieces[i + 2].c_str()); + } + final_parameters_(0, parameter_id) = atof(pieces[2 + kNumTries].c_str()); + + // Parse the remaining parameter lines. + for (int parameter_id = 1; parameter_id < kNumParameters; ++parameter_id) { + GetAndSplitLine(ifs, &pieces); + // b2, b3, .... + for (int i = 0; i < kNumTries; ++i) { + initial_parameters_(i, parameter_id) = atof(pieces[i + 2].c_str()); + } + final_parameters_(0, parameter_id) = atof(pieces[2 + kNumTries].c_str()); + } + + // Certfied cost + SkipLines(ifs, 1); + GetAndSplitLine(ifs, &pieces); + certified_cost_ = atof(pieces[4].c_str()) / 2.0; + + // Read the observations. + SkipLines(ifs, 18 - kNumParameters); + for (int i = 0; i < kNumObservations; ++i) { + GetAndSplitLine(ifs, &pieces); + // Response. + for (int j = 0; j < kNumResponses; ++j) { + response_(i, j) = atof(pieces[j].c_str()); + } + + // Predictor variables. + for (int j = 0; j < kNumPredictors; ++j) { + predictor_(i, j) = atof(pieces[j + kNumResponses].c_str()); + } + } + } + + Matrix initial_parameters(int start) const { return initial_parameters_.row(start); } // NOLINT + Matrix final_parameters() const { return final_parameters_; } + Matrix predictor() const { return predictor_; } + Matrix response() const { return response_; } + int predictor_size() const { return predictor_.cols(); } + int num_observations() const { return predictor_.rows(); } + int response_size() const { return response_.cols(); } + int num_parameters() const { return initial_parameters_.cols(); } + int num_starts() const { return initial_parameters_.rows(); } + double certified_cost() const { return certified_cost_; } + + private: + Matrix predictor_; + Matrix response_; + Matrix initial_parameters_; + Matrix final_parameters_; + double certified_cost_; +}; + +#define NIST_BEGIN(CostFunctionName) \ + struct CostFunctionName { \ + CostFunctionName(const double* const x, \ + const double* const y) \ + : x_(*x), y_(*y) {} \ + double x_; \ + double y_; \ + template \ + bool operator()(const T* const b, T* residual) const { \ + const T y(y_); \ + const T x(x_); \ + residual[0] = y - ( + +#define NIST_END ); return true; }}; + +// y = b1 * (b2+x)**(-1/b3) + e +NIST_BEGIN(Bennet5) + b[0] * pow(b[1] + x, -1.0 / b[2]) +NIST_END + +// y = b1*(1-exp[-b2*x]) + e +NIST_BEGIN(BoxBOD) + b[0] * (1.0 - exp(-b[1] * x)) +NIST_END + +// y = exp[-b1*x]/(b2+b3*x) + e +NIST_BEGIN(Chwirut) + exp(-b[0] * x) / (b[1] + b[2] * x) +NIST_END + +// y = b1*x**b2 + e +NIST_BEGIN(DanWood) + b[0] * pow(x, b[1]) +NIST_END + +// y = b1*exp( -b2*x ) + b3*exp( -(x-b4)**2 / b5**2 ) +// + b6*exp( -(x-b7)**2 / b8**2 ) + e +NIST_BEGIN(Gauss) + b[0] * exp(-b[1] * x) + + b[2] * exp(-pow((x - b[3])/b[4], 2)) + + b[5] * exp(-pow((x - b[6])/b[7], 2)) +NIST_END + +// y = b1*exp(-b2*x) + b3*exp(-b4*x) + b5*exp(-b6*x) + e +NIST_BEGIN(Lanczos) + b[0] * exp(-b[1] * x) + b[2] * exp(-b[3] * x) + b[4] * exp(-b[5] * x) +NIST_END + +// y = (b1+b2*x+b3*x**2+b4*x**3) / +// (1+b5*x+b6*x**2+b7*x**3) + e +NIST_BEGIN(Hahn1) + (b[0] + b[1] * x + b[2] * x * x + b[3] * x * x * x) / + (1.0 + b[4] * x + b[5] * x * x + b[6] * x * x * x) +NIST_END + +// y = (b1 + b2*x + b3*x**2) / +// (1 + b4*x + b5*x**2) + e +NIST_BEGIN(Kirby2) + (b[0] + b[1] * x + b[2] * x * x) / + (1.0 + b[3] * x + b[4] * x * x) +NIST_END + +// y = b1*(x**2+x*b2) / (x**2+x*b3+b4) + e +NIST_BEGIN(MGH09) + b[0] * (x * x + x * b[1]) / (x * x + x * b[2] + b[3]) +NIST_END + +// y = b1 * exp[b2/(x+b3)] + e +NIST_BEGIN(MGH10) + b[0] * exp(b[1] / (x + b[2])) +NIST_END + +// y = b1 + b2*exp[-x*b4] + b3*exp[-x*b5] +NIST_BEGIN(MGH17) + b[0] + b[1] * exp(-x * b[3]) + b[2] * exp(-x * b[4]) +NIST_END + +// y = b1*(1-exp[-b2*x]) + e +NIST_BEGIN(Misra1a) + b[0] * (1.0 - exp(-b[1] * x)) +NIST_END + +// y = b1 * (1-(1+b2*x/2)**(-2)) + e +NIST_BEGIN(Misra1b) + b[0] * (1.0 - 1.0/ ((1.0 + b[1] * x / 2.0) * (1.0 + b[1] * x / 2.0))) // NOLINT +NIST_END + +// y = b1 * (1-(1+2*b2*x)**(-.5)) + e +NIST_BEGIN(Misra1c) + b[0] * (1.0 - pow(1.0 + 2.0 * b[1] * x, -0.5)) +NIST_END + +// y = b1*b2*x*((1+b2*x)**(-1)) + e +NIST_BEGIN(Misra1d) + b[0] * b[1] * x / (1.0 + b[1] * x) +NIST_END + +const double kPi = 3.141592653589793238462643383279; +// pi = 3.141592653589793238462643383279E0 +// y = b1 - b2*x - arctan[b3/(x-b4)]/pi + e +NIST_BEGIN(Roszman1) + b[0] - b[1] * x - atan2(b[2], (x - b[3])) / kPi +NIST_END + +// y = b1 / (1+exp[b2-b3*x]) + e +NIST_BEGIN(Rat42) + b[0] / (1.0 + exp(b[1] - b[2] * x)) +NIST_END + +// y = b1 / ((1+exp[b2-b3*x])**(1/b4)) + e +NIST_BEGIN(Rat43) + b[0] / pow(1.0 + exp(b[1] - b[2] * x), 1.0 / b[3]) +NIST_END + +// y = (b1 + b2*x + b3*x**2 + b4*x**3) / +// (1 + b5*x + b6*x**2 + b7*x**3) + e +NIST_BEGIN(Thurber) + (b[0] + b[1] * x + b[2] * x * x + b[3] * x * x * x) / + (1.0 + b[4] * x + b[5] * x * x + b[6] * x * x * x) +NIST_END + +// y = b1 + b2*cos( 2*pi*x/12 ) + b3*sin( 2*pi*x/12 ) +// + b5*cos( 2*pi*x/b4 ) + b6*sin( 2*pi*x/b4 ) +// + b8*cos( 2*pi*x/b7 ) + b9*sin( 2*pi*x/b7 ) + e +NIST_BEGIN(ENSO) + b[0] + b[1] * cos(2.0 * kPi * x / 12.0) + + b[2] * sin(2.0 * kPi * x / 12.0) + + b[4] * cos(2.0 * kPi * x / b[3]) + + b[5] * sin(2.0 * kPi * x / b[3]) + + b[7] * cos(2.0 * kPi * x / b[6]) + + b[8] * sin(2.0 * kPi * x / b[6]) +NIST_END + +// y = (b1/b2) * exp[-0.5*((x-b3)/b2)**2] + e +NIST_BEGIN(Eckerle4) + b[0] / b[1] * exp(-0.5 * pow((x - b[2])/b[1], 2)) +NIST_END + +struct Nelson { + public: + Nelson(const double* const x, const double* const y) + : x1_(x[0]), x2_(x[1]), y_(y[0]) {} + + template + bool operator()(const T* const b, T* residual) const { + // log[y] = b1 - b2*x1 * exp[-b3*x2] + e + residual[0] = log(y_) - (b[0] - b[1] * x1_ * exp(-b[2] * x2_)); + return true; + } + + private: + double x1_; + double x2_; + double y_; +}; + +static void SetNumericDiffOptions(ceres::NumericDiffOptions* options) { + options->max_num_ridders_extrapolations = FLAGS_ridders_extrapolations; + options->ridders_relative_initial_step_size = FLAGS_ridders_step_size; +} + +string JoinPath(const string& dirname, const string& basename) { +#ifdef _WIN32 + static const char separator = '\\'; +#else + static const char separator = '/'; +#endif // _WIN32 + + if ((!basename.empty() && basename[0] == separator) || dirname.empty()) { + return basename; + } else if (dirname[dirname.size() - 1] == separator) { + return dirname + basename; + } else { + return dirname + string(&separator, 1) + basename; + } +} + +template +int RegressionDriver(const string& filename, + const ceres::Solver::Options& options) { + NISTProblem nist_problem(JoinPath(FLAGS_nist_data_dir, filename)); + CHECK_EQ(num_residuals, nist_problem.response_size()); + CHECK_EQ(num_parameters, nist_problem.num_parameters()); + + Matrix predictor = nist_problem.predictor(); + Matrix response = nist_problem.response(); + Matrix final_parameters = nist_problem.final_parameters(); + + printf("%s\n", filename.c_str()); + + // Each NIST problem comes with multiple starting points, so we + // construct the problem from scratch for each case and solve it. + int num_success = 0; + for (int start = 0; start < nist_problem.num_starts(); ++start) { + Matrix initial_parameters = nist_problem.initial_parameters(start); + + ceres::Problem problem; + for (int i = 0; i < nist_problem.num_observations(); ++i) { + Model* model = new Model( + predictor.data() + nist_problem.predictor_size() * i, + response.data() + nist_problem.response_size() * i); + ceres::CostFunction* cost_function = NULL; + if (FLAGS_use_numeric_diff) { + ceres::NumericDiffOptions options; + SetNumericDiffOptions(&options); + if (FLAGS_numeric_diff_method == "central") { + cost_function = new NumericDiffCostFunction( + model, ceres::TAKE_OWNERSHIP, num_residuals, options); + } else if (FLAGS_numeric_diff_method == "forward") { + cost_function = new NumericDiffCostFunction( + model, ceres::TAKE_OWNERSHIP, num_residuals, options); + } else if (FLAGS_numeric_diff_method == "ridders") { + cost_function = new NumericDiffCostFunction( + model, ceres::TAKE_OWNERSHIP, num_residuals, options); + } else { + LOG(ERROR) << "Invalid numeric diff method specified"; + return 0; + } + } else { + cost_function = + new ceres::AutoDiffCostFunction(model); + } + + problem.AddResidualBlock(cost_function, + NULL, + initial_parameters.data()); + } + + ceres::Solver::Summary summary; + Solve(options, &problem, &summary); + + // Compute the LRE by comparing each component of the solution + // with the ground truth, and taking the minimum. + Matrix final_parameters = nist_problem.final_parameters(); + const double kMaxNumSignificantDigits = 11; + double log_relative_error = kMaxNumSignificantDigits + 1; + for (int i = 0; i < num_parameters; ++i) { + const double tmp_lre = + -std::log10(std::fabs(final_parameters(i) - initial_parameters(i)) / + std::fabs(final_parameters(i))); + // The maximum LRE is capped at 11 - the precision at which the + // ground truth is known. + // + // The minimum LRE is capped at 0 - no digits match between the + // computed solution and the ground truth. + log_relative_error = + std::min(log_relative_error, + std::max(0.0, std::min(kMaxNumSignificantDigits, tmp_lre))); + } + + const int kMinNumMatchingDigits = 4; + if (log_relative_error > kMinNumMatchingDigits) { + ++num_success; + } + + printf("start: %d status: %s lre: %4.1f initial cost: %e final cost:%e " + "certified cost: %e total iterations: %d\n", + start + 1, + log_relative_error < kMinNumMatchingDigits ? "FAILURE" : "SUCCESS", + log_relative_error, + summary.initial_cost, + summary.final_cost, + nist_problem.certified_cost(), + (summary.num_successful_steps + summary.num_unsuccessful_steps)); + } + return num_success; +} + +void SetMinimizerOptions(ceres::Solver::Options* options) { + CHECK(ceres::StringToMinimizerType(FLAGS_minimizer, + &options->minimizer_type)); + CHECK(ceres::StringToLinearSolverType(FLAGS_linear_solver, + &options->linear_solver_type)); + CHECK(ceres::StringToPreconditionerType(FLAGS_preconditioner, + &options->preconditioner_type)); + CHECK(ceres::StringToTrustRegionStrategyType( + FLAGS_trust_region_strategy, + &options->trust_region_strategy_type)); + CHECK(ceres::StringToDoglegType(FLAGS_dogleg, &options->dogleg_type)); + CHECK(ceres::StringToLineSearchDirectionType( + FLAGS_line_search_direction, + &options->line_search_direction_type)); + CHECK(ceres::StringToLineSearchType(FLAGS_line_search, + &options->line_search_type)); + CHECK(ceres::StringToLineSearchInterpolationType( + FLAGS_line_search_interpolation, + &options->line_search_interpolation_type)); + + options->max_num_iterations = FLAGS_num_iterations; + options->use_nonmonotonic_steps = FLAGS_nonmonotonic_steps; + options->initial_trust_region_radius = FLAGS_initial_trust_region_radius; + options->max_lbfgs_rank = FLAGS_lbfgs_rank; + options->line_search_sufficient_function_decrease = FLAGS_sufficient_decrease; + options->line_search_sufficient_curvature_decrease = + FLAGS_sufficient_curvature_decrease; + options->max_num_line_search_step_size_iterations = + FLAGS_max_line_search_iterations; + options->max_num_line_search_direction_restarts = + FLAGS_max_line_search_restarts; + options->use_approximate_eigenvalue_bfgs_scaling = + FLAGS_approximate_eigenvalue_bfgs_scaling; + options->function_tolerance = std::numeric_limits::epsilon(); + options->gradient_tolerance = std::numeric_limits::epsilon(); + options->parameter_tolerance = std::numeric_limits::epsilon(); +} + +void SolveNISTProblems() { + if (FLAGS_nist_data_dir.empty()) { + LOG(FATAL) << "Must specify the directory containing the NIST problems"; + } + + ceres::Solver::Options options; + SetMinimizerOptions(&options); + + cout << "Lower Difficulty\n"; + int easy_success = 0; + easy_success += RegressionDriver("Misra1a.dat", options); + easy_success += RegressionDriver("Chwirut1.dat", options); + easy_success += RegressionDriver("Chwirut2.dat", options); + easy_success += RegressionDriver("Lanczos3.dat", options); + easy_success += RegressionDriver("Gauss1.dat", options); + easy_success += RegressionDriver("Gauss2.dat", options); + easy_success += RegressionDriver("DanWood.dat", options); + easy_success += RegressionDriver("Misra1b.dat", options); + + cout << "\nMedium Difficulty\n"; + int medium_success = 0; + medium_success += RegressionDriver("Kirby2.dat", options); + medium_success += RegressionDriver("Hahn1.dat", options); + medium_success += RegressionDriver("Nelson.dat", options); + medium_success += RegressionDriver("MGH17.dat", options); + medium_success += RegressionDriver("Lanczos1.dat", options); + medium_success += RegressionDriver("Lanczos2.dat", options); + medium_success += RegressionDriver("Gauss3.dat", options); + medium_success += RegressionDriver("Misra1c.dat", options); + medium_success += RegressionDriver("Misra1d.dat", options); + medium_success += RegressionDriver("Roszman1.dat", options); + medium_success += RegressionDriver("ENSO.dat", options); + + cout << "\nHigher Difficulty\n"; + int hard_success = 0; + hard_success += RegressionDriver("MGH09.dat", options); + hard_success += RegressionDriver("Thurber.dat", options); + hard_success += RegressionDriver("BoxBOD.dat", options); + hard_success += RegressionDriver("Rat42.dat", options); + hard_success += RegressionDriver("MGH10.dat", options); + + hard_success += RegressionDriver("Eckerle4.dat", options); + hard_success += RegressionDriver("Rat43.dat", options); + hard_success += RegressionDriver("Bennett5.dat", options); + + cout << "\n"; + cout << "Easy : " << easy_success << "/16\n"; + cout << "Medium : " << medium_success << "/22\n"; + cout << "Hard : " << hard_success << "/16\n"; + cout << "Total : " + << easy_success + medium_success + hard_success << "/54\n"; +} + +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + ceres::examples::SolveNISTProblems(); + return 0; +} diff --git a/examples/pgm_image.h b/examples/pgm_image.h new file mode 100644 index 0000000..1de8d67 --- /dev/null +++ b/examples/pgm_image.h @@ -0,0 +1,319 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) +// +// Simple class for accessing PGM images. + +#ifndef CERES_EXAMPLES_PGM_IMAGE_H_ +#define CERES_EXAMPLES_PGM_IMAGE_H_ + +#include +#include +#include +#include +#include +#include +#include + +#include "glog/logging.h" + +namespace ceres { +namespace examples { + +template +class PGMImage { + public: + // Create an empty image + PGMImage(int width, int height); + // Load an image from file + explicit PGMImage(std::string filename); + // Sets an image to a constant + void Set(double constant); + + // Reading dimensions + int width() const; + int height() const; + int NumPixels() const; + + // Get individual pixels + Real* MutablePixel(int x, int y); + Real Pixel(int x, int y) const; + Real* MutablePixelFromLinearIndex(int index); + Real PixelFromLinearIndex(int index) const; + int LinearIndex(int x, int y) const; + + // Adds an image to another + void operator+=(const PGMImage& image); + // Adds a constant to an image + void operator+=(Real a); + // Multiplies an image by a constant + void operator*=(Real a); + + // File access + bool WriteToFile(std::string filename) const; + bool ReadFromFile(std::string filename); + + // Accessing the image data directly + bool SetData(const std::vector& new_data); + const std::vector& data() const; + + protected: + int height_, width_; + std::vector data_; +}; + +// --- IMPLEMENTATION + +template +PGMImage::PGMImage(int width, int height) + : height_(height), width_(width), data_(width*height, 0.0) { +} + +template +PGMImage::PGMImage(std::string filename) { + if (!ReadFromFile(filename)) { + height_ = 0; + width_ = 0; + } +} + +template +void PGMImage::Set(double constant) { + for (int i = 0; i < data_.size(); ++i) { + data_[i] = constant; + } +} + +template +int PGMImage::width() const { + return width_; +} + +template +int PGMImage::height() const { + return height_; +} + +template +int PGMImage::NumPixels() const { + return width_ * height_; +} + +template +Real* PGMImage::MutablePixel(int x, int y) { + return MutablePixelFromLinearIndex(LinearIndex(x, y)); +} + +template +Real PGMImage::Pixel(int x, int y) const { + return PixelFromLinearIndex(LinearIndex(x, y)); +} + +template +Real* PGMImage::MutablePixelFromLinearIndex(int index) { + CHECK(index >= 0); + CHECK(index < width_ * height_); + CHECK(index < data_.size()); + return &data_[index]; +} + +template +Real PGMImage::PixelFromLinearIndex(int index) const { + CHECK(index >= 0); + CHECK(index < width_ * height_); + CHECK(index < data_.size()); + return data_[index]; +} + +template +int PGMImage::LinearIndex(int x, int y) const { + return x + width_*y; +} + +// Adds an image to another +template +void PGMImage::operator+= (const PGMImage& image) { + CHECK(data_.size() == image.data_.size()); + for (int i = 0; i < data_.size(); ++i) { + data_[i] += image.data_[i]; + } +} + +// Adds a constant to an image +template +void PGMImage::operator+= (Real a) { + for (int i = 0; i < data_.size(); ++i) { + data_[i] += a; + } +} + +// Multiplies an image by a constant +template +void PGMImage::operator*= (Real a) { + for (int i = 0; i < data_.size(); ++i) { + data_[i] *= a; + } +} + +template +bool PGMImage::WriteToFile(std::string filename) const { + std::ofstream outputfile(filename.c_str()); + outputfile << "P2" << std::endl; + outputfile << "# PGM format" << std::endl; + outputfile << " # " << std::endl; + outputfile << " # ... " << std::endl; + outputfile << width_ << ' ' << height_ << " 255 " << std::endl; + + // Write data + int num_pixels = width_*height_; + for (int i = 0; i < num_pixels; ++i) { + // Convert to integer by rounding when writing file + outputfile << static_cast(data_[i] + 0.5) << ' '; + } + + return bool(outputfile); // Returns true/false +} + +namespace { + +// Helper function to read data from a text file, ignoring "#" comments. +template +bool GetIgnoreComment(std::istream* in, T& t) { + std::string word; + bool ok; + do { + ok = true; + (*in) >> word; + if (word.length() > 0 && word[0] == '#') { + // Comment; read the whole line + ok = false; + std::getline(*in, word); + } + } while (!ok); + + // Convert the string + std::stringstream sin(word); + sin >> t; + + // Check for success + if (!in || !sin) { + return false; + } + return true; +} +} // namespace + +template +bool PGMImage::ReadFromFile(std::string filename) { + std::ifstream inputfile(filename.c_str()); + + // File must start with "P2" + char ch1, ch2; + inputfile >> ch1 >> ch2; + if (!inputfile || ch1 != 'P' || (ch2 != '2' && ch2 != '5')) { + return false; + } + + // Read the image header + int two_fifty_five; + if (!GetIgnoreComment(&inputfile, width_) || + !GetIgnoreComment(&inputfile, height_) || + !GetIgnoreComment(&inputfile, two_fifty_five) ) { + return false; + } + // Assert that the number of grey levels is 255. + if (two_fifty_five != 255) { + return false; + } + + // Now read the data + int num_pixels = width_*height_; + data_.resize(num_pixels); + if (ch2 == '2') { + // Ascii file + for (int i = 0; i < num_pixels; ++i) { + int pixel_data; + bool res = GetIgnoreComment(&inputfile, pixel_data); + if (!res) { + return false; + } + data_[i] = pixel_data; + } + // There cannot be anything else in the file (except comments). Try reading + // another number and return failure if that succeeded. + int temp; + bool res = GetIgnoreComment(&inputfile, temp); + if (res) { + return false; + } + } else { + // Read the line feed character + if (inputfile.get() != '\n') { + return false; + } + // Binary file + // TODO(strandmark): Will not work on Windows (linebreak conversion). + for (int i = 0; i < num_pixels; ++i) { + unsigned char pixel_data = inputfile.get(); + if (!inputfile) { + return false; + } + data_[i] = pixel_data; + } + // There cannot be anything else in the file. Try reading another byte + // and return failure if that succeeded. + inputfile.get(); + if (inputfile) { + return false; + } + } + + return true; +} + +template +bool PGMImage::SetData(const std::vector& new_data) { + // This function cannot change the dimensions + if (new_data.size() != data_.size()) { + return false; + } + std::copy(new_data.begin(), new_data.end(), data_.begin()); + return true; +} + +template +const std::vector& PGMImage::data() const { + return data_; +} + +} // namespace examples +} // namespace ceres + + +#endif // CERES_EXAMPLES_PGM_IMAGE_H_ diff --git a/examples/powell.cc b/examples/powell.cc new file mode 100644 index 0000000..e98f12f --- /dev/null +++ b/examples/powell.cc @@ -0,0 +1,154 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// An example program that minimizes Powell's singular function. +// +// F = 1/2 (f1^2 + f2^2 + f3^2 + f4^2) +// +// f1 = x1 + 10*x2; +// f2 = sqrt(5) * (x3 - x4) +// f3 = (x2 - 2*x3)^2 +// f4 = sqrt(10) * (x1 - x4)^2 +// +// The starting values are x1 = 3, x2 = -1, x3 = 0, x4 = 1. +// The minimum is 0 at (x1, x2, x3, x4) = 0. +// +// From: Testing Unconstrained Optimization Software by Jorge J. More, Burton S. +// Garbow and Kenneth E. Hillstrom in ACM Transactions on Mathematical Software, +// Vol 7(1), March 1981. + +#include +#include "ceres/ceres.h" +#include "gflags/gflags.h" +#include "glog/logging.h" + +using ceres::AutoDiffCostFunction; +using ceres::CostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +struct F1 { + template bool operator()(const T* const x1, + const T* const x2, + T* residual) const { + // f1 = x1 + 10 * x2; + residual[0] = x1[0] + 10.0 * x2[0]; + return true; + } +}; + +struct F2 { + template bool operator()(const T* const x3, + const T* const x4, + T* residual) const { + // f2 = sqrt(5) (x3 - x4) + residual[0] = sqrt(5.0) * (x3[0] - x4[0]); + return true; + } +}; + +struct F3 { + template bool operator()(const T* const x2, + const T* const x4, + T* residual) const { + // f3 = (x2 - 2 x3)^2 + residual[0] = (x2[0] - 2.0 * x4[0]) * (x2[0] - 2.0 * x4[0]); + return true; + } +}; + +struct F4 { + template bool operator()(const T* const x1, + const T* const x4, + T* residual) const { + // f4 = sqrt(10) (x1 - x4)^2 + residual[0] = sqrt(10.0) * (x1[0] - x4[0]) * (x1[0] - x4[0]); + return true; + } +}; + +DEFINE_string(minimizer, "trust_region", + "Minimizer type to use, choices are: line_search & trust_region"); + +int main(int argc, char** argv) { + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + google::InitGoogleLogging(argv[0]); + + double x1 = 3.0; + double x2 = -1.0; + double x3 = 0.0; + double x4 = 1.0; + + Problem problem; + // Add residual terms to the problem using the using the autodiff + // wrapper to get the derivatives automatically. The parameters, x1 through + // x4, are modified in place. + problem.AddResidualBlock(new AutoDiffCostFunction(new F1), + NULL, + &x1, &x2); + problem.AddResidualBlock(new AutoDiffCostFunction(new F2), + NULL, + &x3, &x4); + problem.AddResidualBlock(new AutoDiffCostFunction(new F3), + NULL, + &x2, &x3); + problem.AddResidualBlock(new AutoDiffCostFunction(new F4), + NULL, + &x1, &x4); + + Solver::Options options; + LOG_IF(FATAL, !ceres::StringToMinimizerType(FLAGS_minimizer, + &options.minimizer_type)) + << "Invalid minimizer: " << FLAGS_minimizer + << ", valid options are: trust_region and line_search."; + + options.max_num_iterations = 100; + options.linear_solver_type = ceres::DENSE_QR; + options.minimizer_progress_to_stdout = true; + + std::cout << "Initial x1 = " << x1 + << ", x2 = " << x2 + << ", x3 = " << x3 + << ", x4 = " << x4 + << "\n"; + + // Run the solver! + Solver::Summary summary; + Solve(options, &problem, &summary); + + std::cout << summary.FullReport() << "\n"; + std::cout << "Final x1 = " << x1 + << ", x2 = " << x2 + << ", x3 = " << x3 + << ", x4 = " << x4 + << "\n"; + return 0; +} diff --git a/examples/random.h b/examples/random.h new file mode 100644 index 0000000..7b09b15 --- /dev/null +++ b/examples/random.h @@ -0,0 +1,64 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_EXAMPLES_RANDOM_H_ +#define CERES_EXAMPLES_RANDOM_H_ + +#include +#include + +namespace ceres { +namespace examples { + +// Return a random number sampled from a uniform distribution in the range +// [0,1]. +inline double RandDouble() { + double r = static_cast(rand()); + return r / RAND_MAX; +} + +// Marsaglia Polar method for generation standard normal (pseudo) +// random numbers http://en.wikipedia.org/wiki/Marsaglia_polar_method +inline double RandNormal() { + double x1, x2, w; + do { + x1 = 2.0 * RandDouble() - 1.0; + x2 = 2.0 * RandDouble() - 1.0; + w = x1 * x1 + x2 * x2; + } while ( w >= 1.0 || w == 0.0 ); + + w = sqrt((-2.0 * log(w)) / w); + return x1 * w; +} + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_RANDOM_H_ diff --git a/examples/robot_pose_mle.cc b/examples/robot_pose_mle.cc new file mode 100644 index 0000000..1f5058a --- /dev/null +++ b/examples/robot_pose_mle.cc @@ -0,0 +1,316 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: joydeepb@ri.cmu.edu (Joydeep Biswas) +// +// This example demonstrates how to use the DynamicAutoDiffCostFunction +// variant of CostFunction. The DynamicAutoDiffCostFunction is meant to +// be used in cases where the number of parameter blocks or the sizes are not +// known at compile time. +// +// This example simulates a robot traversing down a 1-dimension hallway with +// noise odometry readings and noisy range readings of the end of the hallway. +// By fusing the noisy odometry and sensor readings this example demonstrates +// how to compute the maximum likelihood estimate (MLE) of the robot's pose at +// each timestep. +// +// The robot starts at the origin, and it is travels to the end of a corridor of +// fixed length specified by the "--corridor_length" flag. It executes a series +// of motion commands to move forward a fixed length, specified by the +// "--pose_separation" flag, at which pose it receives relative odometry +// measurements as well as a range reading of the distance to the end of the +// hallway. The odometry readings are drawn with Gaussian noise and standard +// deviation specified by the "--odometry_stddev" flag, and the range readings +// similarly with standard deviation specified by the "--range-stddev" flag. +// +// There are two types of residuals in this problem: +// 1) The OdometryConstraint residual, that accounts for the odometry readings +// between successive pose estimatess of the robot. +// 2) The RangeConstraint residual, that accounts for the errors in the observed +// range readings from each pose. +// +// The OdometryConstraint residual is modeled as an AutoDiffCostFunction with +// a fixed parameter block size of 1, which is the relative odometry being +// solved for, between a pair of successive poses of the robot. Differences +// between observed and computed relative odometry values are penalized weighted +// by the known standard deviation of the odometry readings. +// +// The RangeConstraint residual is modeled as a DynamicAutoDiffCostFunction +// which sums up the relative odometry estimates to compute the estimated +// global pose of the robot, and then computes the expected range reading. +// Differences between the observed and expected range readings are then +// penalized weighted by the standard deviation of readings of the sensor. +// Since the number of poses of the robot is not known at compile time, this +// cost function is implemented as a DynamicAutoDiffCostFunction. +// +// The outputs of the example are the initial values of the odometry and range +// readings, and the range and odometry errors for every pose of the robot. +// After computing the MLE, the computed poses and corrected odometry values +// are printed out, along with the corresponding range and odometry errors. Note +// that as an MLE of a noisy system the errors will not be reduced to zero, but +// the odometry estimates will be updated to maximize the joint likelihood of +// all odometry and range readings of the robot. +// +// Mathematical Formulation +// ====================================================== +// +// Let p_0, .., p_N be (N+1) robot poses, where the robot moves down the +// corridor starting from p_0 and ending at p_N. We assume that p_0 is the +// origin of the coordinate system. +// Odometry u_i is the observed relative odometry between pose p_(i-1) and p_i, +// and range reading y_i is the range reading of the end of the corridor from +// pose p_i. Both odometry as well as range readings are noisy, but we wish to +// compute the maximum likelihood estimate (MLE) of corrected odometry values +// u*_0 to u*_(N-1), such that the Belief is optimized: +// +// Belief(u*_(0:N-1) | u_(0:N-1), y_(0:N-1)) 1. +// = P(u*_(0:N-1) | u_(0:N-1), y_(0:N-1)) 2. +// \propto P(y_(0:N-1) | u*_(0:N-1), u_(0:N-1)) P(u*_(0:N-1) | u_(0:N-1)) 3. +// = \prod_i{ P(y_i | u*_(0:i)) P(u*_i | u_i) } 4. +// +// Here, the subscript "(0:i)" is used as shorthand to indicate entries from all +// timesteps 0 to i for that variable, both inclusive. +// +// Bayes' rule is used to derive eq. 3 from 2, and the independence of +// odometry observations and range readings is expolited to derive 4 from 3. +// +// Thus, the Belief, up to scale, is factored as a product of a number of +// terms, two for each pose, where for each pose term there is one term for the +// range reading, P(y_i | u*_(0:i) and one term for the odometry reading, +// P(u*_i | u_i) . Note that the term for the range reading is dependent on all +// odometry values u*_(0:i), while the odometry term, P(u*_i | u_i) depends only +// on a single value, u_i. Both the range reading as well as odoemtry +// probability terms are modeled as the Normal distribution, and have the form: +// +// p(x) \propto \exp{-((x - x_mean) / x_stddev)^2} +// +// where x refers to either the MLE odometry u* or range reading y, and x_mean +// is the corresponding mean value, u for the odometry terms, and y_expected, +// the expected range reading based on all the previous odometry terms. +// The MLE is thus found by finding those values x* which minimize: +// +// x* = \arg\min{((x - x_mean) / x_stddev)^2} +// +// which is in the nonlinear least-square form, suited to being solved by Ceres. +// The non-linear component arise from the computation of x_mean. The residuals +// ((x - x_mean) / x_stddev) for the residuals that Ceres will optimize. As +// mentioned earlier, the odometry term for each pose depends only on one +// variable, and will be computed by an AutoDiffCostFunction, while the term +// for the range reading will depend on all previous odometry observations, and +// will be computed by a DynamicAutoDiffCostFunction since the number of +// odoemtry observations will only be known at run time. + +#include +#include +#include + +#include "ceres/ceres.h" +#include "ceres/dynamic_autodiff_cost_function.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "random.h" + +using ceres::AutoDiffCostFunction; +using ceres::DynamicAutoDiffCostFunction; +using ceres::CauchyLoss; +using ceres::CostFunction; +using ceres::LossFunction; +using ceres::Problem; +using ceres::Solve; +using ceres::Solver; +using ceres::examples::RandNormal; +using std::min; +using std::vector; + +DEFINE_double(corridor_length, 30.0, "Length of the corridor that the robot is " + "travelling down."); + +DEFINE_double(pose_separation, 0.5, "The distance that the robot traverses " + "between successive odometry updates."); + +DEFINE_double(odometry_stddev, 0.1, "The standard deviation of " + "odometry error of the robot."); + +DEFINE_double(range_stddev, 0.01, "The standard deviation of range readings of " + "the robot."); + +// The stride length of the dynamic_autodiff_cost_function evaluator. +static const int kStride = 10; + +struct OdometryConstraint { + typedef AutoDiffCostFunction OdometryCostFunction; + + OdometryConstraint(double odometry_mean, double odometry_stddev) : + odometry_mean(odometry_mean), odometry_stddev(odometry_stddev) {} + + template + bool operator()(const T* const odometry, T* residual) const { + *residual = (*odometry - odometry_mean) / odometry_stddev; + return true; + } + + static OdometryCostFunction* Create(const double odometry_value) { + return new OdometryCostFunction( + new OdometryConstraint(odometry_value, FLAGS_odometry_stddev)); + } + + const double odometry_mean; + const double odometry_stddev; +}; + +struct RangeConstraint { + typedef DynamicAutoDiffCostFunction + RangeCostFunction; + + RangeConstraint( + int pose_index, + double range_reading, + double range_stddev, + double corridor_length) : + pose_index(pose_index), range_reading(range_reading), + range_stddev(range_stddev), corridor_length(corridor_length) {} + + template + bool operator()(T const* const* relative_poses, T* residuals) const { + T global_pose(0); + for (int i = 0; i <= pose_index; ++i) { + global_pose += relative_poses[i][0]; + } + residuals[0] = (global_pose + range_reading - corridor_length) / + range_stddev; + return true; + } + + // Factory method to create a CostFunction from a RangeConstraint to + // conveniently add to a ceres problem. + static RangeCostFunction* Create(const int pose_index, + const double range_reading, + vector* odometry_values, + vector* parameter_blocks) { + RangeConstraint* constraint = new RangeConstraint( + pose_index, range_reading, FLAGS_range_stddev, FLAGS_corridor_length); + RangeCostFunction* cost_function = new RangeCostFunction(constraint); + // Add all the parameter blocks that affect this constraint. + parameter_blocks->clear(); + for (int i = 0; i <= pose_index; ++i) { + parameter_blocks->push_back(&((*odometry_values)[i])); + cost_function->AddParameterBlock(1); + } + cost_function->SetNumResiduals(1); + return (cost_function); + } + + const int pose_index; + const double range_reading; + const double range_stddev; + const double corridor_length; +}; + +void SimulateRobot(vector* odometry_values, + vector* range_readings) { + const int num_steps = static_cast( + ceil(FLAGS_corridor_length / FLAGS_pose_separation)); + + // The robot starts out at the origin. + double robot_location = 0.0; + for (int i = 0; i < num_steps; ++i) { + const double actual_odometry_value = min( + FLAGS_pose_separation, FLAGS_corridor_length - robot_location); + robot_location += actual_odometry_value; + const double actual_range = FLAGS_corridor_length - robot_location; + const double observed_odometry = + RandNormal() * FLAGS_odometry_stddev + actual_odometry_value; + const double observed_range = + RandNormal() * FLAGS_range_stddev + actual_range; + odometry_values->push_back(observed_odometry); + range_readings->push_back(observed_range); + } +} + +void PrintState(const vector& odometry_readings, + const vector& range_readings) { + CHECK_EQ(odometry_readings.size(), range_readings.size()); + double robot_location = 0.0; + printf("pose: location odom range r.error o.error\n"); + for (int i = 0; i < odometry_readings.size(); ++i) { + robot_location += odometry_readings[i]; + const double range_error = + robot_location + range_readings[i] - FLAGS_corridor_length; + const double odometry_error = + FLAGS_pose_separation - odometry_readings[i]; + printf("%4d: %8.3f %8.3f %8.3f %8.3f %8.3f\n", + static_cast(i), robot_location, odometry_readings[i], + range_readings[i], range_error, odometry_error); + } +} + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + // Make sure that the arguments parsed are all positive. + CHECK_GT(FLAGS_corridor_length, 0.0); + CHECK_GT(FLAGS_pose_separation, 0.0); + CHECK_GT(FLAGS_odometry_stddev, 0.0); + CHECK_GT(FLAGS_range_stddev, 0.0); + + vector odometry_values; + vector range_readings; + SimulateRobot(&odometry_values, &range_readings); + + printf("Initial values:\n"); + PrintState(odometry_values, range_readings); + ceres::Problem problem; + + for (int i = 0; i < odometry_values.size(); ++i) { + // Create and add a DynamicAutoDiffCostFunction for the RangeConstraint from + // pose i. + vector parameter_blocks; + RangeConstraint::RangeCostFunction* range_cost_function = + RangeConstraint::Create( + i, range_readings[i], &odometry_values, ¶meter_blocks); + problem.AddResidualBlock(range_cost_function, NULL, parameter_blocks); + + // Create and add an AutoDiffCostFunction for the OdometryConstraint for + // pose i. + problem.AddResidualBlock(OdometryConstraint::Create(odometry_values[i]), + NULL, + &(odometry_values[i])); + } + + ceres::Solver::Options solver_options; + solver_options.minimizer_progress_to_stdout = true; + + Solver::Summary summary; + printf("Solving...\n"); + Solve(solver_options, &problem, &summary); + printf("Done.\n"); + std::cout << summary.FullReport() << "\n"; + printf("Final values:\n"); + PrintState(odometry_values, range_readings); + return 0; +} diff --git a/examples/robust_curve_fitting.cc b/examples/robust_curve_fitting.cc new file mode 100644 index 0000000..6186aa1 --- /dev/null +++ b/examples/robust_curve_fitting.cc @@ -0,0 +1,165 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/ceres.h" +#include "glog/logging.h" + +// Data generated using the following octave code. +// randn('seed', 23497); +// m = 0.3; +// c = 0.1; +// x=[0:0.075:5]; +// y = exp(m * x + c); +// noise = randn(size(x)) * 0.2; +// outlier_noise = rand(size(x)) < 0.05; +// y_observed = y + noise + outlier_noise; +// data = [x', y_observed']; + +const int kNumObservations = 67; +const double data[] = { +0.000000e+00, 1.133898e+00, +7.500000e-02, 1.334902e+00, +1.500000e-01, 1.213546e+00, +2.250000e-01, 1.252016e+00, +3.000000e-01, 1.392265e+00, +3.750000e-01, 1.314458e+00, +4.500000e-01, 1.472541e+00, +5.250000e-01, 1.536218e+00, +6.000000e-01, 1.355679e+00, +6.750000e-01, 1.463566e+00, +7.500000e-01, 1.490201e+00, +8.250000e-01, 1.658699e+00, +9.000000e-01, 1.067574e+00, +9.750000e-01, 1.464629e+00, +1.050000e+00, 1.402653e+00, +1.125000e+00, 1.713141e+00, +1.200000e+00, 1.527021e+00, +1.275000e+00, 1.702632e+00, +1.350000e+00, 1.423899e+00, +1.425000e+00, 5.543078e+00, // Outlier point +1.500000e+00, 5.664015e+00, // Outlier point +1.575000e+00, 1.732484e+00, +1.650000e+00, 1.543296e+00, +1.725000e+00, 1.959523e+00, +1.800000e+00, 1.685132e+00, +1.875000e+00, 1.951791e+00, +1.950000e+00, 2.095346e+00, +2.025000e+00, 2.361460e+00, +2.100000e+00, 2.169119e+00, +2.175000e+00, 2.061745e+00, +2.250000e+00, 2.178641e+00, +2.325000e+00, 2.104346e+00, +2.400000e+00, 2.584470e+00, +2.475000e+00, 1.914158e+00, +2.550000e+00, 2.368375e+00, +2.625000e+00, 2.686125e+00, +2.700000e+00, 2.712395e+00, +2.775000e+00, 2.499511e+00, +2.850000e+00, 2.558897e+00, +2.925000e+00, 2.309154e+00, +3.000000e+00, 2.869503e+00, +3.075000e+00, 3.116645e+00, +3.150000e+00, 3.094907e+00, +3.225000e+00, 2.471759e+00, +3.300000e+00, 3.017131e+00, +3.375000e+00, 3.232381e+00, +3.450000e+00, 2.944596e+00, +3.525000e+00, 3.385343e+00, +3.600000e+00, 3.199826e+00, +3.675000e+00, 3.423039e+00, +3.750000e+00, 3.621552e+00, +3.825000e+00, 3.559255e+00, +3.900000e+00, 3.530713e+00, +3.975000e+00, 3.561766e+00, +4.050000e+00, 3.544574e+00, +4.125000e+00, 3.867945e+00, +4.200000e+00, 4.049776e+00, +4.275000e+00, 3.885601e+00, +4.350000e+00, 4.110505e+00, +4.425000e+00, 4.345320e+00, +4.500000e+00, 4.161241e+00, +4.575000e+00, 4.363407e+00, +4.650000e+00, 4.161576e+00, +4.725000e+00, 4.619728e+00, +4.800000e+00, 4.737410e+00, +4.875000e+00, 4.727863e+00, +4.950000e+00, 4.669206e+00 +}; + +using ceres::AutoDiffCostFunction; +using ceres::CostFunction; +using ceres::CauchyLoss; +using ceres::Problem; +using ceres::Solve; +using ceres::Solver; + +struct ExponentialResidual { + ExponentialResidual(double x, double y) + : x_(x), y_(y) {} + + template bool operator()(const T* const m, + const T* const c, + T* residual) const { + residual[0] = y_ - exp(m[0] * x_ + c[0]); + return true; + } + + private: + const double x_; + const double y_; +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + double m = 0.0; + double c = 0.0; + + Problem problem; + for (int i = 0; i < kNumObservations; ++i) { + CostFunction* cost_function = + new AutoDiffCostFunction( + new ExponentialResidual(data[2 * i], data[2 * i + 1])); + problem.AddResidualBlock(cost_function, + new CauchyLoss(0.5), + &m, &c); + } + + Solver::Options options; + options.linear_solver_type = ceres::DENSE_QR; + options.minimizer_progress_to_stdout = true; + + Solver::Summary summary; + Solve(options, &problem, &summary); + std::cout << summary.BriefReport() << "\n"; + std::cout << "Initial m: " << 0.0 << " c: " << 0.0 << "\n"; + std::cout << "Final m: " << m << " c: " << c << "\n"; + return 0; +} diff --git a/examples/rosenbrock.cc b/examples/rosenbrock.cc new file mode 100644 index 0000000..3f64f1c --- /dev/null +++ b/examples/rosenbrock.cc @@ -0,0 +1,74 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/ceres.h" +#include "glog/logging.h" + +// f(x,y) = (1-x)^2 + 100(y - x^2)^2; +class Rosenbrock : public ceres::FirstOrderFunction { + public: + virtual ~Rosenbrock() {} + + virtual bool Evaluate(const double* parameters, + double* cost, + double* gradient) const { + const double x = parameters[0]; + const double y = parameters[1]; + + cost[0] = (1.0 - x) * (1.0 - x) + 100.0 * (y - x * x) * (y - x * x); + if (gradient != NULL) { + gradient[0] = -2.0 * (1.0 - x) - 200.0 * (y - x * x) * 2.0 * x; + gradient[1] = 200.0 * (y - x * x); + } + return true; + } + + virtual int NumParameters() const { return 2; } +}; + + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + double parameters[2] = {-1.2, 1.0}; + + ceres::GradientProblemSolver::Options options; + options.minimizer_progress_to_stdout = true; + + ceres::GradientProblemSolver::Summary summary; + ceres::GradientProblem problem(new Rosenbrock()); + ceres::Solve(options, problem, parameters, &summary); + + std::cout << summary.FullReport() << "\n"; + std::cout << "Initial x: " << -1.2 << " y: " << 1.0 << "\n"; + std::cout << "Final x: " << parameters[0] + << " y: " << parameters[1] << "\n"; + return 0; +} diff --git a/examples/sampled_function/CMakeLists.txt b/examples/sampled_function/CMakeLists.txt new file mode 100644 index 0000000..57f31d1 --- /dev/null +++ b/examples/sampled_function/CMakeLists.txt @@ -0,0 +1,32 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: vitus@google.com (Michael Vitus) + +add_executable(sampled_function sampled_function.cc) +target_link_libraries(sampled_function ceres) diff --git a/examples/sampled_function/README.md b/examples/sampled_function/README.md new file mode 100644 index 0000000..77ce365 --- /dev/null +++ b/examples/sampled_function/README.md @@ -0,0 +1,42 @@ +Sampled Functions +-- + +It is common to not have an analytical representation of the optimization +problem but rather a table of values at specific inputs. This commonly occurs +when working with images or when the functions in the problem are expensive to +evaluate. To use this data in an optimization problem we can use interpolation +to evaluate the function and derivatives at intermediate input values. + +There are many libraries that implement a variety of interpolation schemes, but +it is difficult to use them in Ceres' automatic differentiation framework. +Instead, Ceres provides the ability to interpolate one and two dimensional data. + +The one dimensional interpolation is based on the Cubic Hermite Spline. This +interpolation method requires knowledge of the function derivatives at the +control points, however we only know the function values. Consequently, we will +use the data to estimate derivatives at the control points. The choice of how to +compute the derivatives is not unique and Ceres uses the Catmull–Rom Spline +variant which uses `0.5 * (p_{k+1} - p_{k-1})` as the derivative for control +point `p_k.` This produces a first order differentiable interpolating +function. The two dimensional interpolation scheme is a generalization of the +one dimensional scheme where the interpolating function is assumed to be +separable in the two dimensions. + +This example shows how to use interpolation schemes within the Ceres automatic +differentiation framework. This is a one dimensional example and the objective +function is to minimize `0.5 * f(x)^2` where `f(x) = (x - 4.5)^2`. + +It is also possible to use analytical derivatives with the provided +interpolation schemes by using a `SizedCostFunction` and defining the +``Evaluate` function. For this example, the evaluate function would be: + +```c++ +bool Evaluate(double const* const* parameters, double* residuals, double** jacobians) const { + if (jacobians == NULL || jacobians[0] == NULL) + interpolator_.Evaluate(parameters[0][0], residuals); + else + interpolator_.Evaluate(parameters[0][0], residuals, jacobians[0]); + + return true; +} +``` diff --git a/examples/sampled_function/sampled_function.cc b/examples/sampled_function/sampled_function.cc new file mode 100644 index 0000000..093276a --- /dev/null +++ b/examples/sampled_function/sampled_function.cc @@ -0,0 +1,94 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// A simple example of optimizing a sampled function by using cubic +// interpolation. + +#include "ceres/ceres.h" +#include "ceres/cubic_interpolation.h" +#include "glog/logging.h" + +using ceres::Grid1D; +using ceres::CubicInterpolator; +using ceres::AutoDiffCostFunction; +using ceres::CostFunction; +using ceres::Problem; +using ceres::Solver; +using ceres::Solve; + +// A simple cost functor that interfaces an interpolated table of +// values with automatic differentiation. +struct InterpolatedCostFunctor { + explicit InterpolatedCostFunctor( + const CubicInterpolator >& interpolator) + : interpolator_(interpolator) { + } + + template bool operator()(const T* x, T* residuals) const { + interpolator_.Evaluate(*x, residuals); + return true; + } + + static CostFunction* Create( + const CubicInterpolator >& interpolator) { + return new AutoDiffCostFunction( + new InterpolatedCostFunctor(interpolator)); + } + + private: + const CubicInterpolator >& interpolator_; +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + + // Evaluate the function f(x) = (x - 4.5)^2; + const int kNumSamples = 10; + double values[kNumSamples]; + for (int i = 0; i < kNumSamples; ++i) { + values[i] = (i - 4.5) * (i - 4.5); + } + + Grid1D array(values, 0, kNumSamples); + CubicInterpolator > interpolator(array); + + double x = 1.0; + Problem problem; + CostFunction* cost_function = InterpolatedCostFunctor::Create(interpolator); + problem.AddResidualBlock(cost_function, NULL, &x); + + Solver::Options options; + options.minimizer_progress_to_stdout = true; + Solver::Summary summary; + Solve(options, &problem, &summary); + std::cout << summary.BriefReport() << "\n"; + std::cout << "Expected x: 4.5. Actual x : " << x << std::endl; + return 0; +} diff --git a/examples/simple_bundle_adjuster.cc b/examples/simple_bundle_adjuster.cc new file mode 100644 index 0000000..dec6cd6 --- /dev/null +++ b/examples/simple_bundle_adjuster.cc @@ -0,0 +1,218 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A minimal, self-contained bundle adjuster using Ceres, that reads +// files from University of Washington' Bundle Adjustment in the Large dataset: +// http://grail.cs.washington.edu/projects/bal +// +// This does not use the best configuration for solving; see the more involved +// bundle_adjuster.cc file for details. + +#include +#include +#include + +#include "ceres/ceres.h" +#include "ceres/rotation.h" + +// Read a Bundle Adjustment in the Large dataset. +class BALProblem { + public: + ~BALProblem() { + delete[] point_index_; + delete[] camera_index_; + delete[] observations_; + delete[] parameters_; + } + + int num_observations() const { return num_observations_; } + const double* observations() const { return observations_; } + double* mutable_cameras() { return parameters_; } + double* mutable_points() { return parameters_ + 9 * num_cameras_; } + + double* mutable_camera_for_observation(int i) { + return mutable_cameras() + camera_index_[i] * 9; + } + double* mutable_point_for_observation(int i) { + return mutable_points() + point_index_[i] * 3; + } + + bool LoadFile(const char* filename) { + FILE* fptr = fopen(filename, "r"); + if (fptr == NULL) { + return false; + }; + + FscanfOrDie(fptr, "%d", &num_cameras_); + FscanfOrDie(fptr, "%d", &num_points_); + FscanfOrDie(fptr, "%d", &num_observations_); + + point_index_ = new int[num_observations_]; + camera_index_ = new int[num_observations_]; + observations_ = new double[2 * num_observations_]; + + num_parameters_ = 9 * num_cameras_ + 3 * num_points_; + parameters_ = new double[num_parameters_]; + + for (int i = 0; i < num_observations_; ++i) { + FscanfOrDie(fptr, "%d", camera_index_ + i); + FscanfOrDie(fptr, "%d", point_index_ + i); + for (int j = 0; j < 2; ++j) { + FscanfOrDie(fptr, "%lf", observations_ + 2*i + j); + } + } + + for (int i = 0; i < num_parameters_; ++i) { + FscanfOrDie(fptr, "%lf", parameters_ + i); + } + return true; + } + + private: + template + void FscanfOrDie(FILE *fptr, const char *format, T *value) { + int num_scanned = fscanf(fptr, format, value); + if (num_scanned != 1) { + LOG(FATAL) << "Invalid UW data file."; + } + } + + int num_cameras_; + int num_points_; + int num_observations_; + int num_parameters_; + + int* point_index_; + int* camera_index_; + double* observations_; + double* parameters_; +}; + +// Templated pinhole camera model for used with Ceres. The camera is +// parameterized using 9 parameters: 3 for rotation, 3 for translation, 1 for +// focal length and 2 for radial distortion. The principal point is not modeled +// (i.e. it is assumed be located at the image center). +struct SnavelyReprojectionError { + SnavelyReprojectionError(double observed_x, double observed_y) + : observed_x(observed_x), observed_y(observed_y) {} + + template + bool operator()(const T* const camera, + const T* const point, + T* residuals) const { + // camera[0,1,2] are the angle-axis rotation. + T p[3]; + ceres::AngleAxisRotatePoint(camera, point, p); + + // camera[3,4,5] are the translation. + p[0] += camera[3]; + p[1] += camera[4]; + p[2] += camera[5]; + + // Compute the center of distortion. The sign change comes from + // the camera model that Noah Snavely's Bundler assumes, whereby + // the camera coordinate system has a negative z axis. + T xp = - p[0] / p[2]; + T yp = - p[1] / p[2]; + + // Apply second and fourth order radial distortion. + const T& l1 = camera[7]; + const T& l2 = camera[8]; + T r2 = xp*xp + yp*yp; + T distortion = 1.0 + r2 * (l1 + l2 * r2); + + // Compute final projected point position. + const T& focal = camera[6]; + T predicted_x = focal * distortion * xp; + T predicted_y = focal * distortion * yp; + + // The error is the difference between the predicted and observed position. + residuals[0] = predicted_x - observed_x; + residuals[1] = predicted_y - observed_y; + + return true; + } + + // Factory to hide the construction of the CostFunction object from + // the client code. + static ceres::CostFunction* Create(const double observed_x, + const double observed_y) { + return (new ceres::AutoDiffCostFunction( + new SnavelyReprojectionError(observed_x, observed_y))); + } + + double observed_x; + double observed_y; +}; + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + if (argc != 2) { + std::cerr << "usage: simple_bundle_adjuster \n"; + return 1; + } + + BALProblem bal_problem; + if (!bal_problem.LoadFile(argv[1])) { + std::cerr << "ERROR: unable to open file " << argv[1] << "\n"; + return 1; + } + + const double* observations = bal_problem.observations(); + + // Create residuals for each observation in the bundle adjustment problem. The + // parameters for cameras and points are added automatically. + ceres::Problem problem; + for (int i = 0; i < bal_problem.num_observations(); ++i) { + // Each Residual block takes a point and a camera as input and outputs a 2 + // dimensional residual. Internally, the cost function stores the observed + // image location and compares the reprojection against the observation. + + ceres::CostFunction* cost_function = + SnavelyReprojectionError::Create(observations[2 * i + 0], + observations[2 * i + 1]); + problem.AddResidualBlock(cost_function, + NULL /* squared loss */, + bal_problem.mutable_camera_for_observation(i), + bal_problem.mutable_point_for_observation(i)); + } + + // Make Ceres automatically detect the bundle structure. Note that the + // standard solver, SPARSE_NORMAL_CHOLESKY, also works fine but it is slower + // for standard bundle adjustment problems. + ceres::Solver::Options options; + options.linear_solver_type = ceres::DENSE_SCHUR; + options.minimizer_progress_to_stdout = true; + + ceres::Solver::Summary summary; + ceres::Solve(options, &problem, &summary); + std::cout << summary.FullReport() << "\n"; + return 0; +} diff --git a/examples/slam/CMakeLists.txt b/examples/slam/CMakeLists.txt new file mode 100644 index 0000000..c72aa16 --- /dev/null +++ b/examples/slam/CMakeLists.txt @@ -0,0 +1,33 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2016 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: vitus@google.com (Michael Vitus) +include_directories(./) + +add_subdirectory(pose_graph_2d) +add_subdirectory(pose_graph_3d) diff --git a/examples/slam/common/read_g2o.h b/examples/slam/common/read_g2o.h new file mode 100644 index 0000000..71b071c --- /dev/null +++ b/examples/slam/common/read_g2o.h @@ -0,0 +1,141 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) +// +// Reads a file in the g2o filename format that describes a pose graph problem. + +#ifndef EXAMPLES_CERES_READ_G2O_H_ +#define EXAMPLES_CERES_READ_G2O_H_ + +#include +#include + +#include "glog/logging.h" + +namespace ceres { +namespace examples { + +// Reads a single pose from the input and inserts it into the map. Returns false +// if there is a duplicate entry. +template +bool ReadVertex(std::ifstream* infile, + std::map, Allocator>* poses) { + int id; + Pose pose; + *infile >> id >> pose; + + // Ensure we don't have duplicate poses. + if (poses->find(id) != poses->end()) { + LOG(ERROR) << "Duplicate vertex with ID: " << id; + return false; + } + (*poses)[id] = pose; + + return true; +} + +// Reads the contraints between two vertices in the pose graph +template +void ReadConstraint(std::ifstream* infile, + std::vector* constraints) { + Constraint constraint; + *infile >> constraint; + + constraints->push_back(constraint); +} + +// Reads a file in the g2o filename format that describes a pose graph +// problem. The g2o format consists of two entries, vertices and constraints. +// +// In 2D, a vertex is defined as follows: +// +// VERTEX_SE2 ID x_meters y_meters yaw_radians +// +// A constraint is defined as follows: +// +// EDGE_SE2 ID_A ID_B A_x_B A_y_B A_yaw_B I_11 I_12 I_13 I_22 I_23 I_33 +// +// where I_ij is the (i, j)-th entry of the information matrix for the +// measurement. +// +// +// In 3D, a vertex is defined as follows: +// +// VERTEX_SE3:QUAT ID x y z q_x q_y q_z q_w +// +// where the quaternion is in Hamilton form. +// A constraint is defined as follows: +// +// EDGE_SE3:QUAT ID_a ID_b x_ab y_ab z_ab q_x_ab q_y_ab q_z_ab q_w_ab I_11 I_12 I_13 ... I_16 I_22 I_23 ... I_26 ... I_66 // NOLINT +// +// where I_ij is the (i, j)-th entry of the information matrix for the +// measurement. Only the upper-triangular part is stored. The measurement order +// is the delta position followed by the delta orientation. +template +bool ReadG2oFile(const std::string& filename, + std::map, MapAllocator>* poses, + std::vector* constraints) { + CHECK(poses != NULL); + CHECK(constraints != NULL); + + poses->clear(); + constraints->clear(); + + std::ifstream infile(filename.c_str()); + if (!infile) { + return false; + } + + std::string data_type; + while (infile.good()) { + // Read whether the type is a node or a constraint. + infile >> data_type; + if (data_type == Pose::name()) { + if (!ReadVertex(&infile, poses)) { + return false; + } + } else if (data_type == Constraint::name()) { + ReadConstraint(&infile, constraints); + } else { + LOG(ERROR) << "Unknown data type: " << data_type; + return false; + } + + // Clear any trailing whitespace from the line. + infile >> std::ws; + } + + return true; +} + +} // namespace examples +} // namespace ceres + +#endif // EXAMPLES_CERES_READ_G2O_H_ diff --git a/examples/slam/pose_graph_2d/CMakeLists.txt b/examples/slam/pose_graph_2d/CMakeLists.txt new file mode 100644 index 0000000..d654e8c --- /dev/null +++ b/examples/slam/pose_graph_2d/CMakeLists.txt @@ -0,0 +1,39 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2016 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: vitus@google.com (Michael Vitus) + +if (GFLAGS) + add_executable(pose_graph_2d + angle_local_parameterization.h + normalize_angle.h + pose_graph_2d.cc + pose_graph_2d_error_term.h + types.h) + target_link_libraries(pose_graph_2d ceres ${GFLAGS_LIBRARIES}) +endif (GFLAGS) \ No newline at end of file diff --git a/examples/slam/pose_graph_2d/README.md b/examples/slam/pose_graph_2d/README.md new file mode 100644 index 0000000..fed51a6 --- /dev/null +++ b/examples/slam/pose_graph_2d/README.md @@ -0,0 +1,46 @@ +Pose Graph 2D +---------------- + +The Simultaneous Localization and Mapping (SLAM) problem consists of building a +map of an unknown environment while simultaneously localizing against this +map. The main difficulty of this problem stems from not having any additional +external aiding information such as GPS. SLAM has been considered one of the +fundamental challenges of robotics. A pose graph optimization problem is one +example of a SLAM problem. + +This package defines the necessary Ceres cost functions needed to model the +2-dimensional pose graph optimization problem as well as a binary to build and +solve the problem. The cost functions are shown for instruction purposes and can +be speed up by using analytical derivatives which take longer to implement. + +Running +----------- +This package includes an executable `pose_graph_2d` that will read a problem +definition file. This executable can work with any 2D problem definition that +uses the g2o format. It would be relatively straightforward to implement a new +reader for a different format such as TORO or others. `pose_graph_2d` will print +the Ceres solver full summary and then output to disk the original and optimized +poses (`poses_original.txt` and `poses_optimized.txt`, respectively) of the +robot in the following format: + +``` +pose_id x y yaw_radians +pose_id x y yaw_radians +pose_id x y yaw_radians +... +``` + +where `pose_id` is the corresponding integer ID from the file definition. Note, +the file will be sorted in ascending order for the `pose_id`. + +The executable `pose_graph_2d` expects the first argument to be the path to the +problem definition. To run the executable, + +``` +/path/to/bin/pose_graph_2d /path/to/dataset/dataset.g2o +``` + +A python script is provided to visualize the resulting output files. +``` +/path/to/repo/examples/slam/pose_graph_2d/plot_results.py --optimized_poses ./poses_optimized.txt --initial_poses ./poses_original.txt +``` diff --git a/examples/slam/pose_graph_2d/angle_local_parameterization.h b/examples/slam/pose_graph_2d/angle_local_parameterization.h new file mode 100644 index 0000000..428cccc --- /dev/null +++ b/examples/slam/pose_graph_2d/angle_local_parameterization.h @@ -0,0 +1,63 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) + +#ifndef CERES_EXAMPLES_POSE_GRAPH_2D_ANGLE_LOCAL_PARAMETERIZATION_H_ +#define CERES_EXAMPLES_POSE_GRAPH_2D_ANGLE_LOCAL_PARAMETERIZATION_H_ + +#include "ceres/local_parameterization.h" +#include "normalize_angle.h" + +namespace ceres { +namespace examples { + +// Defines a local parameterization for updating the angle to be constrained in +// [-pi to pi). +class AngleLocalParameterization { + public: + + template + bool operator()(const T* theta_radians, const T* delta_theta_radians, + T* theta_radians_plus_delta) const { + *theta_radians_plus_delta = + NormalizeAngle(*theta_radians + *delta_theta_radians); + + return true; + } + + static ceres::LocalParameterization* Create() { + return (new ceres::AutoDiffLocalParameterization); + } +}; + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_POSE_GRAPH_2D_ANGLE_LOCAL_PARAMETERIZATION_H_ diff --git a/examples/slam/pose_graph_2d/normalize_angle.h b/examples/slam/pose_graph_2d/normalize_angle.h new file mode 100644 index 0000000..afd5df4 --- /dev/null +++ b/examples/slam/pose_graph_2d/normalize_angle.h @@ -0,0 +1,53 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) + +#ifndef CERES_EXAMPLES_POSE_GRAPH_2D_NORMALIZE_ANGLE_H_ +#define CERES_EXAMPLES_POSE_GRAPH_2D_NORMALIZE_ANGLE_H_ + +#include + +#include "ceres/ceres.h" + +namespace ceres { +namespace examples { + +// Normalizes the angle in radians between [-pi and pi). +template +inline T NormalizeAngle(const T& angle_radians) { + // Use ceres::floor because it is specialized for double and Jet types. + T two_pi(2.0 * M_PI); + return angle_radians - + two_pi * ceres::floor((angle_radians + T(M_PI)) / two_pi); +} + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_POSE_GRAPH_2D_NORMALIZE_ANGLE_H_ diff --git a/examples/slam/pose_graph_2d/plot_results.py b/examples/slam/pose_graph_2d/plot_results.py new file mode 100755 index 0000000..2c4d16e --- /dev/null +++ b/examples/slam/pose_graph_2d/plot_results.py @@ -0,0 +1,45 @@ +#!/usr/bin/python +# +# Plots the results from the 2D pose graph optimization. It will draw a line +# between consecutive vertices. The commandline expects two optional filenames: +# +# ./plot_results.py --initial_poses optional --optimized_poses optional +# +# The files have the following format: +# ID x y yaw_radians + +import matplotlib.pyplot as plot +import numpy +import sys +from optparse import OptionParser + +parser = OptionParser() +parser.add_option("--initial_poses", dest="initial_poses", + default="", help="The filename that contains the original poses.") +parser.add_option("--optimized_poses", dest="optimized_poses", + default="", help="The filename that contains the optimized poses.") +(options, args) = parser.parse_args() + +# Read the original and optimized poses files. +poses_original = None +if options.initial_poses != '': + poses_original = numpy.genfromtxt(options.initial_poses, usecols = (1, 2)) + +poses_optimized = None +if options.optimized_poses != '': + poses_optimized = numpy.genfromtxt(options.optimized_poses, usecols = (1, 2)) + +# Plots the results for the specified poses. +plot.figure() +if poses_original is not None: + plot.plot(poses_original[:, 0], poses_original[:, 1], '-', label="Original", + alpha=0.5, color="green") + +if poses_optimized is not None: + plot.plot(poses_optimized[:, 0], poses_optimized[:, 1], '-', label="Optimized", + alpha=0.5, color="blue") + +plot.axis('equal') +plot.legend() +# Show the plot and wait for the user to close. +plot.show() diff --git a/examples/slam/pose_graph_2d/pose_graph_2d.cc b/examples/slam/pose_graph_2d/pose_graph_2d.cc new file mode 100644 index 0000000..b9374db --- /dev/null +++ b/examples/slam/pose_graph_2d/pose_graph_2d.cc @@ -0,0 +1,182 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) +// +// An example of solving a graph-based formulation of Simultaneous Localization +// and Mapping (SLAM). It reads a 2D pose graph problem definition file in the +// g2o format, formulates and solves the Ceres optimization problem, and outputs +// the original and optimized poses to file for plotting. + +#include +#include +#include +#include +#include + +#include "angle_local_parameterization.h" +#include "ceres/ceres.h" +#include "common/read_g2o.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "pose_graph_2d_error_term.h" +#include "types.h" + +DEFINE_string(input, "", "The pose graph definition filename in g2o format."); + +namespace ceres { +namespace examples { + +// Constructs the nonlinear least squares optimization problem from the pose +// graph constraints. +void BuildOptimizationProblem(const std::vector& constraints, + std::map* poses, + ceres::Problem* problem) { + CHECK(poses != NULL); + CHECK(problem != NULL); + if (constraints.empty()) { + LOG(INFO) << "No constraints, no problem to optimize."; + return; + } + + ceres::LossFunction* loss_function = NULL; + ceres::LocalParameterization* angle_local_parameterization = + AngleLocalParameterization::Create(); + + for (std::vector::const_iterator constraints_iter = + constraints.begin(); + constraints_iter != constraints.end(); ++constraints_iter) { + const Constraint2d& constraint = *constraints_iter; + + std::map::iterator pose_begin_iter = + poses->find(constraint.id_begin); + CHECK(pose_begin_iter != poses->end()) + << "Pose with ID: " << constraint.id_begin << " not found."; + std::map::iterator pose_end_iter = + poses->find(constraint.id_end); + CHECK(pose_end_iter != poses->end()) + << "Pose with ID: " << constraint.id_end << " not found."; + + const Eigen::Matrix3d sqrt_information = + constraint.information.llt().matrixL(); + // Ceres will take ownership of the pointer. + ceres::CostFunction* cost_function = PoseGraph2dErrorTerm::Create( + constraint.x, constraint.y, constraint.yaw_radians, sqrt_information); + problem->AddResidualBlock( + cost_function, loss_function, &pose_begin_iter->second.x, + &pose_begin_iter->second.y, &pose_begin_iter->second.yaw_radians, + &pose_end_iter->second.x, &pose_end_iter->second.y, + &pose_end_iter->second.yaw_radians); + + problem->SetParameterization(&pose_begin_iter->second.yaw_radians, + angle_local_parameterization); + problem->SetParameterization(&pose_end_iter->second.yaw_radians, + angle_local_parameterization); + } + + // The pose graph optimization problem has three DOFs that are not fully + // constrained. This is typically referred to as gauge freedom. You can apply + // a rigid body transformation to all the nodes and the optimization problem + // will still have the exact same cost. The Levenberg-Marquardt algorithm has + // internal damping which mitigate this issue, but it is better to properly + // constrain the gauge freedom. This can be done by setting one of the poses + // as constant so the optimizer cannot change it. + std::map::iterator pose_start_iter = + poses->begin(); + CHECK(pose_start_iter != poses->end()) << "There are no poses."; + problem->SetParameterBlockConstant(&pose_start_iter->second.x); + problem->SetParameterBlockConstant(&pose_start_iter->second.y); + problem->SetParameterBlockConstant(&pose_start_iter->second.yaw_radians); +} + +// Returns true if the solve was successful. +bool SolveOptimizationProblem(ceres::Problem* problem) { + CHECK(problem != NULL); + + ceres::Solver::Options options; + options.max_num_iterations = 100; + options.linear_solver_type = ceres::SPARSE_NORMAL_CHOLESKY; + + ceres::Solver::Summary summary; + ceres::Solve(options, problem, &summary); + + std::cout << summary.FullReport() << '\n'; + + return summary.IsSolutionUsable(); +} + +// Output the poses to the file with format: ID x y yaw_radians. +bool OutputPoses(const std::string& filename, + const std::map& poses) { + std::fstream outfile; + outfile.open(filename.c_str(), std::istream::out); + if (!outfile) { + std::cerr << "Error opening the file: " << filename << '\n'; + return false; + } + for (std::map::const_iterator poses_iter = poses.begin(); + poses_iter != poses.end(); ++poses_iter) { + const std::map::value_type& pair = *poses_iter; + outfile << pair.first << " " << pair.second.x << " " << pair.second.y + << ' ' << pair.second.yaw_radians << '\n'; + } + return true; +} + +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + + CHECK(FLAGS_input != "") << "Need to specify the filename to read."; + + std::map poses; + std::vector constraints; + + CHECK(ceres::examples::ReadG2oFile(FLAGS_input, &poses, &constraints)) + << "Error reading the file: " << FLAGS_input; + + std::cout << "Number of poses: " << poses.size() << '\n'; + std::cout << "Number of constraints: " << constraints.size() << '\n'; + + CHECK(ceres::examples::OutputPoses("poses_original.txt", poses)) + << "Error outputting to poses_original.txt"; + + ceres::Problem problem; + ceres::examples::BuildOptimizationProblem(constraints, &poses, &problem); + + CHECK(ceres::examples::SolveOptimizationProblem(&problem)) + << "The solve was not successful, exiting."; + + CHECK(ceres::examples::OutputPoses("poses_optimized.txt", poses)) + << "Error outputting to poses_original.txt"; + + return 0; +} diff --git a/examples/slam/pose_graph_2d/pose_graph_2d_error_term.h b/examples/slam/pose_graph_2d/pose_graph_2d_error_term.h new file mode 100644 index 0000000..20656d2 --- /dev/null +++ b/examples/slam/pose_graph_2d/pose_graph_2d_error_term.h @@ -0,0 +1,112 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) +// +// Cost function for a 2D pose graph formulation. + +#ifndef CERES_EXAMPLES_POSE_GRAPH_2D_POSE_GRAPH_2D_ERROR_TERM_H_ +#define CERES_EXAMPLES_POSE_GRAPH_2D_POSE_GRAPH_2D_ERROR_TERM_H_ + +#include "Eigen/Core" + +namespace ceres { +namespace examples { + +template +Eigen::Matrix RotationMatrix2D(T yaw_radians) { + const T cos_yaw = ceres::cos(yaw_radians); + const T sin_yaw = ceres::sin(yaw_radians); + + Eigen::Matrix rotation; + rotation << cos_yaw, -sin_yaw, sin_yaw, cos_yaw; + return rotation; +} + +// Computes the error term for two poses that have a relative pose measurement +// between them. Let the hat variables be the measurement. +// +// residual = information^{1/2} * [ r_a^T * (p_b - p_a) - \hat{p_ab} ] +// [ Normalize(yaw_b - yaw_a - \hat{yaw_ab}) ] +// +// where r_a is the rotation matrix that rotates a vector represented in frame A +// into the global frame, and Normalize(*) ensures the angles are in the range +// [-pi, pi). +class PoseGraph2dErrorTerm { + public: + PoseGraph2dErrorTerm(double x_ab, double y_ab, double yaw_ab_radians, + const Eigen::Matrix3d& sqrt_information) + : p_ab_(x_ab, y_ab), + yaw_ab_radians_(yaw_ab_radians), + sqrt_information_(sqrt_information) {} + + template + bool operator()(const T* const x_a, const T* const y_a, const T* const yaw_a, + const T* const x_b, const T* const y_b, const T* const yaw_b, + T* residuals_ptr) const { + const Eigen::Matrix p_a(*x_a, *y_a); + const Eigen::Matrix p_b(*x_b, *y_b); + + Eigen::Map > residuals_map(residuals_ptr); + + residuals_map.template head<2>() = + RotationMatrix2D(*yaw_a).transpose() * (p_b - p_a) - + p_ab_.cast(); + residuals_map(2) = ceres::examples::NormalizeAngle( + (*yaw_b - *yaw_a) - static_cast(yaw_ab_radians_)); + + // Scale the residuals by the square root information matrix to account for + // the measurement uncertainty. + residuals_map = sqrt_information_.template cast() * residuals_map; + + return true; + } + + static ceres::CostFunction* Create(double x_ab, double y_ab, + double yaw_ab_radians, + const Eigen::Matrix3d& sqrt_information) { + return (new ceres::AutoDiffCostFunction(new PoseGraph2dErrorTerm( + x_ab, y_ab, yaw_ab_radians, sqrt_information))); + } + + EIGEN_MAKE_ALIGNED_OPERATOR_NEW + + private: + // The position of B relative to A in the A frame. + const Eigen::Vector2d p_ab_; + // The orientation of frame B relative to frame A. + const double yaw_ab_radians_; + // The inverse square root of the measurement covariance matrix. + const Eigen::Matrix3d sqrt_information_; +}; + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_POSE_GRAPH_2D_POSE_GRAPH_2D_ERROR_TERM_H_ diff --git a/examples/slam/pose_graph_2d/types.h b/examples/slam/pose_graph_2d/types.h new file mode 100644 index 0000000..a54d9bf --- /dev/null +++ b/examples/slam/pose_graph_2d/types.h @@ -0,0 +1,105 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) +// +// Defines the types used in the 2D pose graph SLAM formulation. Each vertex of +// the graph has a unique integer ID with a position and orientation. There are +// delta transformation constraints between two vertices. + +#ifndef CERES_EXAMPLES_POSE_GRAPH_2D_TYPES_H_ +#define CERES_EXAMPLES_POSE_GRAPH_2D_TYPES_H_ + +#include + +#include "Eigen/Core" +#include "normalize_angle.h" + +namespace ceres { +namespace examples { + +// The state for each vertex in the pose graph. +struct Pose2d { + double x; + double y; + double yaw_radians; + + // The name of the data type in the g2o file format. + static std::string name() { + return "VERTEX_SE2"; + } +}; + +std::istream& operator>>(std::istream& input, Pose2d& pose) { + input >> pose.x >> pose.y >> pose.yaw_radians; + // Normalize the angle between -pi to pi. + pose.yaw_radians = NormalizeAngle(pose.yaw_radians); + return input; +} + +// The constraint between two vertices in the pose graph. The constraint is the +// transformation from vertex id_begin to vertex id_end. +struct Constraint2d { + int id_begin; + int id_end; + + double x; + double y; + double yaw_radians; + + // The inverse of the covariance matrix for the measurement. The order of the + // entries are x, y, and yaw. + Eigen::Matrix3d information; + + // The name of the data type in the g2o file format. + static std::string name() { + return "EDGE_SE2"; + } +}; + +std::istream& operator>>(std::istream& input, Constraint2d& constraint) { + input >> constraint.id_begin >> constraint.id_end >> constraint.x >> + constraint.y >> constraint.yaw_radians >> + constraint.information(0, 0) >> constraint.information(0, 1) >> + constraint.information(0, 2) >> constraint.information(1, 1) >> + constraint.information(1, 2) >> constraint.information(2, 2); + + // Set the lower triangular part of the information matrix. + constraint.information(1, 0) = constraint.information(0, 1); + constraint.information(2, 0) = constraint.information(0, 2); + constraint.information(2, 1) = constraint.information(1, 2); + + // Normalize the angle between -pi to pi. + constraint.yaw_radians = NormalizeAngle(constraint.yaw_radians); + return input; +} + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_POSE_GRAPH_2D_TYPES_H_ diff --git a/examples/slam/pose_graph_3d/CMakeLists.txt b/examples/slam/pose_graph_3d/CMakeLists.txt new file mode 100644 index 0000000..2c5fdc3 --- /dev/null +++ b/examples/slam/pose_graph_3d/CMakeLists.txt @@ -0,0 +1,34 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2016 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: vitus@google.com (Michael Vitus) + +if (GFLAGS) + add_executable(pose_graph_3d pose_graph_3d.cc) + target_link_libraries(pose_graph_3d ceres ${GFLAGS_LIBRARIES}) +endif (GFLAGS) \ No newline at end of file diff --git a/examples/slam/pose_graph_3d/README.md b/examples/slam/pose_graph_3d/README.md new file mode 100644 index 0000000..a16aa09 --- /dev/null +++ b/examples/slam/pose_graph_3d/README.md @@ -0,0 +1,54 @@ +Pose Graph 3D +---------------- + +The Simultaneous Localization and Mapping (SLAM) problem consists of building a +map of an unknown environment while simultaneously localizing against this +map. The main difficulty of this problem stems from not having any additional +external aiding information such as GPS. SLAM has been considered one of the +fundamental challenges of robotics. A pose graph optimization problem is one +example of a SLAM problem. + +The example also illustrates how to use Eigen's geometry module with Ceres' +automatic differentiation functionality. To represent the orientation, we will +use Eigen's quaternion which uses the Hamiltonian convention but has different +element ordering as compared with Ceres's rotation representation. Specifically +they differ by whether the scalar component q_w is first or last; the element +order for Ceres's quaternion is [q_w, q_x, q_y, q_z] where as Eigen's quaternion +is [q_x, q_y, q_z, q_w]. + +This package defines the necessary Ceres cost functions needed to model the +3-dimensional pose graph optimization problem as well as a binary to build and +solve the problem. The cost functions are shown for instruction purposes and can +be speed up by using analytical derivatives which take longer to implement. + + +Running +----------- +This package includes an executable `pose_graph_3d` that will read a problem +definition file. This executable can work with any 3D problem definition that +uses the g2o format with quaternions used for the orientation representation. It +would be relatively straightforward to implement a new reader for a different +format such as TORO or others. `pose_graph_3d` will print the Ceres solver full +summary and then output to disk the original and optimized poses +(`poses_original.txt` and `poses_optimized.txt`, respectively) of the robot in +the following format: +``` +pose_id x y z q_x q_y q_z q_w +pose_id x y z q_x q_y q_z q_w +pose_id x y z q_x q_y q_z q_w +... +``` +where `pose_id` is the corresponding integer ID from the file definition. Note, +the file will be sorted in ascending order for the ```pose_id```. + +The executable `pose_graph_3d` expects the first argument to be the path to the +problem definition. To run the executable, +``` +/path/to/bin/pose_graph_3d /path/to/dataset/dataset.g2o +``` + +A script is provided to visualize the resulting output files. There is also an +option to enable equal axes using ```--axes_equal```. +``` +/path/to/repo/examples/slam/pose_graph_3d/plot_results.py --optimized_poses ./poses_optimized.txt --initial_poses ./poses_original.txt +``` diff --git a/examples/slam/pose_graph_3d/plot_results.py b/examples/slam/pose_graph_3d/plot_results.py new file mode 100755 index 0000000..defb9e6 --- /dev/null +++ b/examples/slam/pose_graph_3d/plot_results.py @@ -0,0 +1,80 @@ +#!/usr/bin/python +# +# Plots the results from the 3D pose graph optimization. It will draw a line +# between consecutive vertices. The commandline expects two optional filenames: +# +# ./plot_results.py --initial_poses filename --optimized_poses filename +# +# The files have the following format: +# ID x y z q_x q_y q_z q_w + +from mpl_toolkits.mplot3d import Axes3D +import matplotlib.pyplot as plot +import numpy +import sys +from optparse import OptionParser + +def set_axes_equal(axes): + ''' Sets the axes of a 3D plot to have equal scale. ''' + x_limits = axes.get_xlim3d() + y_limits = axes.get_ylim3d() + z_limits = axes.get_zlim3d() + + x_range = abs(x_limits[1] - x_limits[0]) + x_middle = numpy.mean(x_limits) + y_range = abs(y_limits[1] - y_limits[0]) + y_middle = numpy.mean(y_limits) + z_range = abs(z_limits[1] - z_limits[0]) + z_middle = numpy.mean(z_limits) + + length = 0.5 * max([x_range, y_range, z_range]) + + axes.set_xlim3d([x_middle - length, x_middle + length]) + axes.set_ylim3d([y_middle - length, y_middle + length]) + axes.set_zlim3d([z_middle - length, z_middle + length]) + +parser = OptionParser() +parser.add_option("--initial_poses", dest="initial_poses", + default="", help="The filename that contains the original poses.") +parser.add_option("--optimized_poses", dest="optimized_poses", + default="", help="The filename that contains the optimized poses.") +parser.add_option("-e", "--axes_equal", action="store_true", dest="axes_equal", + default="", help="Make the plot axes equal.") +(options, args) = parser.parse_args() + +# Read the original and optimized poses files. +poses_original = None +if options.initial_poses != '': + poses_original = numpy.genfromtxt(options.initial_poses, + usecols = (1, 2, 3)) + +poses_optimized = None +if options.optimized_poses != '': + poses_optimized = numpy.genfromtxt(options.optimized_poses, + usecols = (1, 2, 3)) + +# Plots the results for the specified poses. +figure = plot.figure() + +if poses_original is not None: + axes = plot.subplot(1, 2, 1, projection='3d') + plot.plot(poses_original[:, 0], poses_original[:, 1], poses_original[:, 2], + '-', alpha=0.5, color="green") + plot.title('Original') + if options.axes_equal: + axes.set_aspect('equal') + set_axes_equal(axes) + + +if poses_optimized is not None: + axes = plot.subplot(1, 2, 2, projection='3d') + plot.plot(poses_optimized[:, 0], poses_optimized[:, 1], poses_optimized[:, 2], + '-', alpha=0.5, color="blue") + plot.title('Optimized') + if options.axes_equal: + axes.set_aspect('equal') + set_axes_equal(plot.gca()) + + +# Show the plot and wait for the user to close. +plot.show() diff --git a/examples/slam/pose_graph_3d/pose_graph_3d.cc b/examples/slam/pose_graph_3d/pose_graph_3d.cc new file mode 100644 index 0000000..dcc85af --- /dev/null +++ b/examples/slam/pose_graph_3d/pose_graph_3d.cc @@ -0,0 +1,174 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) + +#include +#include +#include + +#include "ceres/ceres.h" +#include "common/read_g2o.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "pose_graph_3d_error_term.h" +#include "types.h" + +DEFINE_string(input, "", "The pose graph definition filename in g2o format."); + +namespace ceres { +namespace examples { + +// Constructs the nonlinear least squares optimization problem from the pose +// graph constraints. +void BuildOptimizationProblem(const VectorOfConstraints& constraints, + MapOfPoses* poses, ceres::Problem* problem) { + CHECK(poses != NULL); + CHECK(problem != NULL); + if (constraints.empty()) { + LOG(INFO) << "No constraints, no problem to optimize."; + return; + } + + ceres::LossFunction* loss_function = NULL; + ceres::LocalParameterization* quaternion_local_parameterization = + new EigenQuaternionParameterization; + + for (VectorOfConstraints::const_iterator constraints_iter = + constraints.begin(); + constraints_iter != constraints.end(); ++constraints_iter) { + const Constraint3d& constraint = *constraints_iter; + + MapOfPoses::iterator pose_begin_iter = poses->find(constraint.id_begin); + CHECK(pose_begin_iter != poses->end()) + << "Pose with ID: " << constraint.id_begin << " not found."; + MapOfPoses::iterator pose_end_iter = poses->find(constraint.id_end); + CHECK(pose_end_iter != poses->end()) + << "Pose with ID: " << constraint.id_end << " not found."; + + const Eigen::Matrix sqrt_information = + constraint.information.llt().matrixL(); + // Ceres will take ownership of the pointer. + ceres::CostFunction* cost_function = + PoseGraph3dErrorTerm::Create(constraint.t_be, sqrt_information); + + problem->AddResidualBlock(cost_function, loss_function, + pose_begin_iter->second.p.data(), + pose_begin_iter->second.q.coeffs().data(), + pose_end_iter->second.p.data(), + pose_end_iter->second.q.coeffs().data()); + + problem->SetParameterization(pose_begin_iter->second.q.coeffs().data(), + quaternion_local_parameterization); + problem->SetParameterization(pose_end_iter->second.q.coeffs().data(), + quaternion_local_parameterization); + } + + // The pose graph optimization problem has six DOFs that are not fully + // constrained. This is typically referred to as gauge freedom. You can apply + // a rigid body transformation to all the nodes and the optimization problem + // will still have the exact same cost. The Levenberg-Marquardt algorithm has + // internal damping which mitigates this issue, but it is better to properly + // constrain the gauge freedom. This can be done by setting one of the poses + // as constant so the optimizer cannot change it. + MapOfPoses::iterator pose_start_iter = poses->begin(); + CHECK(pose_start_iter != poses->end()) << "There are no poses."; + problem->SetParameterBlockConstant(pose_start_iter->second.p.data()); + problem->SetParameterBlockConstant(pose_start_iter->second.q.coeffs().data()); +} + +// Returns true if the solve was successful. +bool SolveOptimizationProblem(ceres::Problem* problem) { + CHECK(problem != NULL); + + ceres::Solver::Options options; + options.max_num_iterations = 200; + options.linear_solver_type = ceres::SPARSE_NORMAL_CHOLESKY; + + ceres::Solver::Summary summary; + ceres::Solve(options, problem, &summary); + + std::cout << summary.FullReport() << '\n'; + + return summary.IsSolutionUsable(); +} + +// Output the poses to the file with format: id x y z q_x q_y q_z q_w. +bool OutputPoses(const std::string& filename, const MapOfPoses& poses) { + std::fstream outfile; + outfile.open(filename.c_str(), std::istream::out); + if (!outfile) { + LOG(ERROR) << "Error opening the file: " << filename; + return false; + } + for (std::map, + Eigen::aligned_allocator > >:: + const_iterator poses_iter = poses.begin(); + poses_iter != poses.end(); ++poses_iter) { + const std::map, + Eigen::aligned_allocator > >:: + value_type& pair = *poses_iter; + outfile << pair.first << " " << pair.second.p.transpose() << " " + << pair.second.q.x() << " " << pair.second.q.y() << " " + << pair.second.q.z() << " " << pair.second.q.w() << '\n'; + } + return true; +} + +} // namespace examples +} // namespace ceres + +int main(int argc, char** argv) { + google::InitGoogleLogging(argv[0]); + CERES_GFLAGS_NAMESPACE::ParseCommandLineFlags(&argc, &argv, true); + + CHECK(FLAGS_input != "") << "Need to specify the filename to read."; + + ceres::examples::MapOfPoses poses; + ceres::examples::VectorOfConstraints constraints; + + CHECK(ceres::examples::ReadG2oFile(FLAGS_input, &poses, &constraints)) + << "Error reading the file: " << FLAGS_input; + + std::cout << "Number of poses: " << poses.size() << '\n'; + std::cout << "Number of constraints: " << constraints.size() << '\n'; + + CHECK(ceres::examples::OutputPoses("poses_original.txt", poses)) + << "Error outputting to poses_original.txt"; + + ceres::Problem problem; + ceres::examples::BuildOptimizationProblem(constraints, &poses, &problem); + + CHECK(ceres::examples::SolveOptimizationProblem(&problem)) + << "The solve was not successful, exiting."; + + CHECK(ceres::examples::OutputPoses("poses_optimized.txt", poses)) + << "Error outputting to poses_original.txt"; + + return 0; +} diff --git a/examples/slam/pose_graph_3d/pose_graph_3d_error_term.h b/examples/slam/pose_graph_3d/pose_graph_3d_error_term.h new file mode 100644 index 0000000..aca819e --- /dev/null +++ b/examples/slam/pose_graph_3d/pose_graph_3d_error_term.h @@ -0,0 +1,131 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) + +#ifndef EXAMPLES_CERES_POSE_GRAPH_3D_ERROR_TERM_H_ +#define EXAMPLES_CERES_POSE_GRAPH_3D_ERROR_TERM_H_ + +#include "Eigen/Core" +#include "ceres/autodiff_cost_function.h" + +#include "types.h" + +namespace ceres { +namespace examples { + +// Computes the error term for two poses that have a relative pose measurement +// between them. Let the hat variables be the measurement. We have two poses x_a +// and x_b. Through sensor measurements we can measure the transformation of +// frame B w.r.t frame A denoted as t_ab_hat. We can compute an error metric +// between the current estimate of the poses and the measurement. +// +// In this formulation, we have chosen to represent the rigid transformation as +// a Hamiltonian quaternion, q, and position, p. The quaternion ordering is +// [x, y, z, w]. + +// The estimated measurement is: +// t_ab = [ p_ab ] = [ R(q_a)^T * (p_b - p_a) ] +// [ q_ab ] [ q_a^{-1] * q_b ] +// +// where ^{-1} denotes the inverse and R(q) is the rotation matrix for the +// quaternion. Now we can compute an error metric between the estimated and +// measurement transformation. For the orientation error, we will use the +// standard multiplicative error resulting in: +// +// error = [ p_ab - \hat{p}_ab ] +// [ 2.0 * Vec(q_ab * \hat{q}_ab^{-1}) ] +// +// where Vec(*) returns the vector (imaginary) part of the quaternion. Since +// the measurement has an uncertainty associated with how accurate it is, we +// will weight the errors by the square root of the measurement information +// matrix: +// +// residuals = I^{1/2) * error +// where I is the information matrix which is the inverse of the covariance. +class PoseGraph3dErrorTerm { + public: + PoseGraph3dErrorTerm(const Pose3d& t_ab_measured, + const Eigen::Matrix& sqrt_information) + : t_ab_measured_(t_ab_measured), sqrt_information_(sqrt_information) {} + + template + bool operator()(const T* const p_a_ptr, const T* const q_a_ptr, + const T* const p_b_ptr, const T* const q_b_ptr, + T* residuals_ptr) const { + Eigen::Map > p_a(p_a_ptr); + Eigen::Map > q_a(q_a_ptr); + + Eigen::Map > p_b(p_b_ptr); + Eigen::Map > q_b(q_b_ptr); + + // Compute the relative transformation between the two frames. + Eigen::Quaternion q_a_inverse = q_a.conjugate(); + Eigen::Quaternion q_ab_estimated = q_a_inverse * q_b; + + // Represent the displacement between the two frames in the A frame. + Eigen::Matrix p_ab_estimated = q_a_inverse * (p_b - p_a); + + // Compute the error between the two orientation estimates. + Eigen::Quaternion delta_q = + t_ab_measured_.q.template cast() * q_ab_estimated.conjugate(); + + // Compute the residuals. + // [ position ] [ delta_p ] + // [ orientation (3x1)] = [ 2 * delta_q(0:2) ] + Eigen::Map > residuals(residuals_ptr); + residuals.template block<3, 1>(0, 0) = + p_ab_estimated - t_ab_measured_.p.template cast(); + residuals.template block<3, 1>(3, 0) = T(2.0) * delta_q.vec(); + + // Scale the residuals by the measurement uncertainty. + residuals.applyOnTheLeft(sqrt_information_.template cast()); + + return true; + } + + static ceres::CostFunction* Create( + const Pose3d& t_ab_measured, + const Eigen::Matrix& sqrt_information) { + return new ceres::AutoDiffCostFunction( + new PoseGraph3dErrorTerm(t_ab_measured, sqrt_information)); + } + + EIGEN_MAKE_ALIGNED_OPERATOR_NEW + + private: + // The measurement for the position of B relative to A in the A frame. + const Pose3d t_ab_measured_; + // The square root of the measurement information matrix. + const Eigen::Matrix sqrt_information_; +}; + +} // namespace examples +} // namespace ceres + +#endif // EXAMPLES_CERES_POSE_GRAPH_3D_ERROR_TERM_H_ diff --git a/examples/slam/pose_graph_3d/types.h b/examples/slam/pose_graph_3d/types.h new file mode 100644 index 0000000..2f12501 --- /dev/null +++ b/examples/slam/pose_graph_3d/types.h @@ -0,0 +1,114 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: vitus@google.com (Michael Vitus) + +#ifndef EXAMPLES_CERES_TYPES_H_ +#define EXAMPLES_CERES_TYPES_H_ + +#include +#include +#include +#include + +#include "Eigen/Core" +#include "Eigen/Geometry" + +namespace ceres { +namespace examples { + +struct Pose3d { + Eigen::Vector3d p; + Eigen::Quaterniond q; + + // The name of the data type in the g2o file format. + static std::string name() { + return "VERTEX_SE3:QUAT"; + } + + EIGEN_MAKE_ALIGNED_OPERATOR_NEW +}; + +std::istream& operator>>(std::istream& input, Pose3d& pose) { + input >> pose.p.x() >> pose.p.y() >> pose.p.z() >> pose.q.x() >> + pose.q.y() >> pose.q.z() >> pose.q.w(); + // Normalize the quaternion to account for precision loss due to + // serialization. + pose.q.normalize(); + return input; +} + +typedef std::map, + Eigen::aligned_allocator > > + MapOfPoses; + +// The constraint between two vertices in the pose graph. The constraint is the +// transformation from vertex id_begin to vertex id_end. +struct Constraint3d { + int id_begin; + int id_end; + + // The transformation that represents the pose of the end frame E w.r.t. the + // begin frame B. In other words, it transforms a vector in the E frame to + // the B frame. + Pose3d t_be; + + // The inverse of the covariance matrix for the measurement. The order of the + // entries are x, y, z, delta orientation. + Eigen::Matrix information; + + // The name of the data type in the g2o file format. + static std::string name() { + return "EDGE_SE3:QUAT"; + } + + EIGEN_MAKE_ALIGNED_OPERATOR_NEW +}; + +std::istream& operator>>(std::istream& input, Constraint3d& constraint) { + Pose3d& t_be = constraint.t_be; + input >> constraint.id_begin >> constraint.id_end >> t_be; + + for (int i = 0; i < 6 && input.good(); ++i) { + for (int j = i; j < 6 && input.good(); ++j) { + input >> constraint.information(i, j); + if (i != j) { + constraint.information(j, i) = constraint.information(i, j); + } + } + } + return input; +} + +typedef std::vector > + VectorOfConstraints; + +} // namespace examples +} // namespace ceres + +#endif // EXAMPLES_CERES_TYPES_H_ diff --git a/examples/snavely_reprojection_error.h b/examples/snavely_reprojection_error.h new file mode 100644 index 0000000..5e51eb4 --- /dev/null +++ b/examples/snavely_reprojection_error.h @@ -0,0 +1,177 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Templated struct implementing the camera model and residual +// computation for bundle adjustment used by Noah Snavely's Bundler +// SfM system. This is also the camera model/residual for the bundle +// adjustment problems in the BAL dataset. It is templated so that we +// can use Ceres's automatic differentiation to compute analytic +// jacobians. +// +// For details see: http://phototour.cs.washington.edu/bundler/ +// and http://grail.cs.washington.edu/projects/bal/ + +#ifndef CERES_EXAMPLES_SNAVELY_REPROJECTION_ERROR_H_ +#define CERES_EXAMPLES_SNAVELY_REPROJECTION_ERROR_H_ + +#include "ceres/rotation.h" + +namespace ceres { +namespace examples { + +// Templated pinhole camera model for used with Ceres. The camera is +// parameterized using 9 parameters: 3 for rotation, 3 for translation, 1 for +// focal length and 2 for radial distortion. The principal point is not modeled +// (i.e. it is assumed be located at the image center). +struct SnavelyReprojectionError { + SnavelyReprojectionError(double observed_x, double observed_y) + : observed_x(observed_x), observed_y(observed_y) {} + + template + bool operator()(const T* const camera, + const T* const point, + T* residuals) const { + // camera[0,1,2] are the angle-axis rotation. + T p[3]; + AngleAxisRotatePoint(camera, point, p); + + // camera[3,4,5] are the translation. + p[0] += camera[3]; + p[1] += camera[4]; + p[2] += camera[5]; + + // Compute the center of distortion. The sign change comes from + // the camera model that Noah Snavely's Bundler assumes, whereby + // the camera coordinate system has a negative z axis. + const T xp = - p[0] / p[2]; + const T yp = - p[1] / p[2]; + + // Apply second and fourth order radial distortion. + const T& l1 = camera[7]; + const T& l2 = camera[8]; + const T r2 = xp*xp + yp*yp; + const T distortion = 1.0 + r2 * (l1 + l2 * r2); + + + // Compute final projected point position. + const T& focal = camera[6]; + const T predicted_x = focal * distortion * xp; + const T predicted_y = focal * distortion * yp; + + // The error is the difference between the predicted and observed position. + residuals[0] = predicted_x - observed_x; + residuals[1] = predicted_y - observed_y; + + return true; + } + + // Factory to hide the construction of the CostFunction object from + // the client code. + static ceres::CostFunction* Create(const double observed_x, + const double observed_y) { + return (new ceres::AutoDiffCostFunction( + new SnavelyReprojectionError(observed_x, observed_y))); + } + + double observed_x; + double observed_y; +}; + +// Templated pinhole camera model for used with Ceres. The camera is +// parameterized using 10 parameters. 4 for rotation, 3 for +// translation, 1 for focal length and 2 for radial distortion. The +// principal point is not modeled (i.e. it is assumed be located at +// the image center). +struct SnavelyReprojectionErrorWithQuaternions { + // (u, v): the position of the observation with respect to the image + // center point. + SnavelyReprojectionErrorWithQuaternions(double observed_x, double observed_y) + : observed_x(observed_x), observed_y(observed_y) {} + + template + bool operator()(const T* const camera, + const T* const point, + T* residuals) const { + // camera[0,1,2,3] is are the rotation of the camera as a quaternion. + // + // We use QuaternionRotatePoint as it does not assume that the + // quaternion is normalized, since one of the ways to run the + // bundle adjuster is to let Ceres optimize all 4 quaternion + // parameters without a local parameterization. + T p[3]; + QuaternionRotatePoint(camera, point, p); + + p[0] += camera[4]; + p[1] += camera[5]; + p[2] += camera[6]; + + // Compute the center of distortion. The sign change comes from + // the camera model that Noah Snavely's Bundler assumes, whereby + // the camera coordinate system has a negative z axis. + const T xp = - p[0] / p[2]; + const T yp = - p[1] / p[2]; + + // Apply second and fourth order radial distortion. + const T& l1 = camera[8]; + const T& l2 = camera[9]; + + const T r2 = xp*xp + yp*yp; + const T distortion = 1.0 + r2 * (l1 + l2 * r2); + + // Compute final projected point position. + const T& focal = camera[7]; + const T predicted_x = focal * distortion * xp; + const T predicted_y = focal * distortion * yp; + + // The error is the difference between the predicted and observed position. + residuals[0] = predicted_x - observed_x; + residuals[1] = predicted_y - observed_y; + + return true; + } + + // Factory to hide the construction of the CostFunction object from + // the client code. + static ceres::CostFunction* Create(const double observed_x, + const double observed_y) { + return (new ceres::AutoDiffCostFunction< + SnavelyReprojectionErrorWithQuaternions, 2, 10, 3>( + new SnavelyReprojectionErrorWithQuaternions(observed_x, + observed_y))); + } + + double observed_x; + double observed_y; +}; + +} // namespace examples +} // namespace ceres + +#endif // CERES_EXAMPLES_SNAVELY_REPROJECTION_ERROR_H_ diff --git a/include/ceres/autodiff_cost_function.h b/include/ceres/autodiff_cost_function.h new file mode 100644 index 0000000..e7893e4 --- /dev/null +++ b/include/ceres/autodiff_cost_function.h @@ -0,0 +1,227 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Create CostFunctions as needed by the least squares framework, with +// Jacobians computed via automatic differentiation. For more +// information on automatic differentation, see the wikipedia article +// at http://en.wikipedia.org/wiki/Automatic_differentiation +// +// To get an auto differentiated cost function, you must define a class with a +// templated operator() (a functor) that computes the cost function in terms of +// the template parameter T. The autodiff framework substitutes appropriate +// "jet" objects for T in order to compute the derivative when necessary, but +// this is hidden, and you should write the function as if T were a scalar type +// (e.g. a double-precision floating point number). +// +// The function must write the computed value in the last argument +// (the only non-const one) and return true to indicate +// success. Please see cost_function.h for details on how the return +// value maybe used to impose simple constraints on the parameter +// block. +// +// For example, consider a scalar error e = k - x'y, where both x and y are +// two-dimensional column vector parameters, the prime sign indicates +// transposition, and k is a constant. The form of this error, which is the +// difference between a constant and an expression, is a common pattern in least +// squares problems. For example, the value x'y might be the model expectation +// for a series of measurements, where there is an instance of the cost function +// for each measurement k. +// +// The actual cost added to the total problem is e^2, or (k - x'k)^2; however, +// the squaring is implicitly done by the optimization framework. +// +// To write an auto-differentiable cost function for the above model, first +// define the object +// +// class MyScalarCostFunctor { +// MyScalarCostFunctor(double k): k_(k) {} +// +// template +// bool operator()(const T* const x , const T* const y, T* e) const { +// e[0] = T(k_) - x[0] * y[0] + x[1] * y[1]; +// return true; +// } +// +// private: +// double k_; +// }; +// +// Note that in the declaration of operator() the input parameters x and y come +// first, and are passed as const pointers to arrays of T. If there were three +// input parameters, then the third input parameter would come after y. The +// output is always the last parameter, and is also a pointer to an array. In +// the example above, e is a scalar, so only e[0] is set. +// +// Then given this class definition, the auto differentiated cost function for +// it can be constructed as follows. +// +// CostFunction* cost_function +// = new AutoDiffCostFunction( +// new MyScalarCostFunctor(1.0)); ^ ^ ^ +// | | | +// Dimension of residual -----+ | | +// Dimension of x ---------------+ | +// Dimension of y ------------------+ +// +// In this example, there is usually an instance for each measumerent of k. +// +// In the instantiation above, the template parameters following +// "MyScalarCostFunctor", "1, 2, 2", describe the functor as computing a +// 1-dimensional output from two arguments, both 2-dimensional. +// +// AutoDiffCostFunction also supports cost functions with a +// runtime-determined number of residuals. For example: +// +// CostFunction* cost_function +// = new AutoDiffCostFunction( +// new CostFunctorWithDynamicNumResiduals(1.0), ^ ^ ^ +// runtime_number_of_residuals); <----+ | | | +// | | | | +// | | | | +// Actual number of residuals ------+ | | | +// Indicate dynamic number of residuals --------+ | | +// Dimension of x ------------------------------------+ | +// Dimension of y ---------------------------------------+ +// +// The framework can currently accommodate cost functions of up to 10 +// independent variables, and there is no limit on the dimensionality +// of each of them. +// +// WARNING #1: Since the functor will get instantiated with different types for +// T, you must to convert from other numeric types to T before mixing +// computations with other variables of type T. In the example above, this is +// seen where instead of using k_ directly, k_ is wrapped with T(k_). +// +// WARNING #2: A common beginner's error when first using autodiff cost +// functions is to get the sizing wrong. In particular, there is a tendency to +// set the template parameters to (dimension of residual, number of parameters) +// instead of passing a dimension parameter for *every parameter*. In the +// example above, that would be , which is missing +// the last '2' argument. Please be careful when setting the size parameters. + +#ifndef CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_ +#define CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_ + +#include "ceres/internal/autodiff.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/sized_cost_function.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { + +// A cost function which computes the derivative of the cost with respect to +// the parameters (a.k.a. the jacobian) using an autodifferentiation framework. +// The first template argument is the functor object, described in the header +// comment. The second argument is the dimension of the residual (or +// ceres::DYNAMIC to indicate it will be set at runtime), and subsequent +// arguments describe the size of the Nth parameter, one per parameter. +// +// The constructors take ownership of the cost functor. +// +// If the number of residuals (argument kNumResiduals below) is +// ceres::DYNAMIC, then the two-argument constructor must be used. The +// second constructor takes a number of residuals (in addition to the +// templated number of residuals). This allows for varying the number +// of residuals for a single autodiff cost function at runtime. +template // Number of parameters in block 9. +class AutoDiffCostFunction : public SizedCostFunction { + public: + // Takes ownership of functor. Uses the template-provided value for the + // number of residuals ("kNumResiduals"). + explicit AutoDiffCostFunction(CostFunctor* functor) + : functor_(functor) { + CHECK_NE(kNumResiduals, DYNAMIC) + << "Can't run the fixed-size constructor if the " + << "number of residuals is set to ceres::DYNAMIC."; + } + + // Takes ownership of functor. Ignores the template-provided + // kNumResiduals in favor of the "num_residuals" argument provided. + // + // This allows for having autodiff cost functions which return varying + // numbers of residuals at runtime. + AutoDiffCostFunction(CostFunctor* functor, int num_residuals) + : functor_(functor) { + CHECK_EQ(kNumResiduals, DYNAMIC) + << "Can't run the dynamic-size constructor if the " + << "number of residuals is not ceres::DYNAMIC."; + SizedCostFunction + ::set_num_residuals(num_residuals); + } + + virtual ~AutoDiffCostFunction() {} + + // Implementation details follow; clients of the autodiff cost function should + // not have to examine below here. + // + // To handle varardic cost functions, some template magic is needed. It's + // mostly hidden inside autodiff.h. + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + if (!jacobians) { + return internal::VariadicEvaluate< + CostFunctor, double, N0, N1, N2, N3, N4, N5, N6, N7, N8, N9> + ::Call(*functor_, parameters, residuals); + } + return internal::AutoDiff::Differentiate( + *functor_, + parameters, + SizedCostFunction::num_residuals(), + residuals, + jacobians); + } + + private: + internal::scoped_ptr functor_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_AUTODIFF_COST_FUNCTION_H_ diff --git a/include/ceres/autodiff_local_parameterization.h b/include/ceres/autodiff_local_parameterization.h new file mode 100644 index 0000000..27397e2 --- /dev/null +++ b/include/ceres/autodiff_local_parameterization.h @@ -0,0 +1,154 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sergey.vfx@gmail.com (Sergey Sharybin) +// mierle@gmail.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_ +#define CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_ + +#include "ceres/local_parameterization.h" +#include "ceres/internal/autodiff.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { + +// Create local parameterization with Jacobians computed via automatic +// differentiation. For more information on local parameterizations, +// see include/ceres/local_parameterization.h +// +// To get an auto differentiated local parameterization, you must define +// a class with a templated operator() (a functor) that computes +// +// x_plus_delta = Plus(x, delta); +// +// the template parameter T. The autodiff framework substitutes appropriate +// "Jet" objects for T in order to compute the derivative when necessary, but +// this is hidden, and you should write the function as if T were a scalar type +// (e.g. a double-precision floating point number). +// +// The function must write the computed value in the last argument (the only +// non-const one) and return true to indicate success. +// +// For example, Quaternions have a three dimensional local +// parameterization. It's plus operation can be implemented as (taken +// from internal/ceres/auto_diff_local_parameterization_test.cc) +// +// struct QuaternionPlus { +// template +// bool operator()(const T* x, const T* delta, T* x_plus_delta) const { +// const T squared_norm_delta = +// delta[0] * delta[0] + delta[1] * delta[1] + delta[2] * delta[2]; +// +// T q_delta[4]; +// if (squared_norm_delta > T(0.0)) { +// T norm_delta = sqrt(squared_norm_delta); +// const T sin_delta_by_delta = sin(norm_delta) / norm_delta; +// q_delta[0] = cos(norm_delta); +// q_delta[1] = sin_delta_by_delta * delta[0]; +// q_delta[2] = sin_delta_by_delta * delta[1]; +// q_delta[3] = sin_delta_by_delta * delta[2]; +// } else { +// // We do not just use q_delta = [1,0,0,0] here because that is a +// // constant and when used for automatic differentiation will +// // lead to a zero derivative. Instead we take a first order +// // approximation and evaluate it at zero. +// q_delta[0] = T(1.0); +// q_delta[1] = delta[0]; +// q_delta[2] = delta[1]; +// q_delta[3] = delta[2]; +// } +// +// QuaternionProduct(q_delta, x, x_plus_delta); +// return true; +// } +// }; +// +// Then given this struct, the auto differentiated local +// parameterization can now be constructed as +// +// LocalParameterization* local_parameterization = +// new AutoDiffLocalParameterization; +// | | +// Global Size ---------------+ | +// Local Size -------------------+ +// +// WARNING: Since the functor will get instantiated with different types for +// T, you must to convert from other numeric types to T before mixing +// computations with other variables of type T. In the example above, this is +// seen where instead of using k_ directly, k_ is wrapped with T(k_). + +template +class AutoDiffLocalParameterization : public LocalParameterization { + public: + AutoDiffLocalParameterization() : + functor_(new Functor()) {} + + // Takes ownership of functor. + explicit AutoDiffLocalParameterization(Functor* functor) : + functor_(functor) {} + + virtual ~AutoDiffLocalParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const { + return (*functor_)(x, delta, x_plus_delta); + } + + virtual bool ComputeJacobian(const double* x, double* jacobian) const { + double zero_delta[kLocalSize]; + for (int i = 0; i < kLocalSize; ++i) { + zero_delta[i] = 0.0; + } + + double x_plus_delta[kGlobalSize]; + for (int i = 0; i < kGlobalSize; ++i) { + x_plus_delta[i] = 0.0; + } + + const double* parameter_ptrs[2] = {x, zero_delta}; + double* jacobian_ptrs[2] = { NULL, jacobian }; + return internal::AutoDiff + ::Differentiate(*functor_, + parameter_ptrs, + kGlobalSize, + x_plus_delta, + jacobian_ptrs); + } + + virtual int GlobalSize() const { return kGlobalSize; } + virtual int LocalSize() const { return kLocalSize; } + + private: + internal::scoped_ptr functor_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_AUTODIFF_LOCAL_PARAMETERIZATION_H_ diff --git a/include/ceres/c_api.h b/include/ceres/c_api.h new file mode 100644 index 0000000..df7c9b6 --- /dev/null +++ b/include/ceres/c_api.h @@ -0,0 +1,146 @@ +/* Ceres Solver - A fast non-linear least squares minimizer + * Copyright 2015 Google Inc. All rights reserved. + * http://ceres-solver.org/ + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither the name of Google Inc. nor the names of its contributors may be + * used to endorse or promote products derived from this software without + * specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + * + * Author: mierle@gmail.com (Keir Mierle) + * + * A minimal C API for Ceres. Not all functionality is included. This API is + * not intended for clients of Ceres, but is instead intended for easing the + * process of binding Ceres to other languages. + * + * Currently this is a work in progress. + */ + +#ifndef CERES_PUBLIC_C_API_H_ +#define CERES_PUBLIC_C_API_H_ + +#include "ceres/internal/port.h" +#include "ceres/internal/disable_warnings.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* Init the Ceres private data. Must be called before anything else. */ +CERES_EXPORT void ceres_init(); + +/* Equivalent to CostFunction::Evaluate() in the C++ API. + * + * The user may keep private information inside the opaque user_data object. + * The pointer here is the same one passed in the ceres_add_residual_block(). + */ +typedef int (*ceres_cost_function_t)(void* user_data, + double** parameters, + double* residuals, + double** jacobians); + +/* Equivalent to LossFunction::Evaluate() from the C++ API. */ +typedef void (*ceres_loss_function_t)(void* user_data, + double squared_norm, + double out[3]); + +/* Create callback data for Ceres' stock loss functions. + * + * Ceres has several loss functions available by default, and these functions + * expose those to the C API. To use the stock loss functions, call + * ceres_create_*_loss_data(), which internally creates an instance of one of + * the stock loss functions (for example ceres::CauchyLoss), and pass the + * returned "loss_function_data" along with the ceres_stock_loss_function to + * ceres_add_residual_block(). + * + * For example: + * + * void* cauchy_loss_function_data = + * ceres_create_cauchy_loss_function_data(1.2, 0.0); + * ceres_problem_add_residual_block( + * problem, + * my_cost_function, + * my_cost_function_data, + * ceres_stock_loss_function, + * cauchy_loss_function_data, + * 1, + * 2, + * parameter_sizes, + * parameter_pointers); + * ... + * ceres_free_stock_loss_function_data(cauchy_loss_function_data); + * + * See loss_function.h for the details of each loss function. + */ +CERES_EXPORT void* ceres_create_huber_loss_function_data(double a); +CERES_EXPORT void* ceres_create_softl1_loss_function_data(double a); +CERES_EXPORT void* ceres_create_cauchy_loss_function_data(double a); +CERES_EXPORT void* ceres_create_arctan_loss_function_data(double a); +CERES_EXPORT void* ceres_create_tolerant_loss_function_data(double a, double b); + +/* Free the given stock loss function data. */ +CERES_EXPORT void ceres_free_stock_loss_function_data(void* loss_function_data); + +/* This is an implementation of ceres_loss_function_t contained within Ceres + * itself, intended as a way to access the various stock Ceres loss functions + * from the C API. This should be passed to ceres_add_residual() below, in + * combination with a user_data pointer generated by + * ceres_create_stock_loss_function() above. */ +CERES_EXPORT void ceres_stock_loss_function(void* user_data, + double squared_norm, + double out[3]); + +/* Equivalent to Problem from the C++ API. */ +struct ceres_problem_s; +typedef struct ceres_problem_s ceres_problem_t; + +struct ceres_residual_block_id_s; +typedef struct ceres_residual_block_id_s ceres_residual_block_id_t; + +/* Create and destroy a problem */ +/* TODO(keir): Add options for the problem. */ +CERES_EXPORT ceres_problem_t* ceres_create_problem(); +CERES_EXPORT void ceres_free_problem(ceres_problem_t* problem); + +/* Add a residual block. */ +CERES_EXPORT ceres_residual_block_id_t* ceres_problem_add_residual_block( + ceres_problem_t* problem, + ceres_cost_function_t cost_function, + void* cost_function_data, + ceres_loss_function_t loss_function, + void* loss_function_data, + int num_residuals, + int num_parameter_blocks, + int* parameter_block_sizes, + double** parameters); + +CERES_EXPORT void ceres_solve(ceres_problem_t* problem); + +/* TODO(keir): Figure out a way to pass a config in. */ + +#ifdef __cplusplus +} +#endif + +#include "ceres/internal/reenable_warnings.h" + +#endif /* CERES_PUBLIC_C_API_H_ */ diff --git a/include/ceres/ceres.h b/include/ceres/ceres.h new file mode 100644 index 0000000..64ffb99 --- /dev/null +++ b/include/ceres/ceres.h @@ -0,0 +1,59 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// This is a forwarding header containing the public symbols exported from +// Ceres. Anything in the "ceres" namespace is available for use. + +#ifndef CERES_PUBLIC_CERES_H_ +#define CERES_PUBLIC_CERES_H_ + +#include "ceres/autodiff_cost_function.h" +#include "ceres/autodiff_local_parameterization.h" +#include "ceres/cost_function.h" +#include "ceres/cost_function_to_functor.h" +#include "ceres/covariance.h" +#include "ceres/crs_matrix.h" +#include "ceres/dynamic_autodiff_cost_function.h" +#include "ceres/dynamic_numeric_diff_cost_function.h" +#include "ceres/gradient_problem.h" +#include "ceres/gradient_problem_solver.h" +#include "ceres/iteration_callback.h" +#include "ceres/jet.h" +#include "ceres/local_parameterization.h" +#include "ceres/loss_function.h" +#include "ceres/numeric_diff_cost_function.h" +#include "ceres/ordered_groups.h" +#include "ceres/problem.h" +#include "ceres/sized_cost_function.h" +#include "ceres/solver.h" +#include "ceres/types.h" +#include "ceres/version.h" + +#endif // CERES_PUBLIC_CERES_H_ diff --git a/include/ceres/conditioned_cost_function.h b/include/ceres/conditioned_cost_function.h new file mode 100644 index 0000000..29597d9 --- /dev/null +++ b/include/ceres/conditioned_cost_function.h @@ -0,0 +1,99 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: wjr@google.com (William Rucklidge) +// +// This file contains a cost function that can apply a transformation to +// each residual value before they are square-summed. + +#ifndef CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_ +#define CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_ + +#include + +#include "ceres/cost_function.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// This class allows you to apply different conditioning to the residual +// values of a wrapped cost function. An example where this is useful is +// where you have an existing cost function that produces N values, but you +// want the total cost to be something other than just the sum of these +// squared values - maybe you want to apply a different scaling to some +// values, to change their contribution to the cost. +// +// Usage: +// +// // my_cost_function produces N residuals +// CostFunction* my_cost_function = ... +// CHECK_EQ(N, my_cost_function->num_residuals()); +// vector conditioners; +// +// // Make N 1x1 cost functions (1 parameter, 1 residual) +// CostFunction* f_1 = ... +// conditioners.push_back(f_1); +// ... +// CostFunction* f_N = ... +// conditioners.push_back(f_N); +// ConditionedCostFunction* ccf = +// new ConditionedCostFunction(my_cost_function, conditioners); +// +// Now ccf's residual i (i=0..N-1) will be passed though the i'th conditioner. +// +// ccf_residual[i] = f_i(my_cost_function_residual[i]) +// +// and the Jacobian will be affected appropriately. +class CERES_EXPORT ConditionedCostFunction : public CostFunction { + public: + // Builds a cost function based on a wrapped cost function, and a + // per-residual conditioner. Takes ownership of all of the wrapped cost + // functions, or not, depending on the ownership parameter. Conditioners + // may be NULL, in which case the corresponding residual is not modified. + ConditionedCostFunction(CostFunction* wrapped_cost_function, + const std::vector& conditioners, + Ownership ownership); + virtual ~ConditionedCostFunction(); + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + + private: + internal::scoped_ptr wrapped_cost_function_; + std::vector conditioners_; + Ownership ownership_; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_CONDITIONED_COST_FUNCTION_H_ diff --git a/include/ceres/cost_function.h b/include/ceres/cost_function.h new file mode 100644 index 0000000..f051a89 --- /dev/null +++ b/include/ceres/cost_function.h @@ -0,0 +1,147 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// keir@google.m (Keir Mierle) +// +// This is the interface through which the least squares solver accesses the +// residual and Jacobian of the least squares problem. Users are expected to +// subclass CostFunction to define their own terms in the least squares problem. +// +// It is recommended that users define templated residual functors for use as +// arguments for AutoDiffCostFunction (see autodiff_cost_function.h), instead of +// directly implementing the CostFunction interface. This often results in both +// shorter code and faster execution than hand-coded derivatives. However, +// specialized cases may demand direct implementation of the lower-level +// CostFunction interface; for example, this is true when calling legacy code +// which is not templated on numeric types. + +#ifndef CERES_PUBLIC_COST_FUNCTION_H_ +#define CERES_PUBLIC_COST_FUNCTION_H_ + +#include +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// This class implements the computation of the cost (a.k.a. residual) terms as +// a function of the input (control) variables, and is the interface for users +// to describe their least squares problem to Ceres. In other words, this is the +// modelling layer between users and the Ceres optimizer. The signature of the +// function (number and sizes of input parameter blocks and number of outputs) +// is stored in parameter_block_sizes_ and num_residuals_ respectively. User +// code inheriting from this class is expected to set these two members with the +// corresponding accessors. This information will be verified by the Problem +// when added with AddResidualBlock(). +class CERES_EXPORT CostFunction { + public: + CostFunction() : num_residuals_(0) {} + + virtual ~CostFunction() {} + + // Inputs: + // + // parameters is an array of pointers to arrays containing the + // various parameter blocks. parameters has the same number of + // elements as parameter_block_sizes_. Parameter blocks are in the + // same order as parameter_block_sizes_.i.e., + // + // parameters_[i] = double[parameter_block_sizes_[i]] + // + // Outputs: + // + // residuals is an array of size num_residuals_. + // + // jacobians is an array of size parameter_block_sizes_ containing + // pointers to storage for jacobian blocks corresponding to each + // parameter block. Jacobian blocks are in the same order as + // parameter_block_sizes, i.e. jacobians[i], is an + // array that contains num_residuals_* parameter_block_sizes_[i] + // elements. Each jacobian block is stored in row-major order, i.e., + // + // jacobians[i][r*parameter_block_size_[i] + c] = + // d residual[r] / d parameters[i][c] + // + // If jacobians is NULL, then no derivatives are returned; this is + // the case when computing cost only. If jacobians[i] is NULL, then + // the jacobian block corresponding to the i'th parameter block must + // not to be returned. + // + // The return value indicates whether the computation of the + // residuals and/or jacobians was successful or not. + // + // This can be used to communicate numerical failures in jacobian + // computations for instance. + // + // A more interesting and common use is to impose constraints on the + // parameters. If the initial values of the parameter blocks satisfy + // the constraints, then returning false whenever the constraints + // are not satisfied will prevent the solver from moving into the + // infeasible region. This is not a very sophisticated mechanism for + // enforcing constraints, but is often good enough. + // + // Note that it is important that the initial values of the + // parameter block must be feasible, otherwise the solver will + // declare a numerical problem at iteration 0. + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const = 0; + + const std::vector& parameter_block_sizes() const { + return parameter_block_sizes_; + } + + int num_residuals() const { + return num_residuals_; + } + + protected: + std::vector* mutable_parameter_block_sizes() { + return ¶meter_block_sizes_; + } + + void set_num_residuals(int num_residuals) { + num_residuals_ = num_residuals; + } + + private: + // Cost function signature metadata: number of inputs & their sizes, + // number of outputs (residuals). + std::vector parameter_block_sizes_; + int num_residuals_; + CERES_DISALLOW_COPY_AND_ASSIGN(CostFunction); +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_COST_FUNCTION_H_ diff --git a/include/ceres/cost_function_to_functor.h b/include/ceres/cost_function_to_functor.h new file mode 100644 index 0000000..d2dc947 --- /dev/null +++ b/include/ceres/cost_function_to_functor.h @@ -0,0 +1,683 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// CostFunctionToFunctor is an adapter class that allows users to use +// SizedCostFunction objects in templated functors which are to be used for +// automatic differentiation. This allows the user to seamlessly mix +// analytic, numeric and automatic differentiation. +// +// For example, let us assume that +// +// class IntrinsicProjection : public SizedCostFunction<2, 5, 3> { +// public: +// IntrinsicProjection(const double* observation); +// virtual bool Evaluate(double const* const* parameters, +// double* residuals, +// double** jacobians) const; +// }; +// +// is a cost function that implements the projection of a point in its +// local coordinate system onto its image plane and subtracts it from +// the observed point projection. It can compute its residual and +// either via analytic or numerical differentiation can compute its +// jacobians. +// +// Now we would like to compose the action of this CostFunction with +// the action of camera extrinsics, i.e., rotation and +// translation. Say we have a templated function +// +// template +// void RotateAndTranslatePoint(const T* rotation, +// const T* translation, +// const T* point, +// T* result); +// +// Then we can now do the following, +// +// struct CameraProjection { +// CameraProjection(const double* observation) +// : intrinsic_projection_(new IntrinsicProjection(observation)) { +// } +// template +// bool operator()(const T* rotation, +// const T* translation, +// const T* intrinsics, +// const T* point, +// T* residual) const { +// T transformed_point[3]; +// RotateAndTranslatePoint(rotation, translation, point, transformed_point); +// +// // Note that we call intrinsic_projection_, just like it was +// // any other templated functor. +// +// return intrinsic_projection_(intrinsics, transformed_point, residual); +// } +// +// private: +// CostFunctionToFunctor<2,5,3> intrinsic_projection_; +// }; + +#ifndef CERES_PUBLIC_COST_FUNCTION_TO_FUNCTOR_H_ +#define CERES_PUBLIC_COST_FUNCTION_TO_FUNCTOR_H_ + +#include +#include + +#include "ceres/cost_function.h" +#include "ceres/dynamic_cost_function_to_functor.h" +#include "ceres/internal/fixed_array.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { + +template +class CostFunctionToFunctor { + public: + // Takes ownership of cost_function. + explicit CostFunctionToFunctor(CostFunction* cost_function) + : cost_functor_(cost_function) { + CHECK_NOTNULL(cost_function); + CHECK(kNumResiduals > 0 || kNumResiduals == DYNAMIC); + + // This block breaks the 80 column rule to keep it somewhat readable. + CHECK((!N1 && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && (N2 > 0) && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && (N9 > 0))) // NOLINT + << "Zero block cannot precede a non-zero block. Block sizes are " + << "(ignore trailing 0s): " << N0 << ", " << N1 << ", " << N2 << ", " + << N3 << ", " << N4 << ", " << N5 << ", " << N6 << ", " << N7 << ", " + << N8 << ", " << N9; + + const std::vector& parameter_block_sizes = + cost_function->parameter_block_sizes(); + const int num_parameter_blocks = + (N0 > 0) + (N1 > 0) + (N2 > 0) + (N3 > 0) + (N4 > 0) + + (N5 > 0) + (N6 > 0) + (N7 > 0) + (N8 > 0) + (N9 > 0); + CHECK_EQ(static_cast(parameter_block_sizes.size()), + num_parameter_blocks); + + CHECK_EQ(N0, parameter_block_sizes[0]); + if (parameter_block_sizes.size() > 1) CHECK_EQ(N1, parameter_block_sizes[1]); // NOLINT + if (parameter_block_sizes.size() > 2) CHECK_EQ(N2, parameter_block_sizes[2]); // NOLINT + if (parameter_block_sizes.size() > 3) CHECK_EQ(N3, parameter_block_sizes[3]); // NOLINT + if (parameter_block_sizes.size() > 4) CHECK_EQ(N4, parameter_block_sizes[4]); // NOLINT + if (parameter_block_sizes.size() > 5) CHECK_EQ(N5, parameter_block_sizes[5]); // NOLINT + if (parameter_block_sizes.size() > 6) CHECK_EQ(N6, parameter_block_sizes[6]); // NOLINT + if (parameter_block_sizes.size() > 7) CHECK_EQ(N7, parameter_block_sizes[7]); // NOLINT + if (parameter_block_sizes.size() > 8) CHECK_EQ(N8, parameter_block_sizes[8]); // NOLINT + if (parameter_block_sizes.size() > 9) CHECK_EQ(N9, parameter_block_sizes[9]); // NOLINT + + CHECK_EQ(accumulate(parameter_block_sizes.begin(), + parameter_block_sizes.end(), 0), + N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9); + } + + bool operator()(const double* x0, double* residuals) const { + CHECK_NE(N0, 0); + CHECK_EQ(N1, 0); + CHECK_EQ(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + + return cost_functor_(&x0, residuals); + } + + bool operator()(const double* x0, + const double* x1, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_EQ(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(2); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(3); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(4); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(5); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + const double* x5, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(6); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + parameter_blocks[5] = x5; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + const double* x5, + const double* x6, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(7); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + parameter_blocks[5] = x5; + parameter_blocks[6] = x6; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + const double* x5, + const double* x6, + const double* x7, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(8); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + parameter_blocks[5] = x5; + parameter_blocks[6] = x6; + parameter_blocks[7] = x7; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + const double* x5, + const double* x6, + const double* x7, + const double* x8, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_NE(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray parameter_blocks(9); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + parameter_blocks[5] = x5; + parameter_blocks[6] = x6; + parameter_blocks[7] = x7; + parameter_blocks[8] = x8; + return cost_functor_(parameter_blocks.get(), residuals); + } + + bool operator()(const double* x0, + const double* x1, + const double* x2, + const double* x3, + const double* x4, + const double* x5, + const double* x6, + const double* x7, + const double* x8, + const double* x9, + double* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_NE(N8, 0); + CHECK_NE(N9, 0); + internal::FixedArray parameter_blocks(10); + parameter_blocks[0] = x0; + parameter_blocks[1] = x1; + parameter_blocks[2] = x2; + parameter_blocks[3] = x3; + parameter_blocks[4] = x4; + parameter_blocks[5] = x5; + parameter_blocks[6] = x6; + parameter_blocks[7] = x7; + parameter_blocks[8] = x8; + parameter_blocks[9] = x9; + return cost_functor_(parameter_blocks.get(), residuals); + } + + template + bool operator()(const JetT* x0, JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_EQ(N1, 0); + CHECK_EQ(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + return cost_functor_(&x0, residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_EQ(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(2); + jets[0] = x0; + jets[1] = x1; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_EQ(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(3); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_EQ(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(4); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_EQ(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(5); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + const JetT* x5, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_EQ(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(6); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + jets[5] = x5; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + const JetT* x5, + const JetT* x6, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_EQ(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(7); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + jets[5] = x5; + jets[6] = x6; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + const JetT* x5, + const JetT* x6, + const JetT* x7, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_EQ(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(8); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + jets[5] = x5; + jets[6] = x6; + jets[7] = x7; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + const JetT* x5, + const JetT* x6, + const JetT* x7, + const JetT* x8, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_NE(N8, 0); + CHECK_EQ(N9, 0); + internal::FixedArray jets(9); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + jets[5] = x5; + jets[6] = x6; + jets[7] = x7; + jets[8] = x8; + return cost_functor_(jets.get(), residuals); + } + + template + bool operator()(const JetT* x0, + const JetT* x1, + const JetT* x2, + const JetT* x3, + const JetT* x4, + const JetT* x5, + const JetT* x6, + const JetT* x7, + const JetT* x8, + const JetT* x9, + JetT* residuals) const { + CHECK_NE(N0, 0); + CHECK_NE(N1, 0); + CHECK_NE(N2, 0); + CHECK_NE(N3, 0); + CHECK_NE(N4, 0); + CHECK_NE(N5, 0); + CHECK_NE(N6, 0); + CHECK_NE(N7, 0); + CHECK_NE(N8, 0); + CHECK_NE(N9, 0); + internal::FixedArray jets(10); + jets[0] = x0; + jets[1] = x1; + jets[2] = x2; + jets[3] = x3; + jets[4] = x4; + jets[5] = x5; + jets[6] = x6; + jets[7] = x7; + jets[8] = x8; + jets[9] = x9; + return cost_functor_(jets.get(), residuals); + } + + private: + DynamicCostFunctionToFunctor cost_functor_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_COST_FUNCTION_TO_FUNCTOR_H_ diff --git a/include/ceres/covariance.h b/include/ceres/covariance.h new file mode 100644 index 0000000..0538522 --- /dev/null +++ b/include/ceres/covariance.h @@ -0,0 +1,467 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_COVARIANCE_H_ +#define CERES_PUBLIC_COVARIANCE_H_ + +#include +#include +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +class Problem; + +namespace internal { +class CovarianceImpl; +} // namespace internal + +// WARNING +// ======= +// It is very easy to use this class incorrectly without understanding +// the underlying mathematics. Please read and understand the +// documentation completely before attempting to use this class. +// +// +// This class allows the user to evaluate the covariance for a +// non-linear least squares problem and provides random access to its +// blocks +// +// Background +// ========== +// One way to assess the quality of the solution returned by a +// non-linear least squares solve is to analyze the covariance of the +// solution. +// +// Let us consider the non-linear regression problem +// +// y = f(x) + N(0, I) +// +// i.e., the observation y is a random non-linear function of the +// independent variable x with mean f(x) and identity covariance. Then +// the maximum likelihood estimate of x given observations y is the +// solution to the non-linear least squares problem: +// +// x* = arg min_x |f(x)|^2 +// +// And the covariance of x* is given by +// +// C(x*) = inverse[J'(x*)J(x*)] +// +// Here J(x*) is the Jacobian of f at x*. The above formula assumes +// that J(x*) has full column rank. +// +// If J(x*) is rank deficient, then the covariance matrix C(x*) is +// also rank deficient and is given by +// +// C(x*) = pseudoinverse[J'(x*)J(x*)] +// +// Note that in the above, we assumed that the covariance +// matrix for y was identity. This is an important assumption. If this +// is not the case and we have +// +// y = f(x) + N(0, S) +// +// Where S is a positive semi-definite matrix denoting the covariance +// of y, then the maximum likelihood problem to be solved is +// +// x* = arg min_x f'(x) inverse[S] f(x) +// +// and the corresponding covariance estimate of x* is given by +// +// C(x*) = inverse[J'(x*) inverse[S] J(x*)] +// +// So, if it is the case that the observations being fitted to have a +// covariance matrix not equal to identity, then it is the user's +// responsibility that the corresponding cost functions are correctly +// scaled, e.g. in the above case the cost function for this problem +// should evaluate S^{-1/2} f(x) instead of just f(x), where S^{-1/2} +// is the inverse square root of the covariance matrix S. +// +// This class allows the user to evaluate the covariance for a +// non-linear least squares problem and provides random access to its +// blocks. The computation assumes that the CostFunctions compute +// residuals such that their covariance is identity. +// +// Since the computation of the covariance matrix requires computing +// the inverse of a potentially large matrix, this can involve a +// rather large amount of time and memory. However, it is usually the +// case that the user is only interested in a small part of the +// covariance matrix. Quite often just the block diagonal. This class +// allows the user to specify the parts of the covariance matrix that +// she is interested in and then uses this information to only compute +// and store those parts of the covariance matrix. +// +// Rank of the Jacobian +// -------------------- +// As we noted above, if the jacobian is rank deficient, then the +// inverse of J'J is not defined and instead a pseudo inverse needs to +// be computed. +// +// The rank deficiency in J can be structural -- columns which are +// always known to be zero or numerical -- depending on the exact +// values in the Jacobian. +// +// Structural rank deficiency occurs when the problem contains +// parameter blocks that are constant. This class correctly handles +// structural rank deficiency like that. +// +// Numerical rank deficiency, where the rank of the matrix cannot be +// predicted by its sparsity structure and requires looking at its +// numerical values is more complicated. Here again there are two +// cases. +// +// a. The rank deficiency arises from overparameterization. e.g., a +// four dimensional quaternion used to parameterize SO(3), which is +// a three dimensional manifold. In cases like this, the user should +// use an appropriate LocalParameterization. Not only will this lead +// to better numerical behaviour of the Solver, it will also expose +// the rank deficiency to the Covariance object so that it can +// handle it correctly. +// +// b. More general numerical rank deficiency in the Jacobian +// requires the computation of the so called Singular Value +// Decomposition (SVD) of J'J. We do not know how to do this for +// large sparse matrices efficiently. For small and moderate sized +// problems this is done using dense linear algebra. +// +// Gauge Invariance +// ---------------- +// In structure from motion (3D reconstruction) problems, the +// reconstruction is ambiguous upto a similarity transform. This is +// known as a Gauge Ambiguity. Handling Gauges correctly requires the +// use of SVD or custom inversion algorithms. For small problems the +// user can use the dense algorithm. For more details see +// +// Ken-ichi Kanatani, Daniel D. Morris: Gauges and gauge +// transformations for uncertainty description of geometric structure +// with indeterminacy. IEEE Transactions on Information Theory 47(5): +// 2017-2028 (2001) +// +// Example Usage +// ============= +// +// double x[3]; +// double y[2]; +// +// Problem problem; +// problem.AddParameterBlock(x, 3); +// problem.AddParameterBlock(y, 2); +// +// +// +// Covariance::Options options; +// Covariance covariance(options); +// +// std::vector > covariance_blocks; +// covariance_blocks.push_back(make_pair(x, x)); +// covariance_blocks.push_back(make_pair(y, y)); +// covariance_blocks.push_back(make_pair(x, y)); +// +// CHECK(covariance.Compute(covariance_blocks, &problem)); +// +// double covariance_xx[3 * 3]; +// double covariance_yy[2 * 2]; +// double covariance_xy[3 * 2]; +// covariance.GetCovarianceBlock(x, x, covariance_xx) +// covariance.GetCovarianceBlock(y, y, covariance_yy) +// covariance.GetCovarianceBlock(x, y, covariance_xy) +// +class CERES_EXPORT Covariance { + public: + struct CERES_EXPORT Options { + Options() { + algorithm_type = SPARSE_QR; + + // Eigen's QR factorization is always available. + sparse_linear_algebra_library_type = EIGEN_SPARSE; +#if !defined(CERES_NO_SUITESPARSE) + sparse_linear_algebra_library_type = SUITE_SPARSE; +#endif + + min_reciprocal_condition_number = 1e-14; + null_space_rank = 0; + num_threads = 1; + apply_loss_function = true; + } + + // Sparse linear algebra library to use when a sparse matrix + // factorization is being used to compute the covariance matrix. + // + // Currently this only applies to SPARSE_QR. + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; + + // Ceres supports two different algorithms for covariance + // estimation, which represent different tradeoffs in speed, + // accuracy and reliability. + // + // 1. DENSE_SVD uses Eigen's JacobiSVD to perform the + // computations. It computes the singular value decomposition + // + // U * S * V' = J + // + // and then uses it to compute the pseudo inverse of J'J as + // + // pseudoinverse[J'J]^ = V * pseudoinverse[S] * V' + // + // It is an accurate but slow method and should only be used + // for small to moderate sized problems. It can handle + // full-rank as well as rank deficient Jacobians. + // + // 2. SPARSE_QR uses the sparse QR factorization algorithm + // to compute the decomposition + // + // Q * R = J + // + // [J'J]^-1 = [R*R']^-1 + // + // SPARSE_QR is not capable of computing the covariance if the + // Jacobian is rank deficient. Depending on the value of + // Covariance::Options::sparse_linear_algebra_library_type, either + // Eigen's Sparse QR factorization algorithm will be used or + // SuiteSparse's high performance SuiteSparseQR algorithm will be + // used. + CovarianceAlgorithmType algorithm_type; + + // If the Jacobian matrix is near singular, then inverting J'J + // will result in unreliable results, e.g, if + // + // J = [1.0 1.0 ] + // [1.0 1.0000001 ] + // + // which is essentially a rank deficient matrix, we have + // + // inv(J'J) = [ 2.0471e+14 -2.0471e+14] + // [-2.0471e+14 2.0471e+14] + // + // This is not a useful result. Therefore, by default + // Covariance::Compute will return false if a rank deficient + // Jacobian is encountered. How rank deficiency is detected + // depends on the algorithm being used. + // + // 1. DENSE_SVD + // + // min_sigma / max_sigma < sqrt(min_reciprocal_condition_number) + // + // where min_sigma and max_sigma are the minimum and maxiumum + // singular values of J respectively. + // + // 2. SPARSE_QR + // + // rank(J) < num_col(J) + // + // Here rank(J) is the estimate of the rank of J returned by the + // sparse QR factorization algorithm. It is a fairly reliable + // indication of rank deficiency. + // + double min_reciprocal_condition_number; + + // When using DENSE_SVD, the user has more control in dealing with + // singular and near singular covariance matrices. + // + // As mentioned above, when the covariance matrix is near + // singular, instead of computing the inverse of J'J, the + // Moore-Penrose pseudoinverse of J'J should be computed. + // + // If J'J has the eigen decomposition (lambda_i, e_i), where + // lambda_i is the i^th eigenvalue and e_i is the corresponding + // eigenvector, then the inverse of J'J is + // + // inverse[J'J] = sum_i e_i e_i' / lambda_i + // + // and computing the pseudo inverse involves dropping terms from + // this sum that correspond to small eigenvalues. + // + // How terms are dropped is controlled by + // min_reciprocal_condition_number and null_space_rank. + // + // If null_space_rank is non-negative, then the smallest + // null_space_rank eigenvalue/eigenvectors are dropped + // irrespective of the magnitude of lambda_i. If the ratio of the + // smallest non-zero eigenvalue to the largest eigenvalue in the + // truncated matrix is still below + // min_reciprocal_condition_number, then the Covariance::Compute() + // will fail and return false. + // + // Setting null_space_rank = -1 drops all terms for which + // + // lambda_i / lambda_max < min_reciprocal_condition_number. + // + // This option has no effect on the SUITE_SPARSE_QR and + // EIGEN_SPARSE_QR algorithms. + int null_space_rank; + + int num_threads; + + // Even though the residual blocks in the problem may contain loss + // functions, setting apply_loss_function to false will turn off + // the application of the loss function to the output of the cost + // function and in turn its effect on the covariance. + // + // TODO(sameergaarwal): Expand this based on Jim's experiments. + bool apply_loss_function; + }; + + explicit Covariance(const Options& options); + ~Covariance(); + + // Compute a part of the covariance matrix. + // + // The vector covariance_blocks, indexes into the covariance matrix + // block-wise using pairs of parameter blocks. This allows the + // covariance estimation algorithm to only compute and store these + // blocks. + // + // Since the covariance matrix is symmetric, if the user passes + // (block1, block2), then GetCovarianceBlock can be called with + // block1, block2 as well as block2, block1. + // + // covariance_blocks cannot contain duplicates. Bad things will + // happen if they do. + // + // Note that the list of covariance_blocks is only used to determine + // what parts of the covariance matrix are computed. The full + // Jacobian is used to do the computation, i.e. they do not have an + // impact on what part of the Jacobian is used for computation. + // + // The return value indicates the success or failure of the + // covariance computation. Please see the documentation for + // Covariance::Options for more on the conditions under which this + // function returns false. + bool Compute( + const std::vector >& covariance_blocks, + Problem* problem); + + // Compute a part of the covariance matrix. + // + // The vector parameter_blocks contains the parameter blocks that + // are used for computing the covariance matrix. From this vector + // all covariance pairs are generated. This allows the covariance + // estimation algorithm to only compute and store these blocks. + // + // parameter_blocks cannot contain duplicates. Bad things will + // happen if they do. + // + // Note that the list of covariance_blocks is only used to determine + // what parts of the covariance matrix are computed. The full + // Jacobian is used to do the computation, i.e. they do not have an + // impact on what part of the Jacobian is used for computation. + // + // The return value indicates the success or failure of the + // covariance computation. Please see the documentation for + // Covariance::Options for more on the conditions under which this + // function returns false. + bool Compute(const std::vector& parameter_blocks, + Problem* problem); + + // Return the block of the cross-covariance matrix corresponding to + // parameter_block1 and parameter_block2. + // + // Compute must be called before the first call to + // GetCovarianceBlock and the pair OR the pair must have been present in the vector + // covariance_blocks when Compute was called. Otherwise + // GetCovarianceBlock will return false. + // + // covariance_block must point to a memory location that can store a + // parameter_block1_size x parameter_block2_size matrix. The + // returned covariance will be a row-major matrix. + bool GetCovarianceBlock(const double* parameter_block1, + const double* parameter_block2, + double* covariance_block) const; + + // Return the block of the cross-covariance matrix corresponding to + // parameter_block1 and parameter_block2. + // Returns cross-covariance in the tangent space if a local + // parameterization is associated with either parameter block; + // else returns cross-covariance in the ambient space. + // + // Compute must be called before the first call to + // GetCovarianceBlock and the pair OR the pair must have been present in the vector + // covariance_blocks when Compute was called. Otherwise + // GetCovarianceBlock will return false. + // + // covariance_block must point to a memory location that can store a + // parameter_block1_local_size x parameter_block2_local_size matrix. The + // returned covariance will be a row-major matrix. + bool GetCovarianceBlockInTangentSpace(const double* parameter_block1, + const double* parameter_block2, + double* covariance_block) const; + + // Return the covariance matrix corresponding to all parameter_blocks. + // + // Compute must be called before calling GetCovarianceMatrix and all + // parameter_blocks must have been present in the vector + // parameter_blocks when Compute was called. Otherwise + // GetCovarianceMatrix returns false. + // + // covariance_matrix must point to a memory location that can store + // the size of the covariance matrix. The covariance matrix will be + // a square matrix whose row and column count is equal to the sum of + // the sizes of the individual parameter blocks. The covariance + // matrix will be a row-major matrix. + bool GetCovarianceMatrix(const std::vector ¶meter_blocks, + double *covariance_matrix); + + // Return the covariance matrix corresponding to parameter_blocks + // in the tangent space if a local parameterization is associated + // with one of the parameter blocks else returns the covariance + // matrix in the ambient space. + // + // Compute must be called before calling GetCovarianceMatrix and all + // parameter_blocks must have been present in the vector + // parameters_blocks when Compute was called. Otherwise + // GetCovarianceMatrix returns false. + // + // covariance_matrix must point to a memory location that can store + // the size of the covariance matrix. The covariance matrix will be + // a square matrix whose row and column count is equal to the sum of + // the sizes of the tangent spaces of the individual parameter + // blocks. The covariance matrix will be a row-major matrix. + bool GetCovarianceMatrixInTangentSpace( + const std::vector& parameter_blocks, + double* covariance_matrix); + + private: + internal::scoped_ptr impl_; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_COVARIANCE_H_ diff --git a/include/ceres/crs_matrix.h b/include/ceres/crs_matrix.h new file mode 100644 index 0000000..23687c4 --- /dev/null +++ b/include/ceres/crs_matrix.h @@ -0,0 +1,86 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_CRS_MATRIX_H_ +#define CERES_PUBLIC_CRS_MATRIX_H_ + +#include +#include "ceres/internal/port.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// A compressed row sparse matrix used primarily for communicating the +// Jacobian matrix to the user. +struct CERES_EXPORT CRSMatrix { + CRSMatrix() : num_rows(0), num_cols(0) {} + + int num_rows; + int num_cols; + + // A compressed row matrix stores its contents in three arrays, + // rows, cols and values. + // + // rows is a num_rows + 1 sized array that points into the cols and + // values array. For each row i: + // + // cols[rows[i]] ... cols[rows[i + 1] - 1] are the indices of the + // non-zero columns of row i. + // + // values[rows[i]] .. values[rows[i + 1] - 1] are the values of the + // corresponding entries. + // + // cols and values contain as many entries as there are non-zeros in + // the matrix. + // + // e.g, consider the 3x4 sparse matrix + // + // [ 0 10 0 4 ] + // [ 0 2 -3 2 ] + // [ 1 2 0 0 ] + // + // The three arrays will be: + // + // + // -row0- ---row1--- -row2- + // rows = [ 0, 2, 5, 7] + // cols = [ 1, 3, 1, 2, 3, 0, 1] + // values = [10, 4, 2, -3, 2, 1, 2] + + std::vector cols; + std::vector rows; + std::vector values; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_CRS_MATRIX_H_ diff --git a/include/ceres/cubic_interpolation.h b/include/ceres/cubic_interpolation.h new file mode 100644 index 0000000..9804a33 --- /dev/null +++ b/include/ceres/cubic_interpolation.h @@ -0,0 +1,439 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_CUBIC_INTERPOLATION_H_ +#define CERES_PUBLIC_CUBIC_INTERPOLATION_H_ + +#include "ceres/internal/port.h" +#include "Eigen/Core" +#include "glog/logging.h" + +namespace ceres { + +// Given samples from a function sampled at four equally spaced points, +// +// p0 = f(-1) +// p1 = f(0) +// p2 = f(1) +// p3 = f(2) +// +// Evaluate the cubic Hermite spline (also known as the Catmull-Rom +// spline) at a point x that lies in the interval [0, 1]. +// +// This is also the interpolation kernel (for the case of a = 0.5) as +// proposed by R. Keys, in: +// +// "Cubic convolution interpolation for digital image processing". +// IEEE Transactions on Acoustics, Speech, and Signal Processing +// 29 (6): 1153–1160. +// +// For more details see +// +// http://en.wikipedia.org/wiki/Cubic_Hermite_spline +// http://en.wikipedia.org/wiki/Bicubic_interpolation +// +// f if not NULL will contain the interpolated function values. +// dfdx if not NULL will contain the interpolated derivative values. +template +void CubicHermiteSpline(const Eigen::Matrix& p0, + const Eigen::Matrix& p1, + const Eigen::Matrix& p2, + const Eigen::Matrix& p3, + const double x, + double* f, + double* dfdx) { + typedef Eigen::Matrix VType; + const VType a = 0.5 * (-p0 + 3.0 * p1 - 3.0 * p2 + p3); + const VType b = 0.5 * (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3); + const VType c = 0.5 * (-p0 + p2); + const VType d = p1; + + // Use Horner's rule to evaluate the function value and its + // derivative. + + // f = ax^3 + bx^2 + cx + d + if (f != NULL) { + Eigen::Map(f, kDataDimension) = d + x * (c + x * (b + x * a)); + } + + // dfdx = 3ax^2 + 2bx + c + if (dfdx != NULL) { + Eigen::Map(dfdx, kDataDimension) = c + x * (2.0 * b + 3.0 * a * x); + } +} + +// Given as input an infinite one dimensional grid, which provides the +// following interface. +// +// class Grid { +// public: +// enum { DATA_DIMENSION = 2; }; +// void GetValue(int n, double* f) const; +// }; +// +// Here, GetValue gives the value of a function f (possibly vector +// valued) for any integer n. +// +// The enum DATA_DIMENSION indicates the dimensionality of the +// function being interpolated. For example if you are interpolating +// rotations in axis-angle format over time, then DATA_DIMENSION = 3. +// +// CubicInterpolator uses cubic Hermite splines to produce a smooth +// approximation to it that can be used to evaluate the f(x) and f'(x) +// at any point on the real number line. +// +// For more details on cubic interpolation see +// +// http://en.wikipedia.org/wiki/Cubic_Hermite_spline +// +// Example usage: +// +// const double data[] = {1.0, 2.0, 5.0, 6.0}; +// Grid1D grid(x, 0, 4); +// CubicInterpolator > interpolator(grid); +// double f, dfdx; +// interpolator.Evaluator(1.5, &f, &dfdx); +template +class CubicInterpolator { + public: + explicit CubicInterpolator(const Grid& grid) + : grid_(grid) { + // The + casts the enum into an int before doing the + // comparison. It is needed to prevent + // "-Wunnamed-type-template-args" related errors. + CHECK_GE(+Grid::DATA_DIMENSION, 1); + } + + void Evaluate(double x, double* f, double* dfdx) const { + const int n = std::floor(x); + Eigen::Matrix p0, p1, p2, p3; + grid_.GetValue(n - 1, p0.data()); + grid_.GetValue(n, p1.data()); + grid_.GetValue(n + 1, p2.data()); + grid_.GetValue(n + 2, p3.data()); + CubicHermiteSpline(p0, p1, p2, p3, x - n, f, dfdx); + } + + // The following two Evaluate overloads are needed for interfacing + // with automatic differentiation. The first is for when a scalar + // evaluation is done, and the second one is for when Jets are used. + void Evaluate(const double& x, double* f) const { + Evaluate(x, f, NULL); + } + + template void Evaluate(const JetT& x, JetT* f) const { + double fx[Grid::DATA_DIMENSION], dfdx[Grid::DATA_DIMENSION]; + Evaluate(x.a, fx, dfdx); + for (int i = 0; i < Grid::DATA_DIMENSION; ++i) { + f[i].a = fx[i]; + f[i].v = dfdx[i] * x.v; + } + } + + private: + const Grid& grid_; +}; + +// An object that implements an infinite one dimensional grid needed +// by the CubicInterpolator where the source of the function values is +// an array of type T on the interval +// +// [begin, ..., end - 1] +// +// Since the input array is finite and the grid is infinite, values +// outside this interval needs to be computed. Grid1D uses the value +// from the nearest edge. +// +// The function being provided can be vector valued, in which case +// kDataDimension > 1. The dimensional slices of the function maybe +// interleaved, or they maybe stacked, i.e, if the function has +// kDataDimension = 2, if kInterleaved = true, then it is stored as +// +// f01, f02, f11, f12 .... +// +// and if kInterleaved = false, then it is stored as +// +// f01, f11, .. fn1, f02, f12, .. , fn2 +// +template +struct Grid1D { + public: + enum { DATA_DIMENSION = kDataDimension }; + + Grid1D(const T* data, const int begin, const int end) + : data_(data), begin_(begin), end_(end), num_values_(end - begin) { + CHECK_LT(begin, end); + } + + EIGEN_STRONG_INLINE void GetValue(const int n, double* f) const { + const int idx = std::min(std::max(begin_, n), end_ - 1) - begin_; + if (kInterleaved) { + for (int i = 0; i < kDataDimension; ++i) { + f[i] = static_cast(data_[kDataDimension * idx + i]); + } + } else { + for (int i = 0; i < kDataDimension; ++i) { + f[i] = static_cast(data_[i * num_values_ + idx]); + } + } + } + + private: + const T* data_; + const int begin_; + const int end_; + const int num_values_; +}; + +// Given as input an infinite two dimensional grid like object, which +// provides the following interface: +// +// struct Grid { +// enum { DATA_DIMENSION = 1 }; +// void GetValue(int row, int col, double* f) const; +// }; +// +// Where, GetValue gives us the value of a function f (possibly vector +// valued) for any pairs of integers (row, col), and the enum +// DATA_DIMENSION indicates the dimensionality of the function being +// interpolated. For example if you are interpolating a color image +// with three channels (Red, Green & Blue), then DATA_DIMENSION = 3. +// +// BiCubicInterpolator uses the cubic convolution interpolation +// algorithm of R. Keys, to produce a smooth approximation to it that +// can be used to evaluate the f(r,c), df(r, c)/dr and df(r,c)/dc at +// any point in the real plane. +// +// For more details on the algorithm used here see: +// +// "Cubic convolution interpolation for digital image processing". +// Robert G. Keys, IEEE Trans. on Acoustics, Speech, and Signal +// Processing 29 (6): 1153–1160, 1981. +// +// http://en.wikipedia.org/wiki/Cubic_Hermite_spline +// http://en.wikipedia.org/wiki/Bicubic_interpolation +// +// Example usage: +// +// const double data[] = {1.0, 3.0, -1.0, 4.0, +// 3.6, 2.1, 4.2, 2.0, +// 2.0, 1.0, 3.1, 5.2}; +// Grid2D grid(data, 3, 4); +// BiCubicInterpolator > interpolator(grid); +// double f, dfdr, dfdc; +// interpolator.Evaluate(1.2, 2.5, &f, &dfdr, &dfdc); + +template +class BiCubicInterpolator { + public: + explicit BiCubicInterpolator(const Grid& grid) + : grid_(grid) { + // The + casts the enum into an int before doing the + // comparison. It is needed to prevent + // "-Wunnamed-type-template-args" related errors. + CHECK_GE(+Grid::DATA_DIMENSION, 1); + } + + // Evaluate the interpolated function value and/or its + // derivative. Returns false if r or c is out of bounds. + void Evaluate(double r, double c, + double* f, double* dfdr, double* dfdc) const { + // BiCubic interpolation requires 16 values around the point being + // evaluated. We will use pij, to indicate the elements of the + // 4x4 grid of values. + // + // col + // p00 p01 p02 p03 + // row p10 p11 p12 p13 + // p20 p21 p22 p23 + // p30 p31 p32 p33 + // + // The point (r,c) being evaluated is assumed to lie in the square + // defined by p11, p12, p22 and p21. + + const int row = std::floor(r); + const int col = std::floor(c); + + Eigen::Matrix p0, p1, p2, p3; + + // Interpolate along each of the four rows, evaluating the function + // value and the horizontal derivative in each row. + Eigen::Matrix f0, f1, f2, f3; + Eigen::Matrix df0dc, df1dc, df2dc, df3dc; + + grid_.GetValue(row - 1, col - 1, p0.data()); + grid_.GetValue(row - 1, col , p1.data()); + grid_.GetValue(row - 1, col + 1, p2.data()); + grid_.GetValue(row - 1, col + 2, p3.data()); + CubicHermiteSpline(p0, p1, p2, p3, c - col, + f0.data(), df0dc.data()); + + grid_.GetValue(row, col - 1, p0.data()); + grid_.GetValue(row, col , p1.data()); + grid_.GetValue(row, col + 1, p2.data()); + grid_.GetValue(row, col + 2, p3.data()); + CubicHermiteSpline(p0, p1, p2, p3, c - col, + f1.data(), df1dc.data()); + + grid_.GetValue(row + 1, col - 1, p0.data()); + grid_.GetValue(row + 1, col , p1.data()); + grid_.GetValue(row + 1, col + 1, p2.data()); + grid_.GetValue(row + 1, col + 2, p3.data()); + CubicHermiteSpline(p0, p1, p2, p3, c - col, + f2.data(), df2dc.data()); + + grid_.GetValue(row + 2, col - 1, p0.data()); + grid_.GetValue(row + 2, col , p1.data()); + grid_.GetValue(row + 2, col + 1, p2.data()); + grid_.GetValue(row + 2, col + 2, p3.data()); + CubicHermiteSpline(p0, p1, p2, p3, c - col, + f3.data(), df3dc.data()); + + // Interpolate vertically the interpolated value from each row and + // compute the derivative along the columns. + CubicHermiteSpline(f0, f1, f2, f3, r - row, f, dfdr); + if (dfdc != NULL) { + // Interpolate vertically the derivative along the columns. + CubicHermiteSpline(df0dc, df1dc, df2dc, df3dc, + r - row, dfdc, NULL); + } + } + + // The following two Evaluate overloads are needed for interfacing + // with automatic differentiation. The first is for when a scalar + // evaluation is done, and the second one is for when Jets are used. + void Evaluate(const double& r, const double& c, double* f) const { + Evaluate(r, c, f, NULL, NULL); + } + + template void Evaluate(const JetT& r, + const JetT& c, + JetT* f) const { + double frc[Grid::DATA_DIMENSION]; + double dfdr[Grid::DATA_DIMENSION]; + double dfdc[Grid::DATA_DIMENSION]; + Evaluate(r.a, c.a, frc, dfdr, dfdc); + for (int i = 0; i < Grid::DATA_DIMENSION; ++i) { + f[i].a = frc[i]; + f[i].v = dfdr[i] * r.v + dfdc[i] * c.v; + } + } + + private: + const Grid& grid_; +}; + +// An object that implements an infinite two dimensional grid needed +// by the BiCubicInterpolator where the source of the function values +// is an grid of type T on the grid +// +// [(row_start, col_start), ..., (row_start, col_end - 1)] +// [ ... ] +// [(row_end - 1, col_start), ..., (row_end - 1, col_end - 1)] +// +// Since the input grid is finite and the grid is infinite, values +// outside this interval needs to be computed. Grid2D uses the value +// from the nearest edge. +// +// The function being provided can be vector valued, in which case +// kDataDimension > 1. The data maybe stored in row or column major +// format and the various dimensional slices of the function maybe +// interleaved, or they maybe stacked, i.e, if the function has +// kDataDimension = 2, is stored in row-major format and if +// kInterleaved = true, then it is stored as +// +// f001, f002, f011, f012, ... +// +// A commonly occuring example are color images (RGB) where the three +// channels are stored interleaved. +// +// If kInterleaved = false, then it is stored as +// +// f001, f011, ..., fnm1, f002, f012, ... +template +struct Grid2D { + public: + enum { DATA_DIMENSION = kDataDimension }; + + Grid2D(const T* data, + const int row_begin, const int row_end, + const int col_begin, const int col_end) + : data_(data), + row_begin_(row_begin), row_end_(row_end), + col_begin_(col_begin), col_end_(col_end), + num_rows_(row_end - row_begin), num_cols_(col_end - col_begin), + num_values_(num_rows_ * num_cols_) { + CHECK_GE(kDataDimension, 1); + CHECK_LT(row_begin, row_end); + CHECK_LT(col_begin, col_end); + } + + EIGEN_STRONG_INLINE void GetValue(const int r, const int c, double* f) const { + const int row_idx = + std::min(std::max(row_begin_, r), row_end_ - 1) - row_begin_; + const int col_idx = + std::min(std::max(col_begin_, c), col_end_ - 1) - col_begin_; + + const int n = + (kRowMajor) + ? num_cols_ * row_idx + col_idx + : num_rows_ * col_idx + row_idx; + + + if (kInterleaved) { + for (int i = 0; i < kDataDimension; ++i) { + f[i] = static_cast(data_[kDataDimension * n + i]); + } + } else { + for (int i = 0; i < kDataDimension; ++i) { + f[i] = static_cast(data_[i * num_values_ + n]); + } + } + } + + private: + const T* data_; + const int row_begin_; + const int row_end_; + const int col_begin_; + const int col_end_; + const int num_rows_; + const int num_cols_; + const int num_values_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_CUBIC_INTERPOLATOR_H_ diff --git a/include/ceres/dynamic_autodiff_cost_function.h b/include/ceres/dynamic_autodiff_cost_function.h new file mode 100644 index 0000000..1cece2c --- /dev/null +++ b/include/ceres/dynamic_autodiff_cost_function.h @@ -0,0 +1,251 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// mierle@gmail.com (Keir Mierle) + +#ifndef CERES_PUBLIC_DYNAMIC_AUTODIFF_COST_FUNCTION_H_ +#define CERES_PUBLIC_DYNAMIC_AUTODIFF_COST_FUNCTION_H_ + +#include +#include +#include + +#include "ceres/dynamic_cost_function.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/jet.h" +#include "glog/logging.h" + +namespace ceres { + +// This autodiff implementation differs from the one found in +// autodiff_cost_function.h by supporting autodiff on cost functions +// with variable numbers of parameters with variable sizes. With the +// other implementation, all the sizes (both the number of parameter +// blocks and the size of each block) must be fixed at compile time. +// +// The functor API differs slightly from the API for fixed size +// autodiff; the expected interface for the cost functors is: +// +// struct MyCostFunctor { +// template +// bool operator()(T const* const* parameters, T* residuals) const { +// // Use parameters[i] to access the i'th parameter block. +// } +// } +// +// Since the sizing of the parameters is done at runtime, you must +// also specify the sizes after creating the dynamic autodiff cost +// function. For example: +// +// DynamicAutoDiffCostFunction cost_function( +// new MyCostFunctor()); +// cost_function.AddParameterBlock(5); +// cost_function.AddParameterBlock(10); +// cost_function.SetNumResiduals(21); +// +// Under the hood, the implementation evaluates the cost function +// multiple times, computing a small set of the derivatives (four by +// default, controlled by the Stride template parameter) with each +// pass. There is a tradeoff with the size of the passes; you may want +// to experiment with the stride. +template +class DynamicAutoDiffCostFunction : public DynamicCostFunction { + public: + explicit DynamicAutoDiffCostFunction(CostFunctor* functor) + : functor_(functor) {} + + virtual ~DynamicAutoDiffCostFunction() {} + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + CHECK_GT(num_residuals(), 0) + << "You must call DynamicAutoDiffCostFunction::SetNumResiduals() " + << "before DynamicAutoDiffCostFunction::Evaluate()."; + + if (jacobians == NULL) { + return (*functor_)(parameters, residuals); + } + + // The difficulty with Jets, as implemented in Ceres, is that they were + // originally designed for strictly compile-sized use. At this point, there + // is a large body of code that assumes inside a cost functor it is + // acceptable to do e.g. T(1.5) and get an appropriately sized jet back. + // + // Unfortunately, it is impossible to communicate the expected size of a + // dynamically sized jet to the static instantiations that existing code + // depends on. + // + // To work around this issue, the solution here is to evaluate the + // jacobians in a series of passes, each one computing Stripe * + // num_residuals() derivatives. This is done with small, fixed-size jets. + const int num_parameter_blocks = parameter_block_sizes().size(); + const int num_parameters = std::accumulate(parameter_block_sizes().begin(), + parameter_block_sizes().end(), + 0); + + // Allocate scratch space for the strided evaluation. + std::vector > input_jets(num_parameters); + std::vector > output_jets(num_residuals()); + + // Make the parameter pack that is sent to the functor (reused). + std::vector* > jet_parameters(num_parameter_blocks, + static_cast* >(NULL)); + int num_active_parameters = 0; + + // To handle constant parameters between non-constant parameter blocks, the + // start position --- a raw parameter index --- of each contiguous block of + // non-constant parameters is recorded in start_derivative_section. + std::vector start_derivative_section; + bool in_derivative_section = false; + int parameter_cursor = 0; + + // Discover the derivative sections and set the parameter values. + for (int i = 0; i < num_parameter_blocks; ++i) { + jet_parameters[i] = &input_jets[parameter_cursor]; + + const int parameter_block_size = parameter_block_sizes()[i]; + if (jacobians[i] != NULL) { + if (!in_derivative_section) { + start_derivative_section.push_back(parameter_cursor); + in_derivative_section = true; + } + + num_active_parameters += parameter_block_size; + } else { + in_derivative_section = false; + } + + for (int j = 0; j < parameter_block_size; ++j, parameter_cursor++) { + input_jets[parameter_cursor].a = parameters[i][j]; + } + } + + // When `num_active_parameters % Stride != 0` then it can be the case + // that `active_parameter_count < Stride` while parameter_cursor is less + // than the total number of parameters and with no remaining non-constant + // parameter blocks. Pushing parameter_cursor (the total number of + // parameters) as a final entry to start_derivative_section is required + // because if a constant parameter block is encountered after the + // last non-constant block then current_derivative_section is incremented + // and would otherwise index an invalid position in + // start_derivative_section. Setting the final element to the total number + // of parameters means that this can only happen at most once in the loop + // below. + start_derivative_section.push_back(parameter_cursor); + + // Evaluate all of the strides. Each stride is a chunk of the derivative to + // evaluate, typically some size proportional to the size of the SIMD + // registers of the CPU. + int num_strides = static_cast(ceil(num_active_parameters / + static_cast(Stride))); + + int current_derivative_section = 0; + int current_derivative_section_cursor = 0; + + for (int pass = 0; pass < num_strides; ++pass) { + // Set most of the jet components to zero, except for + // non-constant #Stride parameters. + const int initial_derivative_section = current_derivative_section; + const int initial_derivative_section_cursor = + current_derivative_section_cursor; + + int active_parameter_count = 0; + parameter_cursor = 0; + + for (int i = 0; i < num_parameter_blocks; ++i) { + for (int j = 0; j < parameter_block_sizes()[i]; + ++j, parameter_cursor++) { + input_jets[parameter_cursor].v.setZero(); + if (active_parameter_count < Stride && + parameter_cursor >= ( + start_derivative_section[current_derivative_section] + + current_derivative_section_cursor)) { + if (jacobians[i] != NULL) { + input_jets[parameter_cursor].v[active_parameter_count] = 1.0; + ++active_parameter_count; + ++current_derivative_section_cursor; + } else { + ++current_derivative_section; + current_derivative_section_cursor = 0; + } + } + } + } + + if (!(*functor_)(&jet_parameters[0], &output_jets[0])) { + return false; + } + + // Copy the pieces of the jacobians into their final place. + active_parameter_count = 0; + + current_derivative_section = initial_derivative_section; + current_derivative_section_cursor = initial_derivative_section_cursor; + + for (int i = 0, parameter_cursor = 0; i < num_parameter_blocks; ++i) { + for (int j = 0; j < parameter_block_sizes()[i]; + ++j, parameter_cursor++) { + if (active_parameter_count < Stride && + parameter_cursor >= ( + start_derivative_section[current_derivative_section] + + current_derivative_section_cursor)) { + if (jacobians[i] != NULL) { + for (int k = 0; k < num_residuals(); ++k) { + jacobians[i][k * parameter_block_sizes()[i] + j] = + output_jets[k].v[active_parameter_count]; + } + ++active_parameter_count; + ++current_derivative_section_cursor; + } else { + ++current_derivative_section; + current_derivative_section_cursor = 0; + } + } + } + } + + // Only copy the residuals over once (even though we compute them on + // every loop). + if (pass == num_strides - 1) { + for (int k = 0; k < num_residuals(); ++k) { + residuals[k] = output_jets[k].a; + } + } + } + return true; + } + + private: + internal::scoped_ptr functor_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_DYNAMIC_AUTODIFF_COST_FUNCTION_H_ diff --git a/include/ceres/dynamic_cost_function.h b/include/ceres/dynamic_cost_function.h new file mode 100644 index 0000000..6c0aa31 --- /dev/null +++ b/include/ceres/dynamic_cost_function.h @@ -0,0 +1,56 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2016 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_DYNAMIC_COST_FUNCTION_H_ +#define CERES_PUBLIC_DYNAMIC_COST_FUNCTION_H_ + +#include "ceres/cost_function.h" + +namespace ceres { + +// A common base class for DynamicAutoDiffCostFunction and +// DynamicNumericDiffCostFunction which depend on methods that can add +// parameter blocks and set the number of residuals at run time. +class CERES_EXPORT DynamicCostFunction : public CostFunction { + public: + ~DynamicCostFunction() {} + + virtual void AddParameterBlock(int size) { + mutable_parameter_block_sizes()->push_back(size); + } + + virtual void SetNumResiduals(int num_residuals) { + set_num_residuals(num_residuals); + } +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_DYNAMIC_COST_FUNCTION_H_ diff --git a/include/ceres/dynamic_cost_function_to_functor.h b/include/ceres/dynamic_cost_function_to_functor.h new file mode 100644 index 0000000..10bc99a --- /dev/null +++ b/include/ceres/dynamic_cost_function_to_functor.h @@ -0,0 +1,190 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// dgossow@google.com (David Gossow) + +#ifndef CERES_PUBLIC_DYNAMIC_COST_FUNCTION_TO_FUNCTOR_H_ +#define CERES_PUBLIC_DYNAMIC_COST_FUNCTION_TO_FUNCTOR_H_ + +#include +#include + +#include "ceres/dynamic_cost_function.h" +#include "ceres/internal/fixed_array.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { + +// DynamicCostFunctionToFunctor allows users to use CostFunction +// objects in templated functors which are to be used for automatic +// differentiation. It works similar to CostFunctionToFunctor, with the +// difference that it allows you to wrap a cost function with dynamic numbers +// of parameters and residuals. +// +// For example, let us assume that +// +// class IntrinsicProjection : public CostFunction { +// public: +// IntrinsicProjection(const double* observation); +// virtual bool Evaluate(double const* const* parameters, +// double* residuals, +// double** jacobians) const; +// }; +// +// is a cost function that implements the projection of a point in its +// local coordinate system onto its image plane and subtracts it from +// the observed point projection. It can compute its residual and +// either via analytic or numerical differentiation can compute its +// jacobians. The intrinsics are passed in as parameters[0] and the point as +// parameters[1]. +// +// Now we would like to compose the action of this CostFunction with +// the action of camera extrinsics, i.e., rotation and +// translation. Say we have a templated function +// +// template +// void RotateAndTranslatePoint(double const* const* parameters, +// double* residuals); +// +// Then we can now do the following, +// +// struct CameraProjection { +// CameraProjection(const double* observation) +// : intrinsic_projection_.(new IntrinsicProjection(observation)) { +// } +// template +// bool operator()(T const* const* parameters, +// T* residual) const { +// const T* rotation = parameters[0]; +// const T* translation = parameters[1]; +// const T* intrinsics = parameters[2]; +// const T* point = parameters[3]; +// T transformed_point[3]; +// RotateAndTranslatePoint(rotation, translation, point, transformed_point); +// +// // Note that we call intrinsic_projection_, just like it was +// // any other templated functor. +// const T* projection_parameters[2]; +// projection_parameters[0] = intrinsics; +// projection_parameters[1] = transformed_point; +// return intrinsic_projection_(projection_parameters, residual); +// } +// +// private: +// DynamicCostFunctionToFunctor intrinsic_projection_; +// }; +class DynamicCostFunctionToFunctor { + public: + // Takes ownership of cost_function. + explicit DynamicCostFunctionToFunctor(CostFunction* cost_function) + : cost_function_(cost_function) { + CHECK_NOTNULL(cost_function); + } + + bool operator()(double const* const* parameters, double* residuals) const { + return cost_function_->Evaluate(parameters, residuals, NULL); + } + + template + bool operator()(JetT const* const* inputs, JetT* output) const { + const std::vector& parameter_block_sizes = + cost_function_->parameter_block_sizes(); + const int num_parameter_blocks = + static_cast(parameter_block_sizes.size()); + const int num_residuals = cost_function_->num_residuals(); + const int num_parameters = std::accumulate(parameter_block_sizes.begin(), + parameter_block_sizes.end(), 0); + + internal::FixedArray parameters(num_parameters); + internal::FixedArray parameter_blocks(num_parameter_blocks); + internal::FixedArray jacobians(num_residuals * num_parameters); + internal::FixedArray jacobian_blocks(num_parameter_blocks); + internal::FixedArray residuals(num_residuals); + + // Build a set of arrays to get the residuals and jacobians from + // the CostFunction wrapped by this functor. + double* parameter_ptr = parameters.get(); + double* jacobian_ptr = jacobians.get(); + for (int i = 0; i < num_parameter_blocks; ++i) { + parameter_blocks[i] = parameter_ptr; + jacobian_blocks[i] = jacobian_ptr; + for (int j = 0; j < parameter_block_sizes[i]; ++j) { + *parameter_ptr++ = inputs[i][j].a; + } + jacobian_ptr += num_residuals * parameter_block_sizes[i]; + } + + if (!cost_function_->Evaluate(parameter_blocks.get(), + residuals.get(), + jacobian_blocks.get())) { + return false; + } + + // Now that we have the incoming Jets, which are carrying the + // partial derivatives of each of the inputs w.r.t to some other + // underlying parameters. The derivative of the outputs of the + // cost function w.r.t to the same underlying parameters can now + // be computed by applying the chain rule. + // + // d output[i] d output[i] d input[j] + // -------------- = sum_j ----------- * ------------ + // d parameter[k] d input[j] d parameter[k] + // + // d input[j] + // -------------- = inputs[j], so + // d parameter[k] + // + // outputJet[i] = sum_k jacobian[i][k] * inputJet[k] + // + // The following loop, iterates over the residuals, computing one + // output jet at a time. + for (int i = 0; i < num_residuals; ++i) { + output[i].a = residuals[i]; + output[i].v.setZero(); + + for (int j = 0; j < num_parameter_blocks; ++j) { + const int32 block_size = parameter_block_sizes[j]; + for (int k = 0; k < parameter_block_sizes[j]; ++k) { + output[i].v += + jacobian_blocks[j][i * block_size + k] * inputs[j][k].v; + } + } + } + + return true; + } + + private: + internal::scoped_ptr cost_function_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_DYNAMIC_COST_FUNCTION_TO_FUNCTOR_H_ diff --git a/include/ceres/dynamic_numeric_diff_cost_function.h b/include/ceres/dynamic_numeric_diff_cost_function.h new file mode 100644 index 0000000..a011ac3 --- /dev/null +++ b/include/ceres/dynamic_numeric_diff_cost_function.h @@ -0,0 +1,180 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: mierle@gmail.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) +// thadh@gmail.com (Thad Hughes) +// tbennun@gmail.com (Tal Ben-Nun) + +#ifndef CERES_PUBLIC_DYNAMIC_NUMERIC_DIFF_COST_FUNCTION_H_ +#define CERES_PUBLIC_DYNAMIC_NUMERIC_DIFF_COST_FUNCTION_H_ + +#include +#include +#include + +#include "ceres/dynamic_cost_function.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/numeric_diff.h" +#include "ceres/numeric_diff_options.h" +#include "glog/logging.h" + +namespace ceres { + +// This numeric diff implementation differs from the one found in +// numeric_diff_cost_function.h by supporting numericdiff on cost +// functions with variable numbers of parameters with variable +// sizes. With the other implementation, all the sizes (both the +// number of parameter blocks and the size of each block) must be +// fixed at compile time. +// +// The functor API differs slightly from the API for fixed size +// numeric diff; the expected interface for the cost functors is: +// +// struct MyCostFunctor { +// bool operator()(double const* const* parameters, double* residuals) const { +// // Use parameters[i] to access the i'th parameter block. +// } +// } +// +// Since the sizing of the parameters is done at runtime, you must +// also specify the sizes after creating the +// DynamicNumericDiffCostFunction. For example: +// +// DynamicAutoDiffCostFunction cost_function( +// new MyCostFunctor()); +// cost_function.AddParameterBlock(5); +// cost_function.AddParameterBlock(10); +// cost_function.SetNumResiduals(21); +template +class DynamicNumericDiffCostFunction : public DynamicCostFunction { + public: + explicit DynamicNumericDiffCostFunction( + const CostFunctor* functor, + Ownership ownership = TAKE_OWNERSHIP, + const NumericDiffOptions& options = NumericDiffOptions()) + : functor_(functor), + ownership_(ownership), + options_(options) { + } + + virtual ~DynamicNumericDiffCostFunction() { + if (ownership_ != TAKE_OWNERSHIP) { + functor_.release(); + } + } + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + using internal::NumericDiff; + CHECK_GT(num_residuals(), 0) + << "You must call DynamicNumericDiffCostFunction::SetNumResiduals() " + << "before DynamicNumericDiffCostFunction::Evaluate()."; + + const std::vector& block_sizes = parameter_block_sizes(); + CHECK(!block_sizes.empty()) + << "You must call DynamicNumericDiffCostFunction::AddParameterBlock() " + << "before DynamicNumericDiffCostFunction::Evaluate()."; + + const bool status = EvaluateCostFunctor(parameters, residuals); + if (jacobians == NULL || !status) { + return status; + } + + // Create local space for a copy of the parameters which will get mutated. + int parameters_size = accumulate(block_sizes.begin(), block_sizes.end(), 0); + std::vector parameters_copy(parameters_size); + std::vector parameters_references_copy(block_sizes.size()); + parameters_references_copy[0] = ¶meters_copy[0]; + for (size_t block = 1; block < block_sizes.size(); ++block) { + parameters_references_copy[block] = parameters_references_copy[block - 1] + + block_sizes[block - 1]; + } + + // Copy the parameters into the local temp space. + for (size_t block = 0; block < block_sizes.size(); ++block) { + memcpy(parameters_references_copy[block], + parameters[block], + block_sizes[block] * sizeof(*parameters[block])); + } + + for (size_t block = 0; block < block_sizes.size(); ++block) { + if (jacobians[block] != NULL && + !NumericDiff::EvaluateJacobianForParameterBlock( + functor_.get(), + residuals, + options_, + this->num_residuals(), + block, + block_sizes[block], + ¶meters_references_copy[0], + jacobians[block])) { + return false; + } + } + return true; + } + + private: + bool EvaluateCostFunctor(double const* const* parameters, + double* residuals) const { + return EvaluateCostFunctorImpl(functor_.get(), + parameters, + residuals, + functor_.get()); + } + + // Helper templates to allow evaluation of a functor or a + // CostFunction. + bool EvaluateCostFunctorImpl(const CostFunctor* functor, + double const* const* parameters, + double* residuals, + const void* /* NOT USED */) const { + return (*functor)(parameters, residuals); + } + + bool EvaluateCostFunctorImpl(const CostFunctor* functor, + double const* const* parameters, + double* residuals, + const CostFunction* /* NOT USED */) const { + return functor->Evaluate(parameters, residuals, NULL); + } + + internal::scoped_ptr functor_; + Ownership ownership_; + NumericDiffOptions options_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_DYNAMIC_AUTODIFF_COST_FUNCTION_H_ diff --git a/include/ceres/fpclassify.h b/include/ceres/fpclassify.h new file mode 100644 index 0000000..bc2dc90 --- /dev/null +++ b/include/ceres/fpclassify.h @@ -0,0 +1,70 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Portable floating point classification. The names are picked such that they +// do not collide with macros. For example, "isnan" in C99 is a macro and hence +// does not respect namespaces. +// +// TODO(keir): Finish porting! + +#ifndef CERES_PUBLIC_FPCLASSIFY_H_ +#define CERES_PUBLIC_FPCLASSIFY_H_ + +#if defined(_MSC_VER) +#include +#endif + +#include + +namespace ceres { + +#if defined(_MSC_VER) + +inline bool IsFinite (double x) { return _finite(x) != 0; } +inline bool IsInfinite(double x) { return _finite(x) == 0 && _isnan(x) == 0; } +inline bool IsNaN (double x) { return _isnan(x) != 0; } +inline bool IsNormal (double x) { // NOLINT + const int classification = _fpclass(x); + return (classification == _FPCLASS_NN || classification == _FPCLASS_PN); +} + +# else + +// These definitions are for the normal Unix suspects. +inline bool IsFinite (double x) { return std::isfinite(x); } +inline bool IsInfinite(double x) { return std::isinf(x); } +inline bool IsNaN (double x) { return std::isnan(x); } +inline bool IsNormal (double x) { return std::isnormal(x); } + +#endif + +} // namespace ceres + +#endif // CERES_PUBLIC_FPCLASSIFY_H_ diff --git a/include/ceres/gradient_checker.h b/include/ceres/gradient_checker.h new file mode 100644 index 0000000..c8ac729 --- /dev/null +++ b/include/ceres/gradient_checker.h @@ -0,0 +1,149 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// Copyright 2007 Google Inc. All Rights Reserved. +// +// Authors: wjr@google.com (William Rucklidge), +// keir@google.com (Keir Mierle), +// dgossow@google.com (David Gossow) + +#ifndef CERES_PUBLIC_GRADIENT_CHECKER_H_ +#define CERES_PUBLIC_GRADIENT_CHECKER_H_ + +#include +#include + +#include "ceres/cost_function.h" +#include "ceres/dynamic_numeric_diff_cost_function.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/fixed_array.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/local_parameterization.h" +#include "glog/logging.h" + +namespace ceres { + +// GradientChecker compares the Jacobians returned by a cost function against +// derivatives estimated using finite differencing. +// +// The condition enforced is that +// +// (J_actual(i, j) - J_numeric(i, j)) +// ------------------------------------ < relative_precision +// max(J_actual(i, j), J_numeric(i, j)) +// +// where J_actual(i, j) is the jacobian as computed by the supplied cost +// function (by the user) multiplied by the local parameterization Jacobian +// and J_numeric is the jacobian as computed by finite differences, multiplied +// by the local parameterization Jacobian as well. +// +// How to use: Fill in an array of pointers to parameter blocks for your +// CostFunction, and then call Probe(). Check that the return value is 'true'. +class CERES_EXPORT GradientChecker { + public: + // This will not take ownership of the cost function or local + // parameterizations. + // + // function: The cost function to probe. + // local_parameterization: A vector of local parameterizations for each + // parameter. May be NULL or contain NULL pointers to indicate that the + // respective parameter does not have a local parameterization. + // options: Options to use for numerical differentiation. + GradientChecker( + const CostFunction* function, + const std::vector* local_parameterizations, + const NumericDiffOptions& options); + + // Contains results from a call to Probe for later inspection. + struct CERES_EXPORT ProbeResults { + // The return value of the cost function. + bool return_value; + + // Computed residual vector. + Vector residuals; + + // The sizes of the Jacobians below are dictated by the cost function's + // parameter block size and residual block sizes. If a parameter block + // has a local parameterization associated with it, the size of the "local" + // Jacobian will be determined by the local parameterization dimension and + // residual block size, otherwise it will be identical to the regular + // Jacobian. + + // Derivatives as computed by the cost function. + std::vector jacobians; + + // Derivatives as computed by the cost function in local space. + std::vector local_jacobians; + + // Derivatives as computed by nuerical differentiation in local space. + std::vector numeric_jacobians; + + // Derivatives as computed by nuerical differentiation in local space. + std::vector local_numeric_jacobians; + + // Contains the maximum relative error found in the local Jacobians. + double maximum_relative_error; + + // If an error was detected, this will contain a detailed description of + // that error. + std::string error_log; + }; + + // Call the cost function, compute alternative Jacobians using finite + // differencing and compare results. If local parameterizations are given, + // the Jacobians will be multiplied by the local parameterization Jacobians + // before performing the check, which effectively means that all errors along + // the null space of the local parameterization will be ignored. + // Returns false if the Jacobians don't match, the cost function return false, + // or if the cost function returns different residual when called with a + // Jacobian output argument vs. calling it without. Otherwise returns true. + // + // parameters: The parameter values at which to probe. + // relative_precision: A threshold for the relative difference between the + // Jacobians. If the Jacobians differ by more than this amount, then the + // probe fails. + // results: On return, the Jacobians (and other information) will be stored + // here. May be NULL. + // + // Returns true if no problems are detected and the difference between the + // Jacobians is less than error_tolerance. + bool Probe(double const* const* parameters, + double relative_precision, + ProbeResults* results) const; + + private: + CERES_DISALLOW_IMPLICIT_CONSTRUCTORS(GradientChecker); + + std::vector local_parameterizations_; + const CostFunction* function_; + internal::scoped_ptr finite_diff_cost_function_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_GRADIENT_CHECKER_H_ diff --git a/include/ceres/gradient_problem.h b/include/ceres/gradient_problem.h new file mode 100644 index 0000000..1226a4c --- /dev/null +++ b/include/ceres/gradient_problem.h @@ -0,0 +1,127 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_GRADIENT_PROBLEM_H_ +#define CERES_PUBLIC_GRADIENT_PROBLEM_H_ + +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/local_parameterization.h" + +namespace ceres { + +class FirstOrderFunction; + +// Instances of GradientProblem represent general non-linear +// optimization problems that must be solved using just the value of +// the objective function and its gradient. Unlike the Problem class, +// which can only be used to model non-linear least squares problems, +// instances of GradientProblem not restricted in the form of the +// objective function. +// +// Structurally GradientProblem is a composition of a +// FirstOrderFunction and optionally a LocalParameterization. +// +// The FirstOrderFunction is responsible for evaluating the cost and +// gradient of the objective function. +// +// The LocalParameterization is responsible for going back and forth +// between the ambient space and the local tangent space. (See +// local_parameterization.h for more details). When a +// LocalParameterization is not provided, then the tangent space is +// assumed to coincide with the ambient Euclidean space that the +// gradient vector lives in. +// +// Example usage: +// +// The following demonstrate the problem construction for Rosenbrock's function +// +// f(x,y) = (1-x)^2 + 100(y - x^2)^2; +// +// class Rosenbrock : public ceres::FirstOrderFunction { +// public: +// virtual ~Rosenbrock() {} +// +// virtual bool Evaluate(const double* parameters, +// double* cost, +// double* gradient) const { +// const double x = parameters[0]; +// const double y = parameters[1]; +// +// cost[0] = (1.0 - x) * (1.0 - x) + 100.0 * (y - x * x) * (y - x * x); +// if (gradient != NULL) { +// gradient[0] = -2.0 * (1.0 - x) - 200.0 * (y - x * x) * 2.0 * x; +// gradient[1] = 200.0 * (y - x * x); +// } +// return true; +// }; +// +// virtual int NumParameters() const { return 2; }; +// }; +// +// ceres::GradientProblem problem(new Rosenbrock()); +class CERES_EXPORT GradientProblem { + public: + // Takes ownership of the function. + explicit GradientProblem(FirstOrderFunction* function); + + // Takes ownership of the function and the parameterization. + GradientProblem(FirstOrderFunction* function, + LocalParameterization* parameterization); + + int NumParameters() const; + int NumLocalParameters() const; + + // This call is not thread safe. + bool Evaluate(const double* parameters, double* cost, double* gradient) const; + bool Plus(const double* x, const double* delta, double* x_plus_delta) const; + + private: + internal::scoped_ptr function_; + internal::scoped_ptr parameterization_; + internal::scoped_array scratch_; +}; + +// A FirstOrderFunction object implements the evaluation of a function +// and its gradient. +class CERES_EXPORT FirstOrderFunction { + public: + virtual ~FirstOrderFunction() {} + // cost is never NULL. gradient may be null. + virtual bool Evaluate(const double* const parameters, + double* cost, + double* gradient) const = 0; + virtual int NumParameters() const = 0; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_GRADIENT_PROBLEM_H_ diff --git a/include/ceres/gradient_problem_solver.h b/include/ceres/gradient_problem_solver.h new file mode 100644 index 0000000..31fed84 --- /dev/null +++ b/include/ceres/gradient_problem_solver.h @@ -0,0 +1,370 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_GRADIENT_PROBLEM_SOLVER_H_ +#define CERES_PUBLIC_GRADIENT_PROBLEM_SOLVER_H_ + +#include +#include +#include +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/iteration_callback.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +class GradientProblem; + +class CERES_EXPORT GradientProblemSolver { + public: + virtual ~GradientProblemSolver(); + + // The options structure contains, not surprisingly, options that control how + // the solver operates. The defaults should be suitable for a wide range of + // problems; however, better performance is often obtainable with tweaking. + // + // The constants are defined inside types.h + struct CERES_EXPORT Options { + // Default constructor that sets up a generic sparse problem. + Options() { + line_search_direction_type = LBFGS; + line_search_type = WOLFE; + nonlinear_conjugate_gradient_type = FLETCHER_REEVES; + max_lbfgs_rank = 20; + use_approximate_eigenvalue_bfgs_scaling = false; + line_search_interpolation_type = CUBIC; + min_line_search_step_size = 1e-9; + line_search_sufficient_function_decrease = 1e-4; + max_line_search_step_contraction = 1e-3; + min_line_search_step_contraction = 0.6; + max_num_line_search_step_size_iterations = 20; + max_num_line_search_direction_restarts = 5; + line_search_sufficient_curvature_decrease = 0.9; + max_line_search_step_expansion = 10.0; + max_num_iterations = 50; + max_solver_time_in_seconds = 1e9; + function_tolerance = 1e-6; + gradient_tolerance = 1e-10; + parameter_tolerance = 1e-8; + logging_type = PER_MINIMIZER_ITERATION; + minimizer_progress_to_stdout = false; + } + + // Returns true if the options struct has a valid + // configuration. Returns false otherwise, and fills in *error + // with a message describing the problem. + bool IsValid(std::string* error) const; + + // Minimizer options ---------------------------------------- + LineSearchDirectionType line_search_direction_type; + LineSearchType line_search_type; + NonlinearConjugateGradientType nonlinear_conjugate_gradient_type; + + // The LBFGS hessian approximation is a low rank approximation to + // the inverse of the Hessian matrix. The rank of the + // approximation determines (linearly) the space and time + // complexity of using the approximation. Higher the rank, the + // better is the quality of the approximation. The increase in + // quality is however is bounded for a number of reasons. + // + // 1. The method only uses secant information and not actual + // derivatives. + // + // 2. The Hessian approximation is constrained to be positive + // definite. + // + // So increasing this rank to a large number will cost time and + // space complexity without the corresponding increase in solution + // quality. There are no hard and fast rules for choosing the + // maximum rank. The best choice usually requires some problem + // specific experimentation. + // + // For more theoretical and implementation details of the LBFGS + // method, please see: + // + // Nocedal, J. (1980). "Updating Quasi-Newton Matrices with + // Limited Storage". Mathematics of Computation 35 (151): 773–782. + int max_lbfgs_rank; + + // As part of the (L)BFGS update step (BFGS) / right-multiply step (L-BFGS), + // the initial inverse Hessian approximation is taken to be the Identity. + // However, Oren showed that using instead I * \gamma, where \gamma is + // chosen to approximate an eigenvalue of the true inverse Hessian can + // result in improved convergence in a wide variety of cases. Setting + // use_approximate_eigenvalue_bfgs_scaling to true enables this scaling. + // + // It is important to note that approximate eigenvalue scaling does not + // always improve convergence, and that it can in fact significantly degrade + // performance for certain classes of problem, which is why it is disabled + // by default. In particular it can degrade performance when the + // sensitivity of the problem to different parameters varies significantly, + // as in this case a single scalar factor fails to capture this variation + // and detrimentally downscales parts of the jacobian approximation which + // correspond to low-sensitivity parameters. It can also reduce the + // robustness of the solution to errors in the jacobians. + // + // Oren S.S., Self-scaling variable metric (SSVM) algorithms + // Part II: Implementation and experiments, Management Science, + // 20(5), 863-874, 1974. + bool use_approximate_eigenvalue_bfgs_scaling; + + // Degree of the polynomial used to approximate the objective + // function. Valid values are BISECTION, QUADRATIC and CUBIC. + // + // BISECTION corresponds to pure backtracking search with no + // interpolation. + LineSearchInterpolationType line_search_interpolation_type; + + // If during the line search, the step_size falls below this + // value, it is truncated to zero. + double min_line_search_step_size; + + // Line search parameters. + + // Solving the line search problem exactly is computationally + // prohibitive. Fortunately, line search based optimization + // algorithms can still guarantee convergence if instead of an + // exact solution, the line search algorithm returns a solution + // which decreases the value of the objective function + // sufficiently. More precisely, we are looking for a step_size + // s.t. + // + // f(step_size) <= f(0) + sufficient_decrease * f'(0) * step_size + // + double line_search_sufficient_function_decrease; + + // In each iteration of the line search, + // + // new_step_size >= max_line_search_step_contraction * step_size + // + // Note that by definition, for contraction: + // + // 0 < max_step_contraction < min_step_contraction < 1 + // + double max_line_search_step_contraction; + + // In each iteration of the line search, + // + // new_step_size <= min_line_search_step_contraction * step_size + // + // Note that by definition, for contraction: + // + // 0 < max_step_contraction < min_step_contraction < 1 + // + double min_line_search_step_contraction; + + // Maximum number of trial step size iterations during each line search, + // if a step size satisfying the search conditions cannot be found within + // this number of trials, the line search will terminate. + int max_num_line_search_step_size_iterations; + + // Maximum number of restarts of the line search direction algorithm before + // terminating the optimization. Restarts of the line search direction + // algorithm occur when the current algorithm fails to produce a new descent + // direction. This typically indicates a numerical failure, or a breakdown + // in the validity of the approximations used. + int max_num_line_search_direction_restarts; + + // The strong Wolfe conditions consist of the Armijo sufficient + // decrease condition, and an additional requirement that the + // step-size be chosen s.t. the _magnitude_ ('strong' Wolfe + // conditions) of the gradient along the search direction + // decreases sufficiently. Precisely, this second condition + // is that we seek a step_size s.t. + // + // |f'(step_size)| <= sufficient_curvature_decrease * |f'(0)| + // + // Where f() is the line search objective and f'() is the derivative + // of f w.r.t step_size (d f / d step_size). + double line_search_sufficient_curvature_decrease; + + // During the bracketing phase of the Wolfe search, the step size is + // increased until either a point satisfying the Wolfe conditions is + // found, or an upper bound for a bracket containing a point satisfying + // the conditions is found. Precisely, at each iteration of the + // expansion: + // + // new_step_size <= max_step_expansion * step_size. + // + // By definition for expansion, max_step_expansion > 1.0. + double max_line_search_step_expansion; + + // Maximum number of iterations for the minimizer to run for. + int max_num_iterations; + + // Maximum time for which the minimizer should run for. + double max_solver_time_in_seconds; + + // Minimizer terminates when + // + // (new_cost - old_cost) < function_tolerance * old_cost; + // + double function_tolerance; + + // Minimizer terminates when + // + // max_i |x - Project(Plus(x, -g(x))| < gradient_tolerance + // + // This value should typically be 1e-4 * function_tolerance. + double gradient_tolerance; + + // Minimizer terminates when + // + // |step|_2 <= parameter_tolerance * ( |x|_2 + parameter_tolerance) + // + double parameter_tolerance; + + // Logging options --------------------------------------------------------- + + LoggingType logging_type; + + // By default the Minimizer progress is logged to VLOG(1), which + // is sent to STDERR depending on the vlog level. If this flag is + // set to true, and logging_type is not SILENT, the logging output + // is sent to STDOUT. + bool minimizer_progress_to_stdout; + + // Callbacks that are executed at the end of each iteration of the + // Minimizer. An iteration may terminate midway, either due to + // numerical failures or because one of the convergence tests has + // been satisfied. In this case none of the callbacks are + // executed. + + // Callbacks are executed in the order that they are specified in + // this vector. By default, parameter blocks are updated only at + // the end of the optimization, i.e when the Minimizer + // terminates. This behaviour is controlled by + // update_state_every_variable. If the user wishes to have access + // to the update parameter blocks when his/her callbacks are + // executed, then set update_state_every_iteration to true. + // + // The solver does NOT take ownership of these pointers. + std::vector callbacks; + }; + + struct CERES_EXPORT Summary { + Summary(); + + // A brief one line description of the state of the solver after + // termination. + std::string BriefReport() const; + + // A full multiline description of the state of the solver after + // termination. + std::string FullReport() const; + + bool IsSolutionUsable() const; + + // Minimizer summary ------------------------------------------------- + TerminationType termination_type; + + // Reason why the solver terminated. + std::string message; + + // Cost of the problem (value of the objective function) before + // the optimization. + double initial_cost; + + // Cost of the problem (value of the objective function) after the + // optimization. + double final_cost; + + // IterationSummary for each minimizer iteration in order. + std::vector iterations; + + // Number of times the cost (and not the gradient) was evaluated. + int num_cost_evaluations; + + // Number of times the gradient (and the cost) were evaluated. + int num_gradient_evaluations; + + // Sum total of all time spent inside Ceres when Solve is called. + double total_time_in_seconds; + + // Time (in seconds) spent evaluating the cost. + double cost_evaluation_time_in_seconds; + + // Time (in seconds) spent evaluating the gradient. + double gradient_evaluation_time_in_seconds; + + // Time (in seconds) spent minimizing the interpolating polynomial + // to compute the next candidate step size as part of a line search. + double line_search_polynomial_minimization_time_in_seconds; + + // Number of parameters in the probem. + int num_parameters; + + // Dimension of the tangent space of the problem. + int num_local_parameters; + + // Type of line search direction used. + LineSearchDirectionType line_search_direction_type; + + // Type of the line search algorithm used. + LineSearchType line_search_type; + + // When performing line search, the degree of the polynomial used + // to approximate the objective function. + LineSearchInterpolationType line_search_interpolation_type; + + // If the line search direction is NONLINEAR_CONJUGATE_GRADIENT, + // then this indicates the particular variant of non-linear + // conjugate gradient used. + NonlinearConjugateGradientType nonlinear_conjugate_gradient_type; + + // If the type of the line search direction is LBFGS, then this + // indicates the rank of the Hessian approximation. + int max_lbfgs_rank; + }; + + // Once a least squares problem has been built, this function takes + // the problem and optimizes it based on the values of the options + // parameters. Upon return, a detailed summary of the work performed + // by the preprocessor, the non-linear minmizer and the linear + // solver are reported in the summary object. + virtual void Solve(const GradientProblemSolver::Options& options, + const GradientProblem& problem, + double* parameters, + GradientProblemSolver::Summary* summary); +}; + +// Helper function which avoids going through the interface. +CERES_EXPORT void Solve(const GradientProblemSolver::Options& options, + const GradientProblem& problem, + double* parameters, + GradientProblemSolver::Summary* summary); + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_GRADIENT_PROBLEM_SOLVER_H_ diff --git a/include/ceres/internal/autodiff.h b/include/ceres/internal/autodiff.h new file mode 100644 index 0000000..bf5fb77 --- /dev/null +++ b/include/ceres/internal/autodiff.h @@ -0,0 +1,324 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Computation of the Jacobian matrix for vector-valued functions of multiple +// variables, using automatic differentiation based on the implementation of +// dual numbers in jet.h. Before reading the rest of this file, it is adivsable +// to read jet.h's header comment in detail. +// +// The helper wrapper AutoDiff::Differentiate() computes the jacobian of +// functors with templated operator() taking this form: +// +// struct F { +// template +// bool operator()(const T *x, const T *y, ..., T *z) { +// // Compute z[] based on x[], y[], ... +// // return true if computation succeeded, false otherwise. +// } +// }; +// +// All inputs and outputs may be vector-valued. +// +// To understand how jets are used to compute the jacobian, a +// picture may help. Consider a vector-valued function, F, returning 3 +// dimensions and taking a vector-valued parameter of 4 dimensions: +// +// y x +// [ * ] F [ * ] +// [ * ] <--- [ * ] +// [ * ] [ * ] +// [ * ] +// +// Similar to the 2-parameter example for f described in jet.h, computing the +// jacobian dy/dx is done by substutiting a suitable jet object for x and all +// intermediate steps of the computation of F. Since x is has 4 dimensions, use +// a Jet. +// +// Before substituting a jet object for x, the dual components are set +// appropriately for each dimension of x: +// +// y x +// [ * | * * * * ] f [ * | 1 0 0 0 ] x0 +// [ * | * * * * ] <--- [ * | 0 1 0 0 ] x1 +// [ * | * * * * ] [ * | 0 0 1 0 ] x2 +// ---+--- [ * | 0 0 0 1 ] x3 +// | ^ ^ ^ ^ +// dy/dx | | | +----- infinitesimal for x3 +// | | +------- infinitesimal for x2 +// | +--------- infinitesimal for x1 +// +----------- infinitesimal for x0 +// +// The reason to set the internal 4x4 submatrix to the identity is that we wish +// to take the derivative of y separately with respect to each dimension of x. +// Each column of the 4x4 identity is therefore for a single component of the +// independent variable x. +// +// Then the jacobian of the mapping, dy/dx, is the 3x4 sub-matrix of the +// extended y vector, indicated in the above diagram. +// +// Functors with multiple parameters +// --------------------------------- +// In practice, it is often convenient to use a function f of two or more +// vector-valued parameters, for example, x[3] and z[6]. Unfortunately, the jet +// framework is designed for a single-parameter vector-valued input. The wrapper +// in this file addresses this issue adding support for functions with one or +// more parameter vectors. +// +// To support multiple parameters, all the parameter vectors are concatenated +// into one and treated as a single parameter vector, except that since the +// functor expects different inputs, we need to construct the jets as if they +// were part of a single parameter vector. The extended jets are passed +// separately for each parameter. +// +// For example, consider a functor F taking two vector parameters, p[2] and +// q[3], and producing an output y[4]: +// +// struct F { +// template +// bool operator()(const T *p, const T *q, T *z) { +// // ... +// } +// }; +// +// In this case, the necessary jet type is Jet. Here is a +// visualization of the jet objects in this case: +// +// Dual components for p ----+ +// | +// -+- +// y [ * | 1 0 | 0 0 0 ] --- p[0] +// [ * | 0 1 | 0 0 0 ] --- p[1] +// [ * | . . | + + + ] | +// [ * | . . | + + + ] v +// [ * | . . | + + + ] <--- F(p, q) +// [ * | . . | + + + ] ^ +// ^^^ ^^^^^ | +// dy/dp dy/dq [ * | 0 0 | 1 0 0 ] --- q[0] +// [ * | 0 0 | 0 1 0 ] --- q[1] +// [ * | 0 0 | 0 0 1 ] --- q[2] +// --+-- +// | +// Dual components for q --------------+ +// +// where the 4x2 submatrix (marked with ".") and 4x3 submatrix (marked with "+" +// of y in the above diagram are the derivatives of y with respect to p and q +// respectively. This is how autodiff works for functors taking multiple vector +// valued arguments (up to 6). +// +// Jacobian NULL pointers +// ---------------------- +// In general, the functions below will accept NULL pointers for all or some of +// the Jacobian parameters, meaning that those Jacobians will not be computed. + +#ifndef CERES_PUBLIC_INTERNAL_AUTODIFF_H_ +#define CERES_PUBLIC_INTERNAL_AUTODIFF_H_ + +#include + +#include "ceres/jet.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/fixed_array.h" +#include "ceres/internal/variadic_evaluate.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +// Extends src by a 1st order pertubation for every dimension and puts it in +// dst. The size of src is N. Since this is also used for perturbations in +// blocked arrays, offset is used to shift which part of the jet the +// perturbation occurs. This is used to set up the extended x augmented by an +// identity matrix. The JetT type should be a Jet type, and T should be a +// numeric type (e.g. double). For example, +// +// 0 1 2 3 4 5 6 7 8 +// dst[0] [ * | . . | 1 0 0 | . . . ] +// dst[1] [ * | . . | 0 1 0 | . . . ] +// dst[2] [ * | . . | 0 0 1 | . . . ] +// +// is what would get put in dst if N was 3, offset was 3, and the jet type JetT +// was 8-dimensional. +template +inline void Make1stOrderPerturbation(int offset, const T* src, JetT* dst) { + DCHECK(src); + DCHECK(dst); + for (int j = 0; j < N; ++j) { + dst[j].a = src[j]; + dst[j].v.setZero(); + dst[j].v[offset + j] = T(1.0); + } +} + +// Takes the 0th order part of src, assumed to be a Jet type, and puts it in +// dst. This is used to pick out the "vector" part of the extended y. +template +inline void Take0thOrderPart(int M, const JetT *src, T dst) { + DCHECK(src); + for (int i = 0; i < M; ++i) { + dst[i] = src[i].a; + } +} + +// Takes N 1st order parts, starting at index N0, and puts them in the M x N +// matrix 'dst'. This is used to pick out the "matrix" parts of the extended y. +template +inline void Take1stOrderPart(const int M, const JetT *src, T *dst) { + DCHECK(src); + DCHECK(dst); + for (int i = 0; i < M; ++i) { + Eigen::Map >(dst + N * i, N) = + src[i].v.template segment(N0); + } +} + +// This is in a struct because default template parameters on a +// function are not supported in C++03 (though it is available in +// C++0x). N0 through N5 are the dimension of the input arguments to +// the user supplied functor. +template +struct AutoDiff { + static bool Differentiate(const Functor& functor, + T const *const *parameters, + int num_outputs, + T *function_value, + T **jacobians) { + // This block breaks the 80 column rule to keep it somewhat readable. + DCHECK_GT(num_outputs, 0); + DCHECK((!N1 && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && (N2 > 0) && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && (N9 > 0))) // NOLINT + << "Zero block cannot precede a non-zero block. Block sizes are " + << "(ignore trailing 0s): " << N0 << ", " << N1 << ", " << N2 << ", " + << N3 << ", " << N4 << ", " << N5 << ", " << N6 << ", " << N7 << ", " + << N8 << ", " << N9; + + typedef Jet JetT; + FixedArray x( + N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9 + num_outputs); + + // These are the positions of the respective jets in the fixed array x. + const int jet0 = 0; + const int jet1 = N0; + const int jet2 = N0 + N1; + const int jet3 = N0 + N1 + N2; + const int jet4 = N0 + N1 + N2 + N3; + const int jet5 = N0 + N1 + N2 + N3 + N4; + const int jet6 = N0 + N1 + N2 + N3 + N4 + N5; + const int jet7 = N0 + N1 + N2 + N3 + N4 + N5 + N6; + const int jet8 = N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7; + const int jet9 = N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8; + + const JetT *unpacked_parameters[10] = { + x.get() + jet0, + x.get() + jet1, + x.get() + jet2, + x.get() + jet3, + x.get() + jet4, + x.get() + jet5, + x.get() + jet6, + x.get() + jet7, + x.get() + jet8, + x.get() + jet9, + }; + + JetT* output = x.get() + N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9; + + // Invalidate the output Jets, so that we can detect if the user + // did not assign values to all of them. + for (int i = 0; i < num_outputs; ++i) { + output[i].a = kImpossibleValue; + output[i].v.setConstant(kImpossibleValue); + } + +#define CERES_MAKE_1ST_ORDER_PERTURBATION(i) \ + if (N ## i) { \ + internal::Make1stOrderPerturbation( \ + jet ## i, \ + parameters[i], \ + x.get() + jet ## i); \ + } + CERES_MAKE_1ST_ORDER_PERTURBATION(0); + CERES_MAKE_1ST_ORDER_PERTURBATION(1); + CERES_MAKE_1ST_ORDER_PERTURBATION(2); + CERES_MAKE_1ST_ORDER_PERTURBATION(3); + CERES_MAKE_1ST_ORDER_PERTURBATION(4); + CERES_MAKE_1ST_ORDER_PERTURBATION(5); + CERES_MAKE_1ST_ORDER_PERTURBATION(6); + CERES_MAKE_1ST_ORDER_PERTURBATION(7); + CERES_MAKE_1ST_ORDER_PERTURBATION(8); + CERES_MAKE_1ST_ORDER_PERTURBATION(9); +#undef CERES_MAKE_1ST_ORDER_PERTURBATION + + if (!VariadicEvaluate::Call( + functor, unpacked_parameters, output)) { + return false; + } + + internal::Take0thOrderPart(num_outputs, output, function_value); + +#define CERES_TAKE_1ST_ORDER_PERTURBATION(i) \ + if (N ## i) { \ + if (jacobians[i]) { \ + internal::Take1stOrderPart(num_outputs, \ + output, \ + jacobians[i]); \ + } \ + } + CERES_TAKE_1ST_ORDER_PERTURBATION(0); + CERES_TAKE_1ST_ORDER_PERTURBATION(1); + CERES_TAKE_1ST_ORDER_PERTURBATION(2); + CERES_TAKE_1ST_ORDER_PERTURBATION(3); + CERES_TAKE_1ST_ORDER_PERTURBATION(4); + CERES_TAKE_1ST_ORDER_PERTURBATION(5); + CERES_TAKE_1ST_ORDER_PERTURBATION(6); + CERES_TAKE_1ST_ORDER_PERTURBATION(7); + CERES_TAKE_1ST_ORDER_PERTURBATION(8); + CERES_TAKE_1ST_ORDER_PERTURBATION(9); +#undef CERES_TAKE_1ST_ORDER_PERTURBATION + return true; + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_AUTODIFF_H_ diff --git a/include/ceres/internal/disable_warnings.h b/include/ceres/internal/disable_warnings.h new file mode 100644 index 0000000..094124f --- /dev/null +++ b/include/ceres/internal/disable_warnings.h @@ -0,0 +1,44 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// This file has the sole purpose to silence warnings when including Ceres. + +// This is not your usual header guard. The macro CERES_WARNINGS_DISABLED +// shows up again in reenable_warnings.h. +#ifndef CERES_WARNINGS_DISABLED +#define CERES_WARNINGS_DISABLED + +#ifdef _MSC_VER +#pragma warning( push ) +// Disable the warning C4251 which is trigerred by stl classes in +// Ceres' public interface. To quote MSDN: "C4251 can be ignored " +// "if you are deriving from a type in the Standard C++ Library" +#pragma warning( disable : 4251 ) +#endif + +#endif // CERES_WARNINGS_DISABLED diff --git a/include/ceres/internal/eigen.h b/include/ceres/internal/eigen.h new file mode 100644 index 0000000..7138804 --- /dev/null +++ b/include/ceres/internal/eigen.h @@ -0,0 +1,93 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_EIGEN_H_ +#define CERES_INTERNAL_EIGEN_H_ + +#include "Eigen/Core" + +namespace ceres { + +typedef Eigen::Matrix Vector; +typedef Eigen::Matrix Matrix; +typedef Eigen::Map VectorRef; +typedef Eigen::Map MatrixRef; +typedef Eigen::Map ConstVectorRef; +typedef Eigen::Map ConstMatrixRef; + +// Column major matrices for DenseSparseMatrix/DenseQRSolver +typedef Eigen::Matrix ColMajorMatrix; + +typedef Eigen::Map > ColMajorMatrixRef; + +typedef Eigen::Map > ConstColMajorMatrixRef; + + + +// C++ does not support templated typdefs, thus the need for this +// struct so that we can support statically sized Matrix and Maps. +template +struct EigenTypes { + typedef Eigen::Matrix + Matrix; + + typedef Eigen::Map< + Eigen::Matrix > + MatrixRef; + + typedef Eigen::Matrix + Vector; + + typedef Eigen::Map < + Eigen::Matrix > + VectorRef; + + + typedef Eigen::Map< + const Eigen::Matrix > + ConstMatrixRef; + + typedef Eigen::Map < + const Eigen::Matrix > + ConstVectorRef; +}; + +} // namespace ceres + +#endif // CERES_INTERNAL_EIGEN_H_ diff --git a/include/ceres/internal/fixed_array.h b/include/ceres/internal/fixed_array.h new file mode 100644 index 0000000..387298c --- /dev/null +++ b/include/ceres/internal/fixed_array.h @@ -0,0 +1,191 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: rennie@google.com (Jeffrey Rennie) +// Author: sanjay@google.com (Sanjay Ghemawat) -- renamed to FixedArray + +#ifndef CERES_PUBLIC_INTERNAL_FIXED_ARRAY_H_ +#define CERES_PUBLIC_INTERNAL_FIXED_ARRAY_H_ + +#include +#include "Eigen/Core" +#include "ceres/internal/macros.h" +#include "ceres/internal/manual_constructor.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +// A FixedArray represents a non-resizable array of T where the +// length of the array does not need to be a compile time constant. +// +// FixedArray allocates small arrays inline, and large arrays on +// the heap. It is a good replacement for non-standard and deprecated +// uses of alloca() and variable length arrays (a GCC extension). +// +// FixedArray keeps performance fast for small arrays, because it +// avoids heap operations. It also helps reduce the chances of +// accidentally overflowing your stack if large input is passed to +// your function. +// +// Also, FixedArray is useful for writing portable code. Not all +// compilers support arrays of dynamic size. + +// Most users should not specify an inline_elements argument and let +// FixedArray<> automatically determine the number of elements +// to store inline based on sizeof(T). +// +// If inline_elements is specified, the FixedArray<> implementation +// will store arrays of length <= inline_elements inline. +// +// Finally note that unlike vector FixedArray will not zero-initialize +// simple types like int, double, bool, etc. +// +// Non-POD types will be default-initialized just like regular vectors or +// arrays. + +#if defined(_WIN64) + typedef __int64 ssize_t; +#elif defined(_WIN32) + typedef __int32 ssize_t; +#endif + +template +class FixedArray { + public: + // For playing nicely with stl: + typedef T value_type; + typedef T* iterator; + typedef T const* const_iterator; + typedef T& reference; + typedef T const& const_reference; + typedef T* pointer; + typedef std::ptrdiff_t difference_type; + typedef size_t size_type; + + // REQUIRES: n >= 0 + // Creates an array object that can store "n" elements. + // + // FixedArray will not zero-initialiaze POD (simple) types like int, + // double, bool, etc. + // Non-POD types will be default-initialized just like regular vectors or + // arrays. + explicit FixedArray(size_type n); + + // Releases any resources. + ~FixedArray(); + + // Returns the length of the array. + inline size_type size() const { return size_; } + + // Returns the memory size of the array in bytes. + inline size_t memsize() const { return size_ * sizeof(T); } + + // Returns a pointer to the underlying element array. + inline const T* get() const { return &array_[0].element; } + inline T* get() { return &array_[0].element; } + + // REQUIRES: 0 <= i < size() + // Returns a reference to the "i"th element. + inline T& operator[](size_type i) { + DCHECK_LT(i, size_); + return array_[i].element; + } + + // REQUIRES: 0 <= i < size() + // Returns a reference to the "i"th element. + inline const T& operator[](size_type i) const { + DCHECK_LT(i, size_); + return array_[i].element; + } + + inline iterator begin() { return &array_[0].element; } + inline iterator end() { return &array_[size_].element; } + + inline const_iterator begin() const { return &array_[0].element; } + inline const_iterator end() const { return &array_[size_].element; } + + private: + // Container to hold elements of type T. This is necessary to handle + // the case where T is a a (C-style) array. The size of InnerContainer + // and T must be the same, otherwise callers' assumptions about use + // of this code will be broken. + struct InnerContainer { + T element; + }; + + // How many elements should we store inline? + // a. If not specified, use a default of 256 bytes (256 bytes + // seems small enough to not cause stack overflow or unnecessary + // stack pollution, while still allowing stack allocation for + // reasonably long character arrays. + // b. Never use 0 length arrays (not ISO C++) + static const size_type S1 = ((inline_elements < 0) + ? (256/sizeof(T)) : inline_elements); + static const size_type S2 = (S1 <= 0) ? 1 : S1; + static const size_type kInlineElements = S2; + + size_type const size_; + InnerContainer* const array_; + + // Allocate some space, not an array of elements of type T, so that we can + // skip calling the T constructors and destructors for space we never use. + ManualConstructor inline_space_[kInlineElements]; +}; + +// Implementation details follow + +template +inline FixedArray::FixedArray(typename FixedArray::size_type n) + : size_(n), + array_((n <= kInlineElements + ? reinterpret_cast(inline_space_) + : new InnerContainer[n])) { + // Construct only the elements actually used. + if (array_ == reinterpret_cast(inline_space_)) { + for (size_t i = 0; i != size_; ++i) { + inline_space_[i].Init(); + } + } +} + +template +inline FixedArray::~FixedArray() { + if (array_ != reinterpret_cast(inline_space_)) { + delete[] array_; + } else { + for (size_t i = 0; i != size_; ++i) { + inline_space_[i].Destroy(); + } + } +} + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_FIXED_ARRAY_H_ diff --git a/include/ceres/internal/macros.h b/include/ceres/internal/macros.h new file mode 100644 index 0000000..bebb965 --- /dev/null +++ b/include/ceres/internal/macros.h @@ -0,0 +1,170 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// +// Various Google-specific macros. +// +// This code is compiled directly on many platforms, including client +// platforms like Windows, Mac, and embedded systems. Before making +// any changes here, make sure that you're not breaking any platforms. + +#ifndef CERES_PUBLIC_INTERNAL_MACROS_H_ +#define CERES_PUBLIC_INTERNAL_MACROS_H_ + +#include // For size_t. + +// A macro to disallow the copy constructor and operator= functions +// This should be used in the private: declarations for a class +// +// For disallowing only assign or copy, write the code directly, but declare +// the intend in a comment, for example: +// +// void operator=(const TypeName&); // _DISALLOW_ASSIGN + +// Note, that most uses of CERES_DISALLOW_ASSIGN and CERES_DISALLOW_COPY +// are broken semantically, one should either use disallow both or +// neither. Try to avoid these in new code. +#define CERES_DISALLOW_COPY_AND_ASSIGN(TypeName) \ + TypeName(const TypeName&); \ + void operator=(const TypeName&) + +// A macro to disallow all the implicit constructors, namely the +// default constructor, copy constructor and operator= functions. +// +// This should be used in the private: declarations for a class +// that wants to prevent anyone from instantiating it. This is +// especially useful for classes containing only static methods. +#define CERES_DISALLOW_IMPLICIT_CONSTRUCTORS(TypeName) \ + TypeName(); \ + CERES_DISALLOW_COPY_AND_ASSIGN(TypeName) + +// The arraysize(arr) macro returns the # of elements in an array arr. +// The expression is a compile-time constant, and therefore can be +// used in defining new arrays, for example. If you use arraysize on +// a pointer by mistake, you will get a compile-time error. +// +// One caveat is that arraysize() doesn't accept any array of an +// anonymous type or a type defined inside a function. In these rare +// cases, you have to use the unsafe ARRAYSIZE() macro below. This is +// due to a limitation in C++'s template system. The limitation might +// eventually be removed, but it hasn't happened yet. + +// This template function declaration is used in defining arraysize. +// Note that the function doesn't need an implementation, as we only +// use its type. +template +char (&ArraySizeHelper(T (&array)[N]))[N]; + +// That gcc wants both of these prototypes seems mysterious. VC, for +// its part, can't decide which to use (another mystery). Matching of +// template overloads: the final frontier. +#ifndef _WIN32 +template +char (&ArraySizeHelper(const T (&array)[N]))[N]; +#endif + +#define arraysize(array) (sizeof(ArraySizeHelper(array))) + +// ARRAYSIZE performs essentially the same calculation as arraysize, +// but can be used on anonymous types or types defined inside +// functions. It's less safe than arraysize as it accepts some +// (although not all) pointers. Therefore, you should use arraysize +// whenever possible. +// +// The expression ARRAYSIZE(a) is a compile-time constant of type +// size_t. +// +// ARRAYSIZE catches a few type errors. If you see a compiler error +// +// "warning: division by zero in ..." +// +// when using ARRAYSIZE, you are (wrongfully) giving it a pointer. +// You should only use ARRAYSIZE on statically allocated arrays. +// +// The following comments are on the implementation details, and can +// be ignored by the users. +// +// ARRAYSIZE(arr) works by inspecting sizeof(arr) (the # of bytes in +// the array) and sizeof(*(arr)) (the # of bytes in one array +// element). If the former is divisible by the latter, perhaps arr is +// indeed an array, in which case the division result is the # of +// elements in the array. Otherwise, arr cannot possibly be an array, +// and we generate a compiler error to prevent the code from +// compiling. +// +// Since the size of bool is implementation-defined, we need to cast +// !(sizeof(a) & sizeof(*(a))) to size_t in order to ensure the final +// result has type size_t. +// +// This macro is not perfect as it wrongfully accepts certain +// pointers, namely where the pointer size is divisible by the pointee +// size. Since all our code has to go through a 32-bit compiler, +// where a pointer is 4 bytes, this means all pointers to a type whose +// size is 3 or greater than 4 will be (righteously) rejected. +// +// Kudos to Jorg Brown for this simple and elegant implementation. +// +// - wan 2005-11-16 +// +// Starting with Visual C++ 2005, WinNT.h includes ARRAYSIZE. However, +// the definition comes from the over-broad windows.h header that +// introduces a macro, ERROR, that conflicts with the logging framework +// that Ceres uses. Instead, rename ARRAYSIZE to CERES_ARRAYSIZE. +#define CERES_ARRAYSIZE(a) \ + ((sizeof(a) / sizeof(*(a))) / \ + static_cast(!(sizeof(a) % sizeof(*(a))))) + +// Tell the compiler to warn about unused return values for functions +// declared with this macro. The macro should be used on function +// declarations following the argument list: +// +// Sprocket* AllocateSprocket() MUST_USE_RESULT; +// +#if (__GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 4)) \ + && !defined(COMPILER_ICC) +#define CERES_MUST_USE_RESULT __attribute__ ((warn_unused_result)) +#else +#define CERES_MUST_USE_RESULT +#endif + +// Platform independent macros to get aligned memory allocations. +// For example +// +// MyFoo my_foo CERES_ALIGN_ATTRIBUTE(16); +// +// Gives us an instance of MyFoo which is aligned at a 16 byte +// boundary. +#if defined(_MSC_VER) +#define CERES_ALIGN_ATTRIBUTE(n) __declspec(align(n)) +#define CERES_ALIGN_OF(T) __alignof(T) +#elif defined(__GNUC__) +#define CERES_ALIGN_ATTRIBUTE(n) __attribute__((aligned(n))) +#define CERES_ALIGN_OF(T) __alignof(T) +#endif + +#endif // CERES_PUBLIC_INTERNAL_MACROS_H_ diff --git a/include/ceres/internal/manual_constructor.h b/include/ceres/internal/manual_constructor.h new file mode 100644 index 0000000..0d7633c --- /dev/null +++ b/include/ceres/internal/manual_constructor.h @@ -0,0 +1,208 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: kenton@google.com (Kenton Varda) +// +// ManualConstructor statically-allocates space in which to store some +// object, but does not initialize it. You can then call the constructor +// and destructor for the object yourself as you see fit. This is useful +// for memory management optimizations, where you want to initialize and +// destroy an object multiple times but only allocate it once. +// +// (When I say ManualConstructor statically allocates space, I mean that +// the ManualConstructor object itself is forced to be the right size.) + +#ifndef CERES_PUBLIC_INTERNAL_MANUAL_CONSTRUCTOR_H_ +#define CERES_PUBLIC_INTERNAL_MANUAL_CONSTRUCTOR_H_ + +#include + +namespace ceres { +namespace internal { + +// ------- Define CERES_ALIGNED_CHAR_ARRAY -------------------------------- + +#ifndef CERES_ALIGNED_CHAR_ARRAY + +// Because MSVC and older GCCs require that the argument to their alignment +// construct to be a literal constant integer, we use a template instantiated +// at all the possible powers of two. +template struct AlignType { }; +template struct AlignType<0, size> { typedef char result[size]; }; + +#if !defined(CERES_ALIGN_ATTRIBUTE) +#define CERES_ALIGNED_CHAR_ARRAY you_must_define_CERES_ALIGNED_CHAR_ARRAY_for_your_compiler +#else // !defined(CERES_ALIGN_ATTRIBUTE) + +#define CERES_ALIGN_TYPE_TEMPLATE(X) \ + template struct AlignType { \ + typedef CERES_ALIGN_ATTRIBUTE(X) char result[size]; \ + } + +CERES_ALIGN_TYPE_TEMPLATE(1); +CERES_ALIGN_TYPE_TEMPLATE(2); +CERES_ALIGN_TYPE_TEMPLATE(4); +CERES_ALIGN_TYPE_TEMPLATE(8); +CERES_ALIGN_TYPE_TEMPLATE(16); +CERES_ALIGN_TYPE_TEMPLATE(32); +CERES_ALIGN_TYPE_TEMPLATE(64); +CERES_ALIGN_TYPE_TEMPLATE(128); +CERES_ALIGN_TYPE_TEMPLATE(256); +CERES_ALIGN_TYPE_TEMPLATE(512); +CERES_ALIGN_TYPE_TEMPLATE(1024); +CERES_ALIGN_TYPE_TEMPLATE(2048); +CERES_ALIGN_TYPE_TEMPLATE(4096); +CERES_ALIGN_TYPE_TEMPLATE(8192); +// Any larger and MSVC++ will complain. + +#undef CERES_ALIGN_TYPE_TEMPLATE + +#define CERES_ALIGNED_CHAR_ARRAY(T, Size) \ + typename AlignType::result + +#endif // !defined(CERES_ALIGN_ATTRIBUTE) + +#endif // CERES_ALIGNED_CHAR_ARRAY + +template +class ManualConstructor { + public: + // No constructor or destructor because one of the most useful uses of + // this class is as part of a union, and members of a union cannot have + // constructors or destructors. And, anyway, the whole point of this + // class is to bypass these. + + inline Type* get() { + return reinterpret_cast(space_); + } + inline const Type* get() const { + return reinterpret_cast(space_); + } + + inline Type* operator->() { return get(); } + inline const Type* operator->() const { return get(); } + + inline Type& operator*() { return *get(); } + inline const Type& operator*() const { return *get(); } + + // This is needed to get around the strict aliasing warning GCC generates. + inline void* space() { + return reinterpret_cast(space_); + } + + // You can pass up to four constructor arguments as arguments of Init(). + inline void Init() { + new(space()) Type; + } + + template + inline void Init(const T1& p1) { + new(space()) Type(p1); + } + + template + inline void Init(const T1& p1, const T2& p2) { + new(space()) Type(p1, p2); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3) { + new(space()) Type(p1, p2, p3); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4) { + new(space()) Type(p1, p2, p3, p4); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5) { + new(space()) Type(p1, p2, p3, p4, p5); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6) { + new(space()) Type(p1, p2, p3, p4, p5, p6); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6, const T7& p7) { + new(space()) Type(p1, p2, p3, p4, p5, p6, p7); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6, const T7& p7, const T8& p8) { + new(space()) Type(p1, p2, p3, p4, p5, p6, p7, p8); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6, const T7& p7, const T8& p8, + const T9& p9) { + new(space()) Type(p1, p2, p3, p4, p5, p6, p7, p8, p9); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6, const T7& p7, const T8& p8, + const T9& p9, const T10& p10) { + new(space()) Type(p1, p2, p3, p4, p5, p6, p7, p8, p9, p10); + } + + template + inline void Init(const T1& p1, const T2& p2, const T3& p3, const T4& p4, + const T5& p5, const T6& p6, const T7& p7, const T8& p8, + const T9& p9, const T10& p10, const T11& p11) { + new(space()) Type(p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p11); + } + + inline void Destroy() { + get()->~Type(); + } + + private: + CERES_ALIGNED_CHAR_ARRAY(Type, 1) space_; +}; + +#undef CERES_ALIGNED_CHAR_ARRAY + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_MANUAL_CONSTRUCTOR_H_ diff --git a/include/ceres/internal/numeric_diff.h b/include/ceres/internal/numeric_diff.h new file mode 100644 index 0000000..11e8275 --- /dev/null +++ b/include/ceres/internal/numeric_diff.h @@ -0,0 +1,446 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// mierle@gmail.com (Keir Mierle) +// tbennun@gmail.com (Tal Ben-Nun) +// +// Finite differencing routines used by NumericDiffCostFunction. + +#ifndef CERES_PUBLIC_INTERNAL_NUMERIC_DIFF_H_ +#define CERES_PUBLIC_INTERNAL_NUMERIC_DIFF_H_ + +#include + +#include "Eigen/Dense" +#include "Eigen/StdVector" +#include "ceres/cost_function.h" +#include "ceres/internal/fixed_array.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/internal/variadic_evaluate.h" +#include "ceres/numeric_diff_options.h" +#include "ceres/types.h" +#include "glog/logging.h" + + +namespace ceres { +namespace internal { + +// Helper templates that allow evaluation of a variadic functor or a +// CostFunction object. +template +bool EvaluateImpl(const CostFunctor* functor, + double const* const* parameters, + double* residuals, + const void* /* NOT USED */) { + return VariadicEvaluate::Call( + *functor, + parameters, + residuals); +} + +template +bool EvaluateImpl(const CostFunctor* functor, + double const* const* parameters, + double* residuals, + const CostFunction* /* NOT USED */) { + return functor->Evaluate(parameters, residuals, NULL); +} + +// This is split from the main class because C++ doesn't allow partial template +// specializations for member functions. The alternative is to repeat the main +// class for differing numbers of parameters, which is also unfortunate. +template +struct NumericDiff { + // Mutates parameters but must restore them before return. + static bool EvaluateJacobianForParameterBlock( + const CostFunctor* functor, + const double* residuals_at_eval_point, + const NumericDiffOptions& options, + int num_residuals, + int parameter_block_index, + int parameter_block_size, + double **parameters, + double *jacobian) { + using Eigen::Map; + using Eigen::Matrix; + using Eigen::RowMajor; + using Eigen::ColMajor; + + const int num_residuals_internal = + (kNumResiduals != ceres::DYNAMIC ? kNumResiduals : num_residuals); + const int parameter_block_index_internal = + (kParameterBlock != ceres::DYNAMIC ? kParameterBlock : + parameter_block_index); + const int parameter_block_size_internal = + (kParameterBlockSize != ceres::DYNAMIC ? kParameterBlockSize : + parameter_block_size); + + typedef Matrix ResidualVector; + typedef Matrix ParameterVector; + + // The convoluted reasoning for choosing the Row/Column major + // ordering of the matrix is an artifact of the restrictions in + // Eigen that prevent it from creating RowMajor matrices with a + // single column. In these cases, we ask for a ColMajor matrix. + typedef Matrix + JacobianMatrix; + + Map parameter_jacobian(jacobian, + num_residuals_internal, + parameter_block_size_internal); + + Map x_plus_delta( + parameters[parameter_block_index_internal], + parameter_block_size_internal); + ParameterVector x(x_plus_delta); + ParameterVector step_size = x.array().abs() * + ((kMethod == RIDDERS) ? options.ridders_relative_initial_step_size : + options.relative_step_size); + + // It is not a good idea to make the step size arbitrarily + // small. This will lead to problems with round off and numerical + // instability when dividing by the step size. The general + // recommendation is to not go down below sqrt(epsilon). + double min_step_size = std::sqrt(std::numeric_limits::epsilon()); + + // For Ridders' method, the initial step size is required to be large, + // thus ridders_relative_initial_step_size is used. + if (kMethod == RIDDERS) { + min_step_size = std::max(min_step_size, + options.ridders_relative_initial_step_size); + } + + // For each parameter in the parameter block, use finite differences to + // compute the derivative for that parameter. + FixedArray temp_residual_array(num_residuals_internal); + FixedArray residual_array(num_residuals_internal); + Map residuals(residual_array.get(), + num_residuals_internal); + + for (int j = 0; j < parameter_block_size_internal; ++j) { + const double delta = std::max(min_step_size, step_size(j)); + + if (kMethod == RIDDERS) { + if (!EvaluateRiddersJacobianColumn(functor, j, delta, + options, + num_residuals_internal, + parameter_block_size_internal, + x.data(), + residuals_at_eval_point, + parameters, + x_plus_delta.data(), + temp_residual_array.get(), + residual_array.get())) { + return false; + } + } else { + if (!EvaluateJacobianColumn(functor, j, delta, + num_residuals_internal, + parameter_block_size_internal, + x.data(), + residuals_at_eval_point, + parameters, + x_plus_delta.data(), + temp_residual_array.get(), + residual_array.get())) { + return false; + } + } + + parameter_jacobian.col(j).matrix() = residuals; + } + return true; + } + + static bool EvaluateJacobianColumn(const CostFunctor* functor, + int parameter_index, + double delta, + int num_residuals, + int parameter_block_size, + const double* x_ptr, + const double* residuals_at_eval_point, + double** parameters, + double* x_plus_delta_ptr, + double* temp_residuals_ptr, + double* residuals_ptr) { + using Eigen::Map; + using Eigen::Matrix; + + typedef Matrix ResidualVector; + typedef Matrix ParameterVector; + + Map x(x_ptr, parameter_block_size); + Map x_plus_delta(x_plus_delta_ptr, + parameter_block_size); + + Map residuals(residuals_ptr, num_residuals); + Map temp_residuals(temp_residuals_ptr, num_residuals); + + // Mutate 1 element at a time and then restore. + x_plus_delta(parameter_index) = x(parameter_index) + delta; + + if (!EvaluateImpl( + functor, parameters, residuals.data(), functor)) { + return false; + } + + // Compute this column of the jacobian in 3 steps: + // 1. Store residuals for the forward part. + // 2. Subtract residuals for the backward (or 0) part. + // 3. Divide out the run. + double one_over_delta = 1.0 / delta; + if (kMethod == CENTRAL || kMethod == RIDDERS) { + // Compute the function on the other side of x(parameter_index). + x_plus_delta(parameter_index) = x(parameter_index) - delta; + + if (!EvaluateImpl( + functor, parameters, temp_residuals.data(), functor)) { + return false; + } + + residuals -= temp_residuals; + one_over_delta /= 2; + } else { + // Forward difference only; reuse existing residuals evaluation. + residuals -= + Map(residuals_at_eval_point, + num_residuals); + } + + // Restore x_plus_delta. + x_plus_delta(parameter_index) = x(parameter_index); + + // Divide out the run to get slope. + residuals *= one_over_delta; + + return true; + } + + // This numeric difference implementation uses adaptive differentiation + // on the parameters to obtain the Jacobian matrix. The adaptive algorithm + // is based on Ridders' method for adaptive differentiation, which creates + // a Romberg tableau from varying step sizes and extrapolates the + // intermediate results to obtain the current computational error. + // + // References: + // C.J.F. Ridders, Accurate computation of F'(x) and F'(x) F"(x), Advances + // in Engineering Software (1978), Volume 4, Issue 2, April 1982, + // Pages 75-76, ISSN 0141-1195, + // http://dx.doi.org/10.1016/S0141-1195(82)80057-0. + static bool EvaluateRiddersJacobianColumn( + const CostFunctor* functor, + int parameter_index, + double delta, + const NumericDiffOptions& options, + int num_residuals, + int parameter_block_size, + const double* x_ptr, + const double* residuals_at_eval_point, + double** parameters, + double* x_plus_delta_ptr, + double* temp_residuals_ptr, + double* residuals_ptr) { + using Eigen::Map; + using Eigen::Matrix; + using Eigen::aligned_allocator; + + typedef Matrix ResidualVector; + typedef Matrix ResidualCandidateMatrix; + typedef Matrix ParameterVector; + + Map x(x_ptr, parameter_block_size); + Map x_plus_delta(x_plus_delta_ptr, + parameter_block_size); + + Map residuals(residuals_ptr, num_residuals); + Map temp_residuals(temp_residuals_ptr, num_residuals); + + // In order for the algorithm to converge, the step size should be + // initialized to a value that is large enough to produce a significant + // change in the function. + // As the derivative is estimated, the step size decreases. + // By default, the step sizes are chosen so that the middle column + // of the Romberg tableau uses the input delta. + double current_step_size = delta * + pow(options.ridders_step_shrink_factor, + options.max_num_ridders_extrapolations / 2); + + // Double-buffering temporary differential candidate vectors + // from previous step size. + ResidualCandidateMatrix stepsize_candidates_a( + num_residuals, + options.max_num_ridders_extrapolations); + ResidualCandidateMatrix stepsize_candidates_b( + num_residuals, + options.max_num_ridders_extrapolations); + ResidualCandidateMatrix* current_candidates = &stepsize_candidates_a; + ResidualCandidateMatrix* previous_candidates = &stepsize_candidates_b; + + // Represents the computational error of the derivative. This variable is + // initially set to a large value, and is set to the difference between + // current and previous finite difference extrapolations. + // norm_error is supposed to decrease as the finite difference tableau + // generation progresses, serving both as an estimate for differentiation + // error and as a measure of differentiation numerical stability. + double norm_error = std::numeric_limits::max(); + + // Loop over decreasing step sizes until: + // 1. Error is smaller than a given value (ridders_epsilon), + // 2. Maximal order of extrapolation reached, or + // 3. Extrapolation becomes numerically unstable. + for (int i = 0; i < options.max_num_ridders_extrapolations; ++i) { + // Compute the numerical derivative at this step size. + if (!EvaluateJacobianColumn(functor, parameter_index, current_step_size, + num_residuals, + parameter_block_size, + x.data(), + residuals_at_eval_point, + parameters, + x_plus_delta.data(), + temp_residuals.data(), + current_candidates->col(0).data())) { + // Something went wrong; bail. + return false; + } + + // Store initial results. + if (i == 0) { + residuals = current_candidates->col(0); + } + + // Shrink differentiation step size. + current_step_size /= options.ridders_step_shrink_factor; + + // Extrapolation factor for Richardson acceleration method (see below). + double richardson_factor = options.ridders_step_shrink_factor * + options.ridders_step_shrink_factor; + for (int k = 1; k <= i; ++k) { + // Extrapolate the various orders of finite differences using + // the Richardson acceleration method. + current_candidates->col(k) = + (richardson_factor * current_candidates->col(k - 1) - + previous_candidates->col(k - 1)) / (richardson_factor - 1.0); + + richardson_factor *= options.ridders_step_shrink_factor * + options.ridders_step_shrink_factor; + + // Compute the difference between the previous value and the current. + double candidate_error = std::max( + (current_candidates->col(k) - + current_candidates->col(k - 1)).norm(), + (current_candidates->col(k) - + previous_candidates->col(k - 1)).norm()); + + // If the error has decreased, update results. + if (candidate_error <= norm_error) { + norm_error = candidate_error; + residuals = current_candidates->col(k); + + // If the error is small enough, stop. + if (norm_error < options.ridders_epsilon) { + break; + } + } + } + + // After breaking out of the inner loop, declare convergence. + if (norm_error < options.ridders_epsilon) { + break; + } + + // Check to see if the current gradient estimate is numerically unstable. + // If so, bail out and return the last stable result. + if (i > 0) { + double tableau_error = (current_candidates->col(i) - + previous_candidates->col(i - 1)).norm(); + + // Compare current error to the chosen candidate's error. + if (tableau_error >= 2 * norm_error) { + break; + } + } + + std::swap(current_candidates, previous_candidates); + } + return true; + } +}; + +template +struct NumericDiff { + // Mutates parameters but must restore them before return. + static bool EvaluateJacobianForParameterBlock( + const CostFunctor* functor, + const double* residuals_at_eval_point, + const NumericDiffOptions& options, + const int num_residuals, + const int parameter_block_index, + const int parameter_block_size, + double **parameters, + double *jacobian) { + // Silence unused parameter compiler warnings. + (void)functor; + (void)residuals_at_eval_point; + (void)options; + (void)num_residuals; + (void)parameter_block_index; + (void)parameter_block_size; + (void)parameters; + (void)jacobian; + LOG(FATAL) << "Control should never reach here."; + return true; + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_NUMERIC_DIFF_H_ diff --git a/include/ceres/internal/port.h b/include/ceres/internal/port.h new file mode 100644 index 0000000..652f6fb --- /dev/null +++ b/include/ceres/internal/port.h @@ -0,0 +1,98 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#ifndef CERES_PUBLIC_INTERNAL_PORT_H_ +#define CERES_PUBLIC_INTERNAL_PORT_H_ + +// This file needs to compile as c code. +#ifdef __cplusplus +#include +#include "ceres/internal/config.h" +#if defined(CERES_TR1_MEMORY_HEADER) +#include +#else +#include +#endif + +namespace ceres { + +#if defined(CERES_TR1_SHARED_PTR) +using std::tr1::shared_ptr; +#else +using std::shared_ptr; +#endif + +// We allocate some Eigen objects on the stack and other places they +// might not be aligned to X(=16 [SSE], 32 [AVX] etc)-byte boundaries. If we +// have C++11, we can specify their alignment (which is desirable, as it means +// we can safely enable vectorisation on matrices). However, the standard gives +// wide lattitude as to what alignments are legal. It must be the case that +// alignments up to alignof(std::max_align_t) are valid, but this might be < 16 +// on some platforms, in which case even if using C++11, on these platforms +// we should not attempt to align to X-byte boundaries. If using < C++11, +// we cannot specify the alignment. +#ifdef CERES_USE_CXX11 +namespace port_constants { +static constexpr size_t kMaxAlignBytes = + // Work around a GCC 4.8 bug + // (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56019) where + // std::max_align_t is misplaced. +#if defined (__GNUC__) && __GNUC__ == 4 && __GNUC_MINOR__ == 8 + alignof(::max_align_t); +#else + alignof(std::max_align_t); +#endif +} // namespace port_constants +#endif + +} // namespace ceres + +#endif // __cplusplus + +// A macro to signal which functions and classes are exported when +// building a DLL with MSVC. +// +// Note that the ordering here is important, CERES_BUILDING_SHARED_LIBRARY +// is only defined locally when Ceres is compiled, it is never exported to +// users. However, in order that we do not have to configure config.h +// separately for building vs installing, if we are using MSVC and building +// a shared library, then both CERES_BUILDING_SHARED_LIBRARY and +// CERES_USING_SHARED_LIBRARY will be defined when Ceres is compiled. +// Hence it is important that the check for CERES_BUILDING_SHARED_LIBRARY +// happens first. +#if defined(_MSC_VER) && defined(CERES_BUILDING_SHARED_LIBRARY) +# define CERES_EXPORT __declspec(dllexport) +#elif defined(_MSC_VER) && defined(CERES_USING_SHARED_LIBRARY) +# define CERES_EXPORT __declspec(dllimport) +#else +# define CERES_EXPORT +#endif + +#endif // CERES_PUBLIC_INTERNAL_PORT_H_ diff --git a/include/ceres/internal/reenable_warnings.h b/include/ceres/internal/reenable_warnings.h new file mode 100644 index 0000000..7e41025 --- /dev/null +++ b/include/ceres/internal/reenable_warnings.h @@ -0,0 +1,38 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// + +// This is not your usual header guard. See disable_warnings.h +#ifdef CERES_WARNINGS_DISABLED +#undef CERES_WARNINGS_DISABLED + +#ifdef _MSC_VER +#pragma warning( pop ) +#endif + +#endif // CERES_WARNINGS_DISABLED diff --git a/include/ceres/internal/scoped_ptr.h b/include/ceres/internal/scoped_ptr.h new file mode 100644 index 0000000..fa0ac25 --- /dev/null +++ b/include/ceres/internal/scoped_ptr.h @@ -0,0 +1,310 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: jorg@google.com (Jorg Brown) +// +// This is an implementation designed to match the anticipated future TR2 +// implementation of the scoped_ptr class, and its closely-related brethren, +// scoped_array, scoped_ptr_malloc, and make_scoped_ptr. + +#ifndef CERES_PUBLIC_INTERNAL_SCOPED_PTR_H_ +#define CERES_PUBLIC_INTERNAL_SCOPED_PTR_H_ + +#include +#include +#include +#include + +namespace ceres { +namespace internal { + +template class scoped_ptr; +template class scoped_ptr_malloc; +template class scoped_array; + +template +scoped_ptr make_scoped_ptr(C *); + +// A scoped_ptr is like a T*, except that the destructor of +// scoped_ptr automatically deletes the pointer it holds (if +// any). That is, scoped_ptr owns the T object that it points +// to. Like a T*, a scoped_ptr may hold either NULL or a pointer to +// a T object. Also like T*, scoped_ptr is thread-compatible, and +// once you dereference it, you get the threadsafety guarantees of T. +// +// The size of a scoped_ptr is small: sizeof(scoped_ptr) == sizeof(C*) +template +class scoped_ptr { + public: + // The element type + typedef C element_type; + + // Constructor. Defaults to intializing with NULL. + // There is no way to create an uninitialized scoped_ptr. + // The input parameter must be allocated with new. + explicit scoped_ptr(C* p = NULL) : ptr_(p) { } + + // Destructor. If there is a C object, delete it. + // We don't need to test ptr_ == NULL because C++ does that for us. + ~scoped_ptr() { + enum { type_must_be_complete = sizeof(C) }; + delete ptr_; + } + + // Reset. Deletes the current owned object, if any. + // Then takes ownership of a new object, if given. + // this->reset(this->get()) works. + void reset(C* p = NULL) { + if (p != ptr_) { + enum { type_must_be_complete = sizeof(C) }; + delete ptr_; + ptr_ = p; + } + } + + // Accessors to get the owned object. + // operator* and operator-> will assert() if there is no current object. + C& operator*() const { + assert(ptr_ != NULL); + return *ptr_; + } + C* operator->() const { + assert(ptr_ != NULL); + return ptr_; + } + C* get() const { return ptr_; } + + // Comparison operators. + // These return whether a scoped_ptr and a raw pointer refer to + // the same object, not just to two different but equal objects. + bool operator==(const C* p) const { return ptr_ == p; } + bool operator!=(const C* p) const { return ptr_ != p; } + + // Swap two scoped pointers. + void swap(scoped_ptr& p2) { + C* tmp = ptr_; + ptr_ = p2.ptr_; + p2.ptr_ = tmp; + } + + // Release a pointer. + // The return value is the current pointer held by this object. + // If this object holds a NULL pointer, the return value is NULL. + // After this operation, this object will hold a NULL pointer, + // and will not own the object any more. + C* release() { + C* retVal = ptr_; + ptr_ = NULL; + return retVal; + } + + private: + C* ptr_; + + // google3 friend class that can access copy ctor (although if it actually + // calls a copy ctor, there will be a problem) see below + friend scoped_ptr make_scoped_ptr(C *p); + + // Forbid comparison of scoped_ptr types. If C2 != C, it totally doesn't + // make sense, and if C2 == C, it still doesn't make sense because you should + // never have the same object owned by two different scoped_ptrs. + template bool operator==(scoped_ptr const& p2) const; + template bool operator!=(scoped_ptr const& p2) const; + + // Disallow evil constructors + scoped_ptr(const scoped_ptr&); + void operator=(const scoped_ptr&); +}; + +// Free functions +template +inline void swap(scoped_ptr& p1, scoped_ptr& p2) { + p1.swap(p2); +} + +template +inline bool operator==(const C* p1, const scoped_ptr& p2) { + return p1 == p2.get(); +} + +template +inline bool operator==(const C* p1, const scoped_ptr& p2) { + return p1 == p2.get(); +} + +template +inline bool operator!=(const C* p1, const scoped_ptr& p2) { + return p1 != p2.get(); +} + +template +inline bool operator!=(const C* p1, const scoped_ptr& p2) { + return p1 != p2.get(); +} + +template +scoped_ptr make_scoped_ptr(C *p) { + // This does nothing but to return a scoped_ptr of the type that the passed + // pointer is of. (This eliminates the need to specify the name of T when + // making a scoped_ptr that is used anonymously/temporarily.) From an + // access control point of view, we construct an unnamed scoped_ptr here + // which we return and thus copy-construct. Hence, we need to have access + // to scoped_ptr::scoped_ptr(scoped_ptr const &). However, it is guaranteed + // that we never actually call the copy constructor, which is a good thing + // as we would call the temporary's object destructor (and thus delete p) + // if we actually did copy some object, here. + return scoped_ptr(p); +} + +// scoped_array is like scoped_ptr, except that the caller must allocate +// with new [] and the destructor deletes objects with delete []. +// +// As with scoped_ptr, a scoped_array either points to an object +// or is NULL. A scoped_array owns the object that it points to. +// scoped_array is thread-compatible, and once you index into it, +// the returned objects have only the threadsafety guarantees of T. +// +// Size: sizeof(scoped_array) == sizeof(C*) +template +class scoped_array { + public: + // The element type + typedef C element_type; + + // Constructor. Defaults to intializing with NULL. + // There is no way to create an uninitialized scoped_array. + // The input parameter must be allocated with new []. + explicit scoped_array(C* p = NULL) : array_(p) { } + + // Destructor. If there is a C object, delete it. + // We don't need to test ptr_ == NULL because C++ does that for us. + ~scoped_array() { + enum { type_must_be_complete = sizeof(C) }; + delete[] array_; + } + + // Reset. Deletes the current owned object, if any. + // Then takes ownership of a new object, if given. + // this->reset(this->get()) works. + void reset(C* p = NULL) { + if (p != array_) { + enum { type_must_be_complete = sizeof(C) }; + delete[] array_; + array_ = p; + } + } + + // Get one element of the current object. + // Will assert() if there is no current object, or index i is negative. + C& operator[](std::ptrdiff_t i) const { + assert(i >= 0); + assert(array_ != NULL); + return array_[i]; + } + + // Get a pointer to the zeroth element of the current object. + // If there is no current object, return NULL. + C* get() const { + return array_; + } + + // Comparison operators. + // These return whether a scoped_array and a raw pointer refer to + // the same array, not just to two different but equal arrays. + bool operator==(const C* p) const { return array_ == p; } + bool operator!=(const C* p) const { return array_ != p; } + + // Swap two scoped arrays. + void swap(scoped_array& p2) { + C* tmp = array_; + array_ = p2.array_; + p2.array_ = tmp; + } + + // Release an array. + // The return value is the current pointer held by this object. + // If this object holds a NULL pointer, the return value is NULL. + // After this operation, this object will hold a NULL pointer, + // and will not own the object any more. + C* release() { + C* retVal = array_; + array_ = NULL; + return retVal; + } + + private: + C* array_; + + // Forbid comparison of different scoped_array types. + template bool operator==(scoped_array const& p2) const; + template bool operator!=(scoped_array const& p2) const; + + // Disallow evil constructors + scoped_array(const scoped_array&); + void operator=(const scoped_array&); +}; + +// Free functions +template +inline void swap(scoped_array& p1, scoped_array& p2) { + p1.swap(p2); +} + +template +inline bool operator==(const C* p1, const scoped_array& p2) { + return p1 == p2.get(); +} + +template +inline bool operator==(const C* p1, const scoped_array& p2) { + return p1 == p2.get(); +} + +template +inline bool operator!=(const C* p1, const scoped_array& p2) { + return p1 != p2.get(); +} + +template +inline bool operator!=(const C* p1, const scoped_array& p2) { + return p1 != p2.get(); +} + +// This class wraps the c library function free() in a class that can be +// passed as a template argument to scoped_ptr_malloc below. +class ScopedPtrMallocFree { + public: + inline void operator()(void* x) const { + free(x); + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_SCOPED_PTR_H_ diff --git a/include/ceres/internal/variadic_evaluate.h b/include/ceres/internal/variadic_evaluate.h new file mode 100644 index 0000000..b3515b9 --- /dev/null +++ b/include/ceres/internal/variadic_evaluate.h @@ -0,0 +1,194 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// mierle@gmail.com (Keir Mierle) + +#ifndef CERES_PUBLIC_INTERNAL_VARIADIC_EVALUATE_H_ +#define CERES_PUBLIC_INTERNAL_VARIADIC_EVALUATE_H_ + +#include + +#include "ceres/jet.h" +#include "ceres/types.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/fixed_array.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +// This block of quasi-repeated code calls the user-supplied functor, which may +// take a variable number of arguments. This is accomplished by specializing the +// struct based on the size of the trailing parameters; parameters with 0 size +// are assumed missing. +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + input[5], + input[6], + input[7], + input[8], + input[9], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + input[5], + input[6], + input[7], + input[8], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + input[5], + input[6], + input[7], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + input[5], + input[6], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + input[5], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + input[4], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + input[3], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + input[2], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + input[1], + output); + } +}; + +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input[0], + output); + } +}; + +// Template instantiation for dynamically-sized functors. +template +struct VariadicEvaluate { + static bool Call(const Functor& functor, T const *const *input, T* output) { + return functor(input, output); + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_PUBLIC_INTERNAL_VARIADIC_EVALUATE_H_ diff --git a/include/ceres/iteration_callback.h b/include/ceres/iteration_callback.h new file mode 100644 index 0000000..db5d0ef --- /dev/null +++ b/include/ceres/iteration_callback.h @@ -0,0 +1,225 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// When an iteration callback is specified, Ceres calls the callback +// after each minimizer step (if the minimizer has not converged) and +// passes it an IterationSummary object, defined below. + +#ifndef CERES_PUBLIC_ITERATION_CALLBACK_H_ +#define CERES_PUBLIC_ITERATION_CALLBACK_H_ + +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// This struct describes the state of the optimizer after each +// iteration of the minimization. +struct CERES_EXPORT IterationSummary { + IterationSummary() + : iteration(0), + step_is_valid(false), + step_is_nonmonotonic(false), + step_is_successful(false), + cost(0.0), + cost_change(0.0), + gradient_max_norm(0.0), + gradient_norm(0.0), + step_norm(0.0), + eta(0.0), + step_size(0.0), + line_search_function_evaluations(0), + line_search_gradient_evaluations(0), + line_search_iterations(0), + linear_solver_iterations(0), + iteration_time_in_seconds(0.0), + step_solver_time_in_seconds(0.0), + cumulative_time_in_seconds(0.0) {} + + // Current iteration number. + int32 iteration; + + // Step was numerically valid, i.e., all values are finite and the + // step reduces the value of the linearized model. + // + // Note: step_is_valid is always true when iteration = 0. + bool step_is_valid; + + // Step did not reduce the value of the objective function + // sufficiently, but it was accepted because of the relaxed + // acceptance criterion used by the non-monotonic trust region + // algorithm. + // + // Note: step_is_nonmonotonic is always false when iteration = 0; + bool step_is_nonmonotonic; + + // Whether or not the minimizer accepted this step or not. If the + // ordinary trust region algorithm is used, this means that the + // relative reduction in the objective function value was greater + // than Solver::Options::min_relative_decrease. However, if the + // non-monotonic trust region algorithm is used + // (Solver::Options:use_nonmonotonic_steps = true), then even if the + // relative decrease is not sufficient, the algorithm may accept the + // step and the step is declared successful. + // + // Note: step_is_successful is always true when iteration = 0. + bool step_is_successful; + + // Value of the objective function. + double cost; + + // Change in the value of the objective function in this + // iteration. This can be positive or negative. + double cost_change; + + // Infinity norm of the gradient vector. + double gradient_max_norm; + + // 2-norm of the gradient vector. + double gradient_norm; + + // 2-norm of the size of the step computed by the optimization + // algorithm. + double step_norm; + + // For trust region algorithms, the ratio of the actual change in + // cost and the change in the cost of the linearized approximation. + double relative_decrease; + + // Size of the trust region at the end of the current iteration. For + // the Levenberg-Marquardt algorithm, the regularization parameter + // mu = 1.0 / trust_region_radius. + double trust_region_radius; + + // For the inexact step Levenberg-Marquardt algorithm, this is the + // relative accuracy with which the Newton(LM) step is solved. This + // number affects only the iterative solvers capable of solving + // linear systems inexactly. Factorization-based exact solvers + // ignore it. + double eta; + + // Step sized computed by the line search algorithm. + double step_size; + + // Number of function value evaluations used by the line search algorithm. + int line_search_function_evaluations; + + // Number of function gradient evaluations used by the line search algorithm. + int line_search_gradient_evaluations; + + // Number of iterations taken by the line search algorithm. + int line_search_iterations; + + // Number of iterations taken by the linear solver to solve for the + // Newton step. + int linear_solver_iterations; + + // All times reported below are wall times. + + // Time (in seconds) spent inside the minimizer loop in the current + // iteration. + double iteration_time_in_seconds; + + // Time (in seconds) spent inside the trust region step solver. + double step_solver_time_in_seconds; + + // Time (in seconds) since the user called Solve(). + double cumulative_time_in_seconds; +}; + +// Interface for specifying callbacks that are executed at the end of +// each iteration of the Minimizer. The solver uses the return value +// of operator() to decide whether to continue solving or to +// terminate. The user can return three values. +// +// SOLVER_ABORT indicates that the callback detected an abnormal +// situation. The solver returns without updating the parameter blocks +// (unless Solver::Options::update_state_every_iteration is set +// true). Solver returns with Solver::Summary::termination_type set to +// USER_ABORT. +// +// SOLVER_TERMINATE_SUCCESSFULLY indicates that there is no need to +// optimize anymore (some user specified termination criterion has +// been met). Solver returns with Solver::Summary::termination_type +// set to USER_SUCCESS. +// +// SOLVER_CONTINUE indicates that the solver should continue +// optimizing. +// +// For example, the following Callback is used internally by Ceres to +// log the progress of the optimization. +// +// Callback for logging the state of the minimizer to STDERR or STDOUT +// depending on the user's preferences and logging level. +// +// class LoggingCallback : public IterationCallback { +// public: +// explicit LoggingCallback(bool log_to_stdout) +// : log_to_stdout_(log_to_stdout) {} +// +// ~LoggingCallback() {} +// +// CallbackReturnType operator()(const IterationSummary& summary) { +// const char* kReportRowFormat = +// "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e " +// "rho:% 3.2e mu:% 3.2e eta:% 3.2e li:% 3d"; +// string output = StringPrintf(kReportRowFormat, +// summary.iteration, +// summary.cost, +// summary.cost_change, +// summary.gradient_max_norm, +// summary.step_norm, +// summary.relative_decrease, +// summary.trust_region_radius, +// summary.eta, +// summary.linear_solver_iterations); +// if (log_to_stdout_) { +// cout << output << endl; +// } else { +// VLOG(1) << output; +// } +// return SOLVER_CONTINUE; +// } +// +// private: +// const bool log_to_stdout_; +// }; +// +class CERES_EXPORT IterationCallback { + public: + virtual ~IterationCallback() {} + virtual CallbackReturnType operator()(const IterationSummary& summary) = 0; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_ITERATION_CALLBACK_H_ diff --git a/include/ceres/jet.h b/include/ceres/jet.h new file mode 100644 index 0000000..934bc18 --- /dev/null +++ b/include/ceres/jet.h @@ -0,0 +1,923 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A simple implementation of N-dimensional dual numbers, for automatically +// computing exact derivatives of functions. +// +// While a complete treatment of the mechanics of automatic differentation is +// beyond the scope of this header (see +// http://en.wikipedia.org/wiki/Automatic_differentiation for details), the +// basic idea is to extend normal arithmetic with an extra element, "e," often +// denoted with the greek symbol epsilon, such that e != 0 but e^2 = 0. Dual +// numbers are extensions of the real numbers analogous to complex numbers: +// whereas complex numbers augment the reals by introducing an imaginary unit i +// such that i^2 = -1, dual numbers introduce an "infinitesimal" unit e such +// that e^2 = 0. Dual numbers have two components: the "real" component and the +// "infinitesimal" component, generally written as x + y*e. Surprisingly, this +// leads to a convenient method for computing exact derivatives without needing +// to manipulate complicated symbolic expressions. +// +// For example, consider the function +// +// f(x) = x^2 , +// +// evaluated at 10. Using normal arithmetic, f(10) = 100, and df/dx(10) = 20. +// Next, augument 10 with an infinitesimal to get: +// +// f(10 + e) = (10 + e)^2 +// = 100 + 2 * 10 * e + e^2 +// = 100 + 20 * e -+- +// -- | +// | +--- This is zero, since e^2 = 0 +// | +// +----------------- This is df/dx! +// +// Note that the derivative of f with respect to x is simply the infinitesimal +// component of the value of f(x + e). So, in order to take the derivative of +// any function, it is only necessary to replace the numeric "object" used in +// the function with one extended with infinitesimals. The class Jet, defined in +// this header, is one such example of this, where substitution is done with +// templates. +// +// To handle derivatives of functions taking multiple arguments, different +// infinitesimals are used, one for each variable to take the derivative of. For +// example, consider a scalar function of two scalar parameters x and y: +// +// f(x, y) = x^2 + x * y +// +// Following the technique above, to compute the derivatives df/dx and df/dy for +// f(1, 3) involves doing two evaluations of f, the first time replacing x with +// x + e, the second time replacing y with y + e. +// +// For df/dx: +// +// f(1 + e, y) = (1 + e)^2 + (1 + e) * 3 +// = 1 + 2 * e + 3 + 3 * e +// = 4 + 5 * e +// +// --> df/dx = 5 +// +// For df/dy: +// +// f(1, 3 + e) = 1^2 + 1 * (3 + e) +// = 1 + 3 + e +// = 4 + e +// +// --> df/dy = 1 +// +// To take the gradient of f with the implementation of dual numbers ("jets") in +// this file, it is necessary to create a single jet type which has components +// for the derivative in x and y, and passing them to a templated version of f: +// +// template +// T f(const T &x, const T &y) { +// return x * x + x * y; +// } +// +// // The "2" means there should be 2 dual number components. +// Jet x(0); // Pick the 0th dual number for x. +// Jet y(1); // Pick the 1st dual number for y. +// Jet z = f(x, y); +// +// LOG(INFO) << "df/dx = " << z.v[0] +// << "df/dy = " << z.v[1]; +// +// Most users should not use Jet objects directly; a wrapper around Jet objects, +// which makes computing the derivative, gradient, or jacobian of templated +// functors simple, is in autodiff.h. Even autodiff.h should not be used +// directly; instead autodiff_cost_function.h is typically the file of interest. +// +// For the more mathematically inclined, this file implements first-order +// "jets". A 1st order jet is an element of the ring +// +// T[N] = T[t_1, ..., t_N] / (t_1, ..., t_N)^2 +// +// which essentially means that each jet consists of a "scalar" value 'a' from T +// and a 1st order perturbation vector 'v' of length N: +// +// x = a + \sum_i v[i] t_i +// +// A shorthand is to write an element as x = a + u, where u is the pertubation. +// Then, the main point about the arithmetic of jets is that the product of +// perturbations is zero: +// +// (a + u) * (b + v) = ab + av + bu + uv +// = ab + (av + bu) + 0 +// +// which is what operator* implements below. Addition is simpler: +// +// (a + u) + (b + v) = (a + b) + (u + v). +// +// The only remaining question is how to evaluate the function of a jet, for +// which we use the chain rule: +// +// f(a + u) = f(a) + f'(a) u +// +// where f'(a) is the (scalar) derivative of f at a. +// +// By pushing these things through sufficiently and suitably templated +// functions, we can do automatic differentiation. Just be sure to turn on +// function inlining and common-subexpression elimination, or it will be very +// slow! +// +// WARNING: Most Ceres users should not directly include this file or know the +// details of how jets work. Instead the suggested method for automatic +// derivatives is to use autodiff_cost_function.h, which is a wrapper around +// both jets.h and autodiff.h to make taking derivatives of cost functions for +// use in Ceres easier. + +#ifndef CERES_PUBLIC_JET_H_ +#define CERES_PUBLIC_JET_H_ + +#include +#include +#include // NOLINT +#include +#include + +#include "Eigen/Core" +#include "ceres/fpclassify.h" +#include "ceres/internal/port.h" + +namespace ceres { + +template +struct Jet { + enum { DIMENSION = N }; + + // Default-construct "a" because otherwise this can lead to false errors about + // uninitialized uses when other classes relying on default constructed T + // (where T is a Jet). This usually only happens in opt mode. Note that + // the C++ standard mandates that e.g. default constructed doubles are + // initialized to 0.0; see sections 8.5 of the C++03 standard. + Jet() : a() { + v.setZero(); + } + + // Constructor from scalar: a + 0. + explicit Jet(const T& value) { + a = value; + v.setZero(); + } + + // Constructor from scalar plus variable: a + t_i. + Jet(const T& value, int k) { + a = value; + v.setZero(); + v[k] = T(1.0); + } + + // Constructor from scalar and vector part + // The use of Eigen::DenseBase allows Eigen expressions + // to be passed in without being fully evaluated until + // they are assigned to v + template + EIGEN_STRONG_INLINE Jet(const T& a, const Eigen::DenseBase &v) + : a(a), v(v) { + } + + // Compound operators + Jet& operator+=(const Jet &y) { + *this = *this + y; + return *this; + } + + Jet& operator-=(const Jet &y) { + *this = *this - y; + return *this; + } + + Jet& operator*=(const Jet &y) { + *this = *this * y; + return *this; + } + + Jet& operator/=(const Jet &y) { + *this = *this / y; + return *this; + } + + // Compound with scalar operators. + Jet& operator+=(const T& s) { + *this = *this + s; + return *this; + } + + Jet& operator-=(const T& s) { + *this = *this - s; + return *this; + } + + Jet& operator*=(const T& s) { + *this = *this * s; + return *this; + } + + Jet& operator/=(const T& s) { + *this = *this / s; + return *this; + } + + // The scalar part. + T a; + + // The infinitesimal part. + // + // We allocate Jets on the stack and other places they might not be aligned + // to X(=16 [SSE], 32 [AVX] etc)-byte boundaries, which would prevent the safe + // use of vectorisation. If we have C++11, we can specify the alignment. + // However, the standard gives wide lattitude as to what alignments are valid, + // and it might be that the maximum supported alignment *guaranteed* to be + // supported is < 16, in which case we do not specify an alignment, as this + // implies the host is not a modern x86 machine. If using < C++11, we cannot + // specify alignment. +#ifndef CERES_USE_CXX11 + // Without >= C++11, we cannot specify the alignment so fall back to safe, + // unvectorised version. + Eigen::Matrix v; +#else + // Enable vectorisation iff the maximum supported scalar alignment is >= + // 16 bytes, as this is the minimum required by Eigen for any vectorisation. + // + // NOTE: It might be the case that we could get >= 16-byte alignment even if + // kMaxAlignBytes < 16. However we can't guarantee that this + // would happen (and it should not for any modern x86 machine) and if it + // didn't, we could get misaligned Jets. + static constexpr int kAlignOrNot = + 16 <= ::ceres::port_constants::kMaxAlignBytes + ? Eigen::AutoAlign : Eigen::DontAlign; +#if defined(EIGEN_MAX_ALIGN_BYTES) + // Eigen >= 3.3 supports AVX & FMA instructions that require 32-byte alignment + // (greater for AVX512). Rather than duplicating the detection logic, use + // Eigen's macro for the alignment size. + // + // NOTE: EIGEN_MAX_ALIGN_BYTES can be > 16 (e.g. 32 for AVX), even though + // kMaxAlignBytes will max out at 16. We are therefore relying on + // Eigen's detection logic to ensure that this does not result in + // misaligned Jets. +#define CERES_JET_ALIGN_BYTES EIGEN_MAX_ALIGN_BYTES +#else + // Eigen < 3.3 only supported 16-byte alignment. +#define CERES_JET_ALIGN_BYTES 16 +#endif + // Default to the native alignment if 16-byte alignment is not guaranteed to + // be supported. We cannot use alignof(T) as if we do, GCC 4.8 complains that + // the alignment 'is not an integer constant', although Clang accepts it. + static constexpr size_t kAlignment = kAlignOrNot == Eigen::AutoAlign + ? CERES_JET_ALIGN_BYTES : alignof(double); +#undef CERES_JET_ALIGN_BYTES + alignas(kAlignment) Eigen::Matrix v; +#endif +}; + +// Unary + +template inline +Jet const& operator+(const Jet& f) { + return f; +} + +// TODO(keir): Try adding __attribute__((always_inline)) to these functions to +// see if it causes a performance increase. + +// Unary - +template inline +Jet operator-(const Jet&f) { + return Jet(-f.a, -f.v); +} + +// Binary + +template inline +Jet operator+(const Jet& f, + const Jet& g) { + return Jet(f.a + g.a, f.v + g.v); +} + +// Binary + with a scalar: x + s +template inline +Jet operator+(const Jet& f, T s) { + return Jet(f.a + s, f.v); +} + +// Binary + with a scalar: s + x +template inline +Jet operator+(T s, const Jet& f) { + return Jet(f.a + s, f.v); +} + +// Binary - +template inline +Jet operator-(const Jet& f, + const Jet& g) { + return Jet(f.a - g.a, f.v - g.v); +} + +// Binary - with a scalar: x - s +template inline +Jet operator-(const Jet& f, T s) { + return Jet(f.a - s, f.v); +} + +// Binary - with a scalar: s - x +template inline +Jet operator-(T s, const Jet& f) { + return Jet(s - f.a, -f.v); +} + +// Binary * +template inline +Jet operator*(const Jet& f, + const Jet& g) { + return Jet(f.a * g.a, f.a * g.v + f.v * g.a); +} + +// Binary * with a scalar: x * s +template inline +Jet operator*(const Jet& f, T s) { + return Jet(f.a * s, f.v * s); +} + +// Binary * with a scalar: s * x +template inline +Jet operator*(T s, const Jet& f) { + return Jet(f.a * s, f.v * s); +} + +// Binary / +template inline +Jet operator/(const Jet& f, + const Jet& g) { + // This uses: + // + // a + u (a + u)(b - v) (a + u)(b - v) + // ----- = -------------- = -------------- + // b + v (b + v)(b - v) b^2 + // + // which holds because v*v = 0. + const T g_a_inverse = T(1.0) / g.a; + const T f_a_by_g_a = f.a * g_a_inverse; + return Jet(f.a * g_a_inverse, (f.v - f_a_by_g_a * g.v) * g_a_inverse); +} + +// Binary / with a scalar: s / x +template inline +Jet operator/(T s, const Jet& g) { + const T minus_s_g_a_inverse2 = -s / (g.a * g.a); + return Jet(s / g.a, g.v * minus_s_g_a_inverse2); +} + +// Binary / with a scalar: x / s +template inline +Jet operator/(const Jet& f, T s) { + const T s_inverse = T(1.0) / s; + return Jet(f.a * s_inverse, f.v * s_inverse); +} + +// Binary comparison operators for both scalars and jets. +#define CERES_DEFINE_JET_COMPARISON_OPERATOR(op) \ +template inline \ +bool operator op(const Jet& f, const Jet& g) { \ + return f.a op g.a; \ +} \ +template inline \ +bool operator op(const T& s, const Jet& g) { \ + return s op g.a; \ +} \ +template inline \ +bool operator op(const Jet& f, const T& s) { \ + return f.a op s; \ +} +CERES_DEFINE_JET_COMPARISON_OPERATOR( < ) // NOLINT +CERES_DEFINE_JET_COMPARISON_OPERATOR( <= ) // NOLINT +CERES_DEFINE_JET_COMPARISON_OPERATOR( > ) // NOLINT +CERES_DEFINE_JET_COMPARISON_OPERATOR( >= ) // NOLINT +CERES_DEFINE_JET_COMPARISON_OPERATOR( == ) // NOLINT +CERES_DEFINE_JET_COMPARISON_OPERATOR( != ) // NOLINT +#undef CERES_DEFINE_JET_COMPARISON_OPERATOR + +// Pull some functions from namespace std. +// +// This is necessary because we want to use the same name (e.g. 'sqrt') for +// double-valued and Jet-valued functions, but we are not allowed to put +// Jet-valued functions inside namespace std. +// +// TODO(keir): Switch to "using". +inline double abs (double x) { return std::abs(x); } +inline double log (double x) { return std::log(x); } +inline double exp (double x) { return std::exp(x); } +inline double sqrt (double x) { return std::sqrt(x); } +inline double cos (double x) { return std::cos(x); } +inline double acos (double x) { return std::acos(x); } +inline double sin (double x) { return std::sin(x); } +inline double asin (double x) { return std::asin(x); } +inline double tan (double x) { return std::tan(x); } +inline double atan (double x) { return std::atan(x); } +inline double sinh (double x) { return std::sinh(x); } +inline double cosh (double x) { return std::cosh(x); } +inline double tanh (double x) { return std::tanh(x); } +inline double floor (double x) { return std::floor(x); } +inline double ceil (double x) { return std::ceil(x); } +inline double pow (double x, double y) { return std::pow(x, y); } +inline double atan2(double y, double x) { return std::atan2(y, x); } + +// In general, f(a + h) ~= f(a) + f'(a) h, via the chain rule. + +// abs(x + h) ~= x + h or -(x + h) +template inline +Jet abs(const Jet& f) { + return f.a < T(0.0) ? -f : f; +} + +// log(a + h) ~= log(a) + h / a +template inline +Jet log(const Jet& f) { + const T a_inverse = T(1.0) / f.a; + return Jet(log(f.a), f.v * a_inverse); +} + +// exp(a + h) ~= exp(a) + exp(a) h +template inline +Jet exp(const Jet& f) { + const T tmp = exp(f.a); + return Jet(tmp, tmp * f.v); +} + +// sqrt(a + h) ~= sqrt(a) + h / (2 sqrt(a)) +template inline +Jet sqrt(const Jet& f) { + const T tmp = sqrt(f.a); + const T two_a_inverse = T(1.0) / (T(2.0) * tmp); + return Jet(tmp, f.v * two_a_inverse); +} + +// cos(a + h) ~= cos(a) - sin(a) h +template inline +Jet cos(const Jet& f) { + return Jet(cos(f.a), - sin(f.a) * f.v); +} + +// acos(a + h) ~= acos(a) - 1 / sqrt(1 - a^2) h +template inline +Jet acos(const Jet& f) { + const T tmp = - T(1.0) / sqrt(T(1.0) - f.a * f.a); + return Jet(acos(f.a), tmp * f.v); +} + +// sin(a + h) ~= sin(a) + cos(a) h +template inline +Jet sin(const Jet& f) { + return Jet(sin(f.a), cos(f.a) * f.v); +} + +// asin(a + h) ~= asin(a) + 1 / sqrt(1 - a^2) h +template inline +Jet asin(const Jet& f) { + const T tmp = T(1.0) / sqrt(T(1.0) - f.a * f.a); + return Jet(asin(f.a), tmp * f.v); +} + +// tan(a + h) ~= tan(a) + (1 + tan(a)^2) h +template inline +Jet tan(const Jet& f) { + const T tan_a = tan(f.a); + const T tmp = T(1.0) + tan_a * tan_a; + return Jet(tan_a, tmp * f.v); +} + +// atan(a + h) ~= atan(a) + 1 / (1 + a^2) h +template inline +Jet atan(const Jet& f) { + const T tmp = T(1.0) / (T(1.0) + f.a * f.a); + return Jet(atan(f.a), tmp * f.v); +} + +// sinh(a + h) ~= sinh(a) + cosh(a) h +template inline +Jet sinh(const Jet& f) { + return Jet(sinh(f.a), cosh(f.a) * f.v); +} + +// cosh(a + h) ~= cosh(a) + sinh(a) h +template inline +Jet cosh(const Jet& f) { + return Jet(cosh(f.a), sinh(f.a) * f.v); +} + +// tanh(a + h) ~= tanh(a) + (1 - tanh(a)^2) h +template inline +Jet tanh(const Jet& f) { + const T tanh_a = tanh(f.a); + const T tmp = T(1.0) - tanh_a * tanh_a; + return Jet(tanh_a, tmp * f.v); +} + +// The floor function should be used with extreme care as this operation will +// result in a zero derivative which provides no information to the solver. +// +// floor(a + h) ~= floor(a) + 0 +template inline +Jet floor(const Jet& f) { + return Jet(floor(f.a)); +} + +// The ceil function should be used with extreme care as this operation will +// result in a zero derivative which provides no information to the solver. +// +// ceil(a + h) ~= ceil(a) + 0 +template inline +Jet ceil(const Jet& f) { + return Jet(ceil(f.a)); +} + +// Bessel functions of the first kind with integer order equal to 0, 1, n. +// +// Microsoft has deprecated the j[0,1,n]() POSIX Bessel functions in favour of +// _j[0,1,n](). Where available on MSVC, use _j[0,1,n]() to avoid deprecated +// function errors in client code (the specific warning is suppressed when +// Ceres itself is built). +inline double BesselJ0(double x) { +#if defined(CERES_MSVC_USE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + return _j0(x); +#else + return j0(x); +#endif +} +inline double BesselJ1(double x) { +#if defined(CERES_MSVC_USE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + return _j1(x); +#else + return j1(x); +#endif +} +inline double BesselJn(int n, double x) { +#if defined(CERES_MSVC_USE_UNDERSCORE_PREFIXED_BESSEL_FUNCTIONS) + return _jn(n, x); +#else + return jn(n, x); +#endif +} + +// For the formulae of the derivatives of the Bessel functions see the book: +// Olver, Lozier, Boisvert, Clark, NIST Handbook of Mathematical Functions, +// Cambridge University Press 2010. +// +// Formulae are also available at http://dlmf.nist.gov + +// See formula http://dlmf.nist.gov/10.6#E3 +// j0(a + h) ~= j0(a) - j1(a) h +template inline +Jet BesselJ0(const Jet& f) { + return Jet(BesselJ0(f.a), + -BesselJ1(f.a) * f.v); +} + +// See formula http://dlmf.nist.gov/10.6#E1 +// j1(a + h) ~= j1(a) + 0.5 ( j0(a) - j2(a) ) h +template inline +Jet BesselJ1(const Jet& f) { + return Jet(BesselJ1(f.a), + T(0.5) * (BesselJ0(f.a) - BesselJn(2, f.a)) * f.v); +} + +// See formula http://dlmf.nist.gov/10.6#E1 +// j_n(a + h) ~= j_n(a) + 0.5 ( j_{n-1}(a) - j_{n+1}(a) ) h +template inline +Jet BesselJn(int n, const Jet& f) { + return Jet(BesselJn(n, f.a), + T(0.5) * (BesselJn(n - 1, f.a) - BesselJn(n + 1, f.a)) * f.v); +} + +// Jet Classification. It is not clear what the appropriate semantics are for +// these classifications. This picks that IsFinite and isnormal are "all" +// operations, i.e. all elements of the jet must be finite for the jet itself +// to be finite (or normal). For IsNaN and IsInfinite, the answer is less +// clear. This takes a "any" approach for IsNaN and IsInfinite such that if any +// part of a jet is nan or inf, then the entire jet is nan or inf. This leads +// to strange situations like a jet can be both IsInfinite and IsNaN, but in +// practice the "any" semantics are the most useful for e.g. checking that +// derivatives are sane. + +// The jet is finite if all parts of the jet are finite. +template inline +bool IsFinite(const Jet& f) { + if (!IsFinite(f.a)) { + return false; + } + for (int i = 0; i < N; ++i) { + if (!IsFinite(f.v[i])) { + return false; + } + } + return true; +} + +// The jet is infinite if any part of the jet is infinite. +template inline +bool IsInfinite(const Jet& f) { + if (IsInfinite(f.a)) { + return true; + } + for (int i = 0; i < N; i++) { + if (IsInfinite(f.v[i])) { + return true; + } + } + return false; +} + +// The jet is NaN if any part of the jet is NaN. +template inline +bool IsNaN(const Jet& f) { + if (IsNaN(f.a)) { + return true; + } + for (int i = 0; i < N; ++i) { + if (IsNaN(f.v[i])) { + return true; + } + } + return false; +} + +// The jet is normal if all parts of the jet are normal. +template inline +bool IsNormal(const Jet& f) { + if (!IsNormal(f.a)) { + return false; + } + for (int i = 0; i < N; ++i) { + if (!IsNormal(f.v[i])) { + return false; + } + } + return true; +} + +// atan2(b + db, a + da) ~= atan2(b, a) + (- b da + a db) / (a^2 + b^2) +// +// In words: the rate of change of theta is 1/r times the rate of +// change of (x, y) in the positive angular direction. +template inline +Jet atan2(const Jet& g, const Jet& f) { + // Note order of arguments: + // + // f = a + da + // g = b + db + + T const tmp = T(1.0) / (f.a * f.a + g.a * g.a); + return Jet(atan2(g.a, f.a), tmp * (- g.a * f.v + f.a * g.v)); +} + + +// pow -- base is a differentiable function, exponent is a constant. +// (a+da)^p ~= a^p + p*a^(p-1) da +template inline +Jet pow(const Jet& f, double g) { + T const tmp = g * pow(f.a, g - T(1.0)); + return Jet(pow(f.a, g), tmp * f.v); +} + +// pow -- base is a constant, exponent is a differentiable function. +// We have various special cases, see the comment for pow(Jet, Jet) for +// analysis: +// +// 1. For f > 0 we have: (f)^(g + dg) ~= f^g + f^g log(f) dg +// +// 2. For f == 0 and g > 0 we have: (f)^(g + dg) ~= f^g +// +// 3. For f < 0 and integer g we have: (f)^(g + dg) ~= f^g but if dg +// != 0, the derivatives are not defined and we return NaN. + +template inline +Jet pow(double f, const Jet& g) { + if (f == 0 && g.a > 0) { + // Handle case 2. + return Jet(T(0.0)); + } + if (f < 0 && g.a == floor(g.a)) { + // Handle case 3. + Jet ret(pow(f, g.a)); + for (int i = 0; i < N; i++) { + if (g.v[i] != T(0.0)) { + // Return a NaN when g.v != 0. + ret.v[i] = std::numeric_limits::quiet_NaN(); + } + } + return ret; + } + // Handle case 1. + T const tmp = pow(f, g.a); + return Jet(tmp, log(f) * tmp * g.v); +} + +// pow -- both base and exponent are differentiable functions. This has a +// variety of special cases that require careful handling. +// +// 1. For f > 0: +// (f + df)^(g + dg) ~= f^g + f^(g - 1) * (g * df + f * log(f) * dg) +// The numerical evaluation of f * log(f) for f > 0 is well behaved, even for +// extremely small values (e.g. 1e-99). +// +// 2. For f == 0 and g > 1: (f + df)^(g + dg) ~= 0 +// This cases is needed because log(0) can not be evaluated in the f > 0 +// expression. However the function f*log(f) is well behaved around f == 0 +// and its limit as f-->0 is zero. +// +// 3. For f == 0 and g == 1: (f + df)^(g + dg) ~= 0 + df +// +// 4. For f == 0 and 0 < g < 1: The value is finite but the derivatives are not. +// +// 5. For f == 0 and g < 0: The value and derivatives of f^g are not finite. +// +// 6. For f == 0 and g == 0: The C standard incorrectly defines 0^0 to be 1 +// "because there are applications that can exploit this definition". We +// (arbitrarily) decree that derivatives here will be nonfinite, since that +// is consistent with the behavior for f == 0, g < 0 and 0 < g < 1. +// Practically any definition could have been justified because mathematical +// consistency has been lost at this point. +// +// 7. For f < 0, g integer, dg == 0: (f + df)^(g + dg) ~= f^g + g * f^(g - 1) df +// This is equivalent to the case where f is a differentiable function and g +// is a constant (to first order). +// +// 8. For f < 0, g integer, dg != 0: The value is finite but the derivatives are +// not, because any change in the value of g moves us away from the point +// with a real-valued answer into the region with complex-valued answers. +// +// 9. For f < 0, g noninteger: The value and derivatives of f^g are not finite. + +template inline +Jet pow(const Jet& f, const Jet& g) { + if (f.a == 0 && g.a >= 1) { + // Handle cases 2 and 3. + if (g.a > 1) { + return Jet(T(0.0)); + } + return f; + } + if (f.a < 0 && g.a == floor(g.a)) { + // Handle cases 7 and 8. + T const tmp = g.a * pow(f.a, g.a - T(1.0)); + Jet ret(pow(f.a, g.a), tmp * f.v); + for (int i = 0; i < N; i++) { + if (g.v[i] != T(0.0)) { + // Return a NaN when g.v != 0. + ret.v[i] = std::numeric_limits::quiet_NaN(); + } + } + return ret; + } + // Handle the remaining cases. For cases 4,5,6,9 we allow the log() function + // to generate -HUGE_VAL or NaN, since those cases result in a nonfinite + // derivative. + T const tmp1 = pow(f.a, g.a); + T const tmp2 = g.a * pow(f.a, g.a - T(1.0)); + T const tmp3 = tmp1 * log(f.a); + return Jet(tmp1, tmp2 * f.v + tmp3 * g.v); +} + +// Define the helper functions Eigen needs to embed Jet types. +// +// NOTE(keir): machine_epsilon() and precision() are missing, because they don't +// work with nested template types (e.g. where the scalar is itself templated). +// Among other things, this means that decompositions of Jet's does not work, +// for example +// +// Matrix ... > A, x, b; +// ... +// A.solve(b, &x) +// +// does not work and will fail with a strange compiler error. +// +// TODO(keir): This is an Eigen 2.0 limitation that is lifted in 3.0. When we +// switch to 3.0, also add the rest of the specialization functionality. +template inline const Jet& ei_conj(const Jet& x) { return x; } // NOLINT +template inline const Jet& ei_real(const Jet& x) { return x; } // NOLINT +template inline Jet ei_imag(const Jet& ) { return Jet(0.0); } // NOLINT +template inline Jet ei_abs (const Jet& x) { return fabs(x); } // NOLINT +template inline Jet ei_abs2(const Jet& x) { return x * x; } // NOLINT +template inline Jet ei_sqrt(const Jet& x) { return sqrt(x); } // NOLINT +template inline Jet ei_exp (const Jet& x) { return exp(x); } // NOLINT +template inline Jet ei_log (const Jet& x) { return log(x); } // NOLINT +template inline Jet ei_sin (const Jet& x) { return sin(x); } // NOLINT +template inline Jet ei_cos (const Jet& x) { return cos(x); } // NOLINT +template inline Jet ei_tan (const Jet& x) { return tan(x); } // NOLINT +template inline Jet ei_atan(const Jet& x) { return atan(x); } // NOLINT +template inline Jet ei_sinh(const Jet& x) { return sinh(x); } // NOLINT +template inline Jet ei_cosh(const Jet& x) { return cosh(x); } // NOLINT +template inline Jet ei_tanh(const Jet& x) { return tanh(x); } // NOLINT +template inline Jet ei_pow (const Jet& x, Jet y) { return pow(x, y); } // NOLINT + +// Note: This has to be in the ceres namespace for argument dependent lookup to +// function correctly. Otherwise statements like CHECK_LE(x, 2.0) fail with +// strange compile errors. +template +inline std::ostream &operator<<(std::ostream &s, const Jet& z) { + s << "[" << z.a << " ; "; + for (int i = 0; i < N; ++i) { + s << z.v[i]; + if (i != N - 1) { + s << ", "; + } + } + s << "]"; + return s; +} + +} // namespace ceres + +namespace Eigen { + +// Creating a specialization of NumTraits enables placing Jet objects inside +// Eigen arrays, getting all the goodness of Eigen combined with autodiff. +template +struct NumTraits > { + typedef ceres::Jet Real; + typedef ceres::Jet NonInteger; + typedef ceres::Jet Nested; + typedef ceres::Jet Literal; + + static typename ceres::Jet dummy_precision() { + return ceres::Jet(1e-12); + } + + static inline Real epsilon() { + return Real(std::numeric_limits::epsilon()); + } + + static inline int digits10() { return NumTraits::digits10(); } + + enum { + IsComplex = 0, + IsInteger = 0, + IsSigned, + ReadCost = 1, + AddCost = 1, + // For Jet types, multiplication is more expensive than addition. + MulCost = 3, + HasFloatingPoint = 1, + RequireInitialization = 1 + }; + + template + struct Div { + enum { +#if defined(EIGEN_VECTORIZE_AVX) + AVX = true, +#else + AVX = false, +#endif + + // Assuming that for Jets, division is as expensive as + // multiplication. + Cost = 3 + }; + }; +}; + +#if EIGEN_VERSION_AT_LEAST(3, 3, 0) +// Specifying the return type of binary operations between Jets and scalar types +// allows you to perform matrix/array operations with Eigen matrices and arrays +// such as addition, subtraction, multiplication, and division where one Eigen +// matrix/array is of type Jet and the other is a scalar type. This improves +// performance by using the optimized scalar-to-Jet binary operations but +// is only available on Eigen versions >= 3.3 +template +struct ScalarBinaryOpTraits, T, BinaryOp> { + typedef ceres::Jet ReturnType; +}; +template +struct ScalarBinaryOpTraits, BinaryOp> { + typedef ceres::Jet ReturnType; +}; +#endif // EIGEN_VERSION_AT_LEAST(3, 3, 0) + +} // namespace Eigen + +#endif // CERES_PUBLIC_JET_H_ diff --git a/include/ceres/local_parameterization.h b/include/ceres/local_parameterization.h new file mode 100644 index 0000000..8a4ca56 --- /dev/null +++ b/include/ceres/local_parameterization.h @@ -0,0 +1,323 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_LOCAL_PARAMETERIZATION_H_ +#define CERES_PUBLIC_LOCAL_PARAMETERIZATION_H_ + +#include +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// Purpose: Sometimes parameter blocks x can overparameterize a problem +// +// min f(x) +// x +// +// In that case it is desirable to choose a parameterization for the +// block itself to remove the null directions of the cost. More +// generally, if x lies on a manifold of a smaller dimension than the +// ambient space that it is embedded in, then it is numerically and +// computationally more effective to optimize it using a +// parameterization that lives in the tangent space of that manifold +// at each point. +// +// For example, a sphere in three dimensions is a 2 dimensional +// manifold, embedded in a three dimensional space. At each point on +// the sphere, the plane tangent to it defines a two dimensional +// tangent space. For a cost function defined on this sphere, given a +// point x, moving in the direction normal to the sphere at that point +// is not useful. Thus a better way to do a local optimization is to +// optimize over two dimensional vector delta in the tangent space at +// that point and then "move" to the point x + delta, where the move +// operation involves projecting back onto the sphere. Doing so +// removes a redundent dimension from the optimization, making it +// numerically more robust and efficient. +// +// More generally we can define a function +// +// x_plus_delta = Plus(x, delta), +// +// where x_plus_delta has the same size as x, and delta is of size +// less than or equal to x. The function Plus, generalizes the +// definition of vector addition. Thus it satisfies the identify +// +// Plus(x, 0) = x, for all x. +// +// A trivial version of Plus is when delta is of the same size as x +// and +// +// Plus(x, delta) = x + delta +// +// A more interesting case if x is two dimensional vector, and the +// user wishes to hold the first coordinate constant. Then, delta is a +// scalar and Plus is defined as +// +// Plus(x, delta) = x + [0] * delta +// [1] +// +// An example that occurs commonly in Structure from Motion problems +// is when camera rotations are parameterized using Quaternion. There, +// it is useful only make updates orthogonal to that 4-vector defining +// the quaternion. One way to do this is to let delta be a 3 +// dimensional vector and define Plus to be +// +// Plus(x, delta) = [cos(|delta|), sin(|delta|) delta / |delta|] * x +// +// The multiplication between the two 4-vectors on the RHS is the +// standard quaternion product. +// +// Given g and a point x, optimizing f can now be restated as +// +// min f(Plus(x, delta)) +// delta +// +// Given a solution delta to this problem, the optimal value is then +// given by +// +// x* = Plus(x, delta) +// +// The class LocalParameterization defines the function Plus and its +// Jacobian which is needed to compute the Jacobian of f w.r.t delta. +class CERES_EXPORT LocalParameterization { + public: + virtual ~LocalParameterization(); + + // Generalization of the addition operation, + // + // x_plus_delta = Plus(x, delta) + // + // with the condition that Plus(x, 0) = x. + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const = 0; + + // The jacobian of Plus(x, delta) w.r.t delta at delta = 0. + // + // jacobian is a row-major GlobalSize() x LocalSize() matrix. + virtual bool ComputeJacobian(const double* x, double* jacobian) const = 0; + + // local_matrix = global_matrix * jacobian + // + // global_matrix is a num_rows x GlobalSize row major matrix. + // local_matrix is a num_rows x LocalSize row major matrix. + // jacobian(x) is the matrix returned by ComputeJacobian at x. + // + // This is only used by GradientProblem. For most normal uses, it is + // okay to use the default implementation. + virtual bool MultiplyByJacobian(const double* x, + const int num_rows, + const double* global_matrix, + double* local_matrix) const; + + // Size of x. + virtual int GlobalSize() const = 0; + + // Size of delta. + virtual int LocalSize() const = 0; +}; + +// Some basic parameterizations + +// Identity Parameterization: Plus(x, delta) = x + delta +class CERES_EXPORT IdentityParameterization : public LocalParameterization { + public: + explicit IdentityParameterization(int size); + virtual ~IdentityParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, + double* jacobian) const; + virtual bool MultiplyByJacobian(const double* x, + const int num_cols, + const double* global_matrix, + double* local_matrix) const; + virtual int GlobalSize() const { return size_; } + virtual int LocalSize() const { return size_; } + + private: + const int size_; +}; + +// Hold a subset of the parameters inside a parameter block constant. +class CERES_EXPORT SubsetParameterization : public LocalParameterization { + public: + explicit SubsetParameterization(int size, + const std::vector& constant_parameters); + virtual ~SubsetParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, + double* jacobian) const; + virtual bool MultiplyByJacobian(const double* x, + const int num_cols, + const double* global_matrix, + double* local_matrix) const; + virtual int GlobalSize() const { + return static_cast(constancy_mask_.size()); + } + virtual int LocalSize() const { return local_size_; } + + private: + const int local_size_; + std::vector constancy_mask_; +}; + +// Plus(x, delta) = [cos(|delta|), sin(|delta|) delta / |delta|] * x +// with * being the quaternion multiplication operator. Here we assume +// that the first element of the quaternion vector is the real (cos +// theta) part. +class CERES_EXPORT QuaternionParameterization : public LocalParameterization { + public: + virtual ~QuaternionParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, + double* jacobian) const; + virtual int GlobalSize() const { return 4; } + virtual int LocalSize() const { return 3; } +}; + +// Implements the quaternion local parameterization for Eigen's representation +// of the quaternion. Eigen uses a different internal memory layout for the +// elements of the quaternion than what is commonly used. Specifically, Eigen +// stores the elements in memory as [x, y, z, w] where the real part is last +// whereas it is typically stored first. Note, when creating an Eigen quaternion +// through the constructor the elements are accepted in w, x, y, z order. Since +// Ceres operates on parameter blocks which are raw double pointers this +// difference is important and requires a different parameterization. +// +// Plus(x, delta) = [sin(|delta|) delta / |delta|, cos(|delta|)] * x +// with * being the quaternion multiplication operator. +class CERES_EXPORT EigenQuaternionParameterization + : public ceres::LocalParameterization { + public: + virtual ~EigenQuaternionParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, double* jacobian) const; + virtual int GlobalSize() const { return 4; } + virtual int LocalSize() const { return 3; } +}; + +// This provides a parameterization for homogeneous vectors which are commonly +// used in Structure for Motion problems. One example where they are used is +// in representing points whose triangulation is ill-conditioned. Here +// it is advantageous to use an over-parameterization since homogeneous vectors +// can represent points at infinity. +// +// The plus operator is defined as +// Plus(x, delta) = +// [sin(0.5 * |delta|) * delta / |delta|, cos(0.5 * |delta|)] * x +// with * defined as an operator which applies the update orthogonal to x to +// remain on the sphere. We assume that the last element of x is the scalar +// component. The size of the homogeneous vector is required to be greater than +// 1. +class CERES_EXPORT HomogeneousVectorParameterization : + public LocalParameterization { + public: + explicit HomogeneousVectorParameterization(int size); + virtual ~HomogeneousVectorParameterization() {} + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, + double* jacobian) const; + virtual int GlobalSize() const { return size_; } + virtual int LocalSize() const { return size_ - 1; } + + private: + const int size_; +}; + +// Construct a local parameterization by taking the Cartesian product +// of a number of other local parameterizations. This is useful, when +// a parameter block is the cartesian product of two or more +// manifolds. For example the parameters of a camera consist of a +// rotation and a translation, i.e., SO(3) x R^3. +// +// Currently this class supports taking the cartesian product of up to +// four local parameterizations. +// +// Example usage: +// +// ProductParameterization product_param(new QuaterionionParameterization(), +// new IdentityParameterization(3)); +// +// is the local parameterization for a rigid transformation, where the +// rotation is represented using a quaternion. +class CERES_EXPORT ProductParameterization : public LocalParameterization { + public: + // + // NOTE: All the constructors take ownership of the input local + // parameterizations. + // + ProductParameterization(LocalParameterization* local_param1, + LocalParameterization* local_param2); + + ProductParameterization(LocalParameterization* local_param1, + LocalParameterization* local_param2, + LocalParameterization* local_param3); + + ProductParameterization(LocalParameterization* local_param1, + LocalParameterization* local_param2, + LocalParameterization* local_param3, + LocalParameterization* local_param4); + + virtual ~ProductParameterization(); + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const; + virtual bool ComputeJacobian(const double* x, + double* jacobian) const; + virtual int GlobalSize() const { return global_size_; } + virtual int LocalSize() const { return local_size_; } + + private: + void Init(); + + std::vector local_params_; + int local_size_; + int global_size_; + int buffer_size_; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_LOCAL_PARAMETERIZATION_H_ diff --git a/include/ceres/loss_function.h b/include/ceres/loss_function.h new file mode 100644 index 0000000..0512c13 --- /dev/null +++ b/include/ceres/loss_function.h @@ -0,0 +1,428 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// The LossFunction interface is the way users describe how residuals +// are converted to cost terms for the overall problem cost function. +// For the exact manner in which loss functions are converted to the +// overall cost for a problem, see problem.h. +// +// For least squares problem where there are no outliers and standard +// squared loss is expected, it is not necessary to create a loss +// function; instead passing a NULL to the problem when adding +// residuals implies a standard squared loss. +// +// For least squares problems where the minimization may encounter +// input terms that contain outliers, that is, completely bogus +// measurements, it is important to use a loss function that reduces +// their associated penalty. +// +// Consider a structure from motion problem. The unknowns are 3D +// points and camera parameters, and the measurements are image +// coordinates describing the expected reprojected position for a +// point in a camera. For example, we want to model the geometry of a +// street scene with fire hydrants and cars, observed by a moving +// camera with unknown parameters, and the only 3D points we care +// about are the pointy tippy-tops of the fire hydrants. Our magic +// image processing algorithm, which is responsible for producing the +// measurements that are input to Ceres, has found and matched all +// such tippy-tops in all image frames, except that in one of the +// frame it mistook a car's headlight for a hydrant. If we didn't do +// anything special (i.e. if we used a basic quadratic loss), the +// residual for the erroneous measurement will result in extreme error +// due to the quadratic nature of squared loss. This results in the +// entire solution getting pulled away from the optimimum to reduce +// the large error that would otherwise be attributed to the wrong +// measurement. +// +// Using a robust loss function, the cost for large residuals is +// reduced. In the example above, this leads to outlier terms getting +// downweighted so they do not overly influence the final solution. +// +// What cost function is best? +// +// In general, there isn't a principled way to select a robust loss +// function. The authors suggest starting with a non-robust cost, then +// only experimenting with robust loss functions if standard squared +// loss doesn't work. + +#ifndef CERES_PUBLIC_LOSS_FUNCTION_H_ +#define CERES_PUBLIC_LOSS_FUNCTION_H_ + +#include "glog/logging.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +class CERES_EXPORT LossFunction { + public: + virtual ~LossFunction() {} + + // For a residual vector with squared 2-norm 'sq_norm', this method + // is required to fill in the value and derivatives of the loss + // function (rho in this example): + // + // out[0] = rho(sq_norm), + // out[1] = rho'(sq_norm), + // out[2] = rho''(sq_norm), + // + // Here the convention is that the contribution of a term to the + // cost function is given by 1/2 rho(s), where + // + // s = ||residuals||^2. + // + // Calling the method with a negative value of 's' is an error and + // the implementations are not required to handle that case. + // + // Most sane choices of rho() satisfy: + // + // rho(0) = 0, + // rho'(0) = 1, + // rho'(s) < 1 in outlier region, + // rho''(s) < 0 in outlier region, + // + // so that they mimic the least squares cost for small residuals. + virtual void Evaluate(double sq_norm, double out[3]) const = 0; +}; + +// Some common implementations follow below. +// +// Note: in the region of interest (i.e. s < 3) we have: +// TrivialLoss >= HuberLoss >= SoftLOneLoss >= CauchyLoss + + +// This corresponds to no robustification. +// +// rho(s) = s +// +// At s = 0: rho = [0, 1, 0]. +// +// It is not normally necessary to use this, as passing NULL for the +// loss function when building the problem accomplishes the same +// thing. +class CERES_EXPORT TrivialLoss : public LossFunction { + public: + virtual void Evaluate(double, double*) const; +}; + +// Scaling +// ------- +// Given one robustifier +// s -> rho(s) +// one can change the length scale at which robustification takes +// place, by adding a scale factor 'a' as follows: +// +// s -> a^2 rho(s / a^2). +// +// The first and second derivatives are: +// +// s -> rho'(s / a^2), +// s -> (1 / a^2) rho''(s / a^2), +// +// but the behaviour near s = 0 is the same as the original function, +// i.e. +// +// rho(s) = s + higher order terms, +// a^2 rho(s / a^2) = s + higher order terms. +// +// The scalar 'a' should be positive. +// +// The reason for the appearance of squaring is that 'a' is in the +// units of the residual vector norm whereas 's' is a squared +// norm. For applications it is more convenient to specify 'a' than +// its square. The commonly used robustifiers below are described in +// un-scaled format (a = 1) but their implementations work for any +// non-zero value of 'a'. + +// Huber. +// +// rho(s) = s for s <= 1, +// rho(s) = 2 sqrt(s) - 1 for s >= 1. +// +// At s = 0: rho = [0, 1, 0]. +// +// The scaling parameter 'a' corresponds to 'delta' on this page: +// http://en.wikipedia.org/wiki/Huber_Loss_Function +class CERES_EXPORT HuberLoss : public LossFunction { + public: + explicit HuberLoss(double a) : a_(a), b_(a * a) { } + virtual void Evaluate(double, double*) const; + + private: + const double a_; + // b = a^2. + const double b_; +}; + +// Soft L1, similar to Huber but smooth. +// +// rho(s) = 2 (sqrt(1 + s) - 1). +// +// At s = 0: rho = [0, 1, -1/2]. +class CERES_EXPORT SoftLOneLoss : public LossFunction { + public: + explicit SoftLOneLoss(double a) : b_(a * a), c_(1 / b_) { } + virtual void Evaluate(double, double*) const; + + private: + // b = a^2. + const double b_; + // c = 1 / a^2. + const double c_; +}; + +// Inspired by the Cauchy distribution +// +// rho(s) = log(1 + s). +// +// At s = 0: rho = [0, 1, -1]. +class CERES_EXPORT CauchyLoss : public LossFunction { + public: + explicit CauchyLoss(double a) : b_(a * a), c_(1 / b_) { } + virtual void Evaluate(double, double*) const; + + private: + // b = a^2. + const double b_; + // c = 1 / a^2. + const double c_; +}; + +// Loss that is capped beyond a certain level using the arc-tangent function. +// The scaling parameter 'a' determines the level where falloff occurs. +// For costs much smaller than 'a', the loss function is linear and behaves like +// TrivialLoss, and for values much larger than 'a' the value asymptotically +// approaches the constant value of a * PI / 2. +// +// rho(s) = a atan(s / a). +// +// At s = 0: rho = [0, 1, 0]. +class CERES_EXPORT ArctanLoss : public LossFunction { + public: + explicit ArctanLoss(double a) : a_(a), b_(1 / (a * a)) { } + virtual void Evaluate(double, double*) const; + + private: + const double a_; + // b = 1 / a^2. + const double b_; +}; + +// Loss function that maps to approximately zero cost in a range around the +// origin, and reverts to linear in error (quadratic in cost) beyond this range. +// The tolerance parameter 'a' sets the nominal point at which the +// transition occurs, and the transition size parameter 'b' sets the nominal +// distance over which most of the transition occurs. Both a and b must be +// greater than zero, and typically b will be set to a fraction of a. +// The slope rho'[s] varies smoothly from about 0 at s <= a - b to +// about 1 at s >= a + b. +// +// The term is computed as: +// +// rho(s) = b log(1 + exp((s - a) / b)) - c0. +// +// where c0 is chosen so that rho(0) == 0 +// +// c0 = b log(1 + exp(-a / b) +// +// This has the following useful properties: +// +// rho(s) == 0 for s = 0 +// rho'(s) ~= 0 for s << a - b +// rho'(s) ~= 1 for s >> a + b +// rho''(s) > 0 for all s +// +// In addition, all derivatives are continuous, and the curvature is +// concentrated in the range a - b to a + b. +// +// At s = 0: rho = [0, ~0, ~0]. +class CERES_EXPORT TolerantLoss : public LossFunction { + public: + explicit TolerantLoss(double a, double b); + virtual void Evaluate(double, double*) const; + + private: + const double a_, b_, c_; +}; + +// This is the Tukey biweight loss function which aggressively +// attempts to suppress large errors. +// +// The term is computed as: +// +// rho(s) = a^2 / 6 * (1 - (1 - s / a^2)^3 ) for s <= a^2, +// rho(s) = a^2 / 6 for s > a^2. +// +// At s = 0: rho = [0, 0.5, -1 / a^2] +class CERES_EXPORT TukeyLoss : public ceres::LossFunction { + public: + explicit TukeyLoss(double a) : a_squared_(a * a) { } + virtual void Evaluate(double, double*) const; + + private: + const double a_squared_; +}; + +// Composition of two loss functions. The error is the result of first +// evaluating g followed by f to yield the composition f(g(s)). +// The loss functions must not be NULL. +class CERES_EXPORT ComposedLoss : public LossFunction { + public: + explicit ComposedLoss(const LossFunction* f, Ownership ownership_f, + const LossFunction* g, Ownership ownership_g); + virtual ~ComposedLoss(); + virtual void Evaluate(double, double*) const; + + private: + internal::scoped_ptr f_, g_; + const Ownership ownership_f_, ownership_g_; +}; + +// The discussion above has to do with length scaling: it affects the space +// in which s is measured. Sometimes you want to simply scale the output +// value of the robustifier. For example, you might want to weight +// different error terms differently (e.g., weight pixel reprojection +// errors differently from terrain errors). +// +// If rho is the wrapped robustifier, then this simply outputs +// s -> a * rho(s) +// +// The first and second derivatives are, not surprisingly +// s -> a * rho'(s) +// s -> a * rho''(s) +// +// Since we treat the a NULL Loss function as the Identity loss +// function, rho = NULL is a valid input and will result in the input +// being scaled by a. This provides a simple way of implementing a +// scaled ResidualBlock. +class CERES_EXPORT ScaledLoss : public LossFunction { + public: + // Constructs a ScaledLoss wrapping another loss function. Takes + // ownership of the wrapped loss function or not depending on the + // ownership parameter. + ScaledLoss(const LossFunction* rho, double a, Ownership ownership) : + rho_(rho), a_(a), ownership_(ownership) { } + + virtual ~ScaledLoss() { + if (ownership_ == DO_NOT_TAKE_OWNERSHIP) { + rho_.release(); + } + } + virtual void Evaluate(double, double*) const; + + private: + internal::scoped_ptr rho_; + const double a_; + const Ownership ownership_; + CERES_DISALLOW_COPY_AND_ASSIGN(ScaledLoss); +}; + +// Sometimes after the optimization problem has been constructed, we +// wish to mutate the scale of the loss function. For example, when +// performing estimation from data which has substantial outliers, +// convergence can be improved by starting out with a large scale, +// optimizing the problem and then reducing the scale. This can have +// better convergence behaviour than just using a loss function with a +// small scale. +// +// This templated class allows the user to implement a loss function +// whose scale can be mutated after an optimization problem has been +// constructed. +// +// Since we treat the a NULL Loss function as the Identity loss +// function, rho = NULL is a valid input. +// +// Example usage +// +// Problem problem; +// +// // Add parameter blocks +// +// CostFunction* cost_function = +// new AutoDiffCostFunction < UW_Camera_Mapper, 2, 9, 3>( +// new UW_Camera_Mapper(feature_x, feature_y)); +// +// LossFunctionWrapper* loss_function(new HuberLoss(1.0), TAKE_OWNERSHIP); +// +// problem.AddResidualBlock(cost_function, loss_function, parameters); +// +// Solver::Options options; +// Solger::Summary summary; +// +// Solve(options, &problem, &summary) +// +// loss_function->Reset(new HuberLoss(1.0), TAKE_OWNERSHIP); +// +// Solve(options, &problem, &summary) +// +class CERES_EXPORT LossFunctionWrapper : public LossFunction { + public: + LossFunctionWrapper(LossFunction* rho, Ownership ownership) + : rho_(rho), ownership_(ownership) { + } + + virtual ~LossFunctionWrapper() { + if (ownership_ == DO_NOT_TAKE_OWNERSHIP) { + rho_.release(); + } + } + + virtual void Evaluate(double sq_norm, double out[3]) const { + if (rho_.get() == NULL) { + out[0] = sq_norm; + out[1] = 1.0; + out[2] = 0.0; + } + else { + rho_->Evaluate(sq_norm, out); + } + } + + void Reset(LossFunction* rho, Ownership ownership) { + if (ownership_ == DO_NOT_TAKE_OWNERSHIP) { + rho_.release(); + } + rho_.reset(rho); + ownership_ = ownership; + } + + private: + internal::scoped_ptr rho_; + Ownership ownership_; + CERES_DISALLOW_COPY_AND_ASSIGN(LossFunctionWrapper); +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_LOSS_FUNCTION_H_ diff --git a/include/ceres/normal_prior.h b/include/ceres/normal_prior.h new file mode 100644 index 0000000..cd98b4c --- /dev/null +++ b/include/ceres/normal_prior.h @@ -0,0 +1,78 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Cost term that implements a prior on a parameter block using a +// normal distribution. + +#ifndef CERES_PUBLIC_NORMAL_PRIOR_H_ +#define CERES_PUBLIC_NORMAL_PRIOR_H_ + +#include "ceres/cost_function.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// Implements a cost function of the form +// +// cost(x) = ||A(x - b)||^2 +// +// where, the matrix A and the vector b are fixed and x is the +// variable. In case the user is interested in implementing a cost +// function of the form +// +// cost(x) = (x - mu)^T S^{-1} (x - mu) +// +// where, mu is a vector and S is a covariance matrix, then, A = +// S^{-1/2}, i.e the matrix A is the square root of the inverse of the +// covariance, also known as the stiffness matrix. There are however +// no restrictions on the shape of A. It is free to be rectangular, +// which would be the case if the covariance matrix S is rank +// deficient. + +class CERES_EXPORT NormalPrior: public CostFunction { + public: + // Check that the number of rows in the vector b are the same as the + // number of columns in the matrix A, crash otherwise. + NormalPrior(const Matrix& A, const Vector& b); + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const; + private: + Matrix A_; + Vector b_; +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_NORMAL_PRIOR_H_ diff --git a/include/ceres/numeric_diff_cost_function.h b/include/ceres/numeric_diff_cost_function.h new file mode 100644 index 0000000..5dfaeab --- /dev/null +++ b/include/ceres/numeric_diff_cost_function.h @@ -0,0 +1,319 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) +// +// Create CostFunctions as needed by the least squares framework with jacobians +// computed via numeric (a.k.a. finite) differentiation. For more details see +// http://en.wikipedia.org/wiki/Numerical_differentiation. +// +// To get an numerically differentiated cost function, you must define +// a class with a operator() (a functor) that computes the residuals. +// +// The function must write the computed value in the last argument +// (the only non-const one) and return true to indicate success. +// Please see cost_function.h for details on how the return value +// maybe used to impose simple constraints on the parameter block. +// +// For example, consider a scalar error e = k - x'y, where both x and y are +// two-dimensional column vector parameters, the prime sign indicates +// transposition, and k is a constant. The form of this error, which is the +// difference between a constant and an expression, is a common pattern in least +// squares problems. For example, the value x'y might be the model expectation +// for a series of measurements, where there is an instance of the cost function +// for each measurement k. +// +// The actual cost added to the total problem is e^2, or (k - x'k)^2; however, +// the squaring is implicitly done by the optimization framework. +// +// To write an numerically-differentiable cost function for the above model, first +// define the object +// +// class MyScalarCostFunctor { +// MyScalarCostFunctor(double k): k_(k) {} +// +// bool operator()(const double* const x, +// const double* const y, +// double* residuals) const { +// residuals[0] = k_ - x[0] * y[0] + x[1] * y[1]; +// return true; +// } +// +// private: +// double k_; +// }; +// +// Note that in the declaration of operator() the input parameters x +// and y come first, and are passed as const pointers to arrays of +// doubles. If there were three input parameters, then the third input +// parameter would come after y. The output is always the last +// parameter, and is also a pointer to an array. In the example above, +// the residual is a scalar, so only residuals[0] is set. +// +// Then given this class definition, the numerically differentiated +// cost function with central differences used for computing the +// derivative can be constructed as follows. +// +// CostFunction* cost_function +// = new NumericDiffCostFunction( +// new MyScalarCostFunctor(1.0)); ^ ^ ^ ^ +// | | | | +// Finite Differencing Scheme -+ | | | +// Dimension of residual ------------+ | | +// Dimension of x ----------------------+ | +// Dimension of y -------------------------+ +// +// In this example, there is usually an instance for each measurement of k. +// +// In the instantiation above, the template parameters following +// "MyScalarCostFunctor", "1, 2, 2", describe the functor as computing +// a 1-dimensional output from two arguments, both 2-dimensional. +// +// NumericDiffCostFunction also supports cost functions with a +// runtime-determined number of residuals. For example: +// +// CostFunction* cost_function +// = new NumericDiffCostFunction( +// new CostFunctorWithDynamicNumResiduals(1.0), ^ ^ ^ +// TAKE_OWNERSHIP, | | | +// runtime_number_of_residuals); <----+ | | | +// | | | | +// | | | | +// Actual number of residuals ------+ | | | +// Indicate dynamic number of residuals --------------------+ | | +// Dimension of x ------------------------------------------------+ | +// Dimension of y ---------------------------------------------------+ +// +// The framework can currently accommodate cost functions of up to 10 +// independent variables, and there is no limit on the dimensionality +// of each of them. +// +// The central difference method is considerably more accurate at the cost of +// twice as many function evaluations than forward difference. Consider using +// central differences begin with, and only after that works, trying forward +// difference to improve performance. +// +// WARNING #1: A common beginner's error when first using +// NumericDiffCostFunction is to get the sizing wrong. In particular, +// there is a tendency to set the template parameters to (dimension of +// residual, number of parameters) instead of passing a dimension +// parameter for *every parameter*. In the example above, that would +// be , which is missing the last '2' +// argument. Please be careful when setting the size parameters. +// +//////////////////////////////////////////////////////////////////////////// +//////////////////////////////////////////////////////////////////////////// +// +// ALTERNATE INTERFACE +// +// For a variety of reasons, including compatibility with legacy code, +// NumericDiffCostFunction can also take CostFunction objects as +// input. The following describes how. +// +// To get a numerically differentiated cost function, define a +// subclass of CostFunction such that the Evaluate() function ignores +// the jacobian parameter. The numeric differentiation wrapper will +// fill in the jacobian parameter if necessary by repeatedly calling +// the Evaluate() function with small changes to the appropriate +// parameters, and computing the slope. For performance, the numeric +// differentiation wrapper class is templated on the concrete cost +// function, even though it could be implemented only in terms of the +// virtual CostFunction interface. +// +// The numerically differentiated version of a cost function for a cost function +// can be constructed as follows: +// +// CostFunction* cost_function +// = new NumericDiffCostFunction( +// new MyCostFunction(...), TAKE_OWNERSHIP); +// +// where MyCostFunction has 1 residual and 2 parameter blocks with sizes 4 and 8 +// respectively. Look at the tests for a more detailed example. +// +// TODO(keir): Characterize accuracy; mention pitfalls; provide alternatives. + +#ifndef CERES_PUBLIC_NUMERIC_DIFF_COST_FUNCTION_H_ +#define CERES_PUBLIC_NUMERIC_DIFF_COST_FUNCTION_H_ + +#include "Eigen/Dense" +#include "ceres/cost_function.h" +#include "ceres/internal/numeric_diff.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/numeric_diff_options.h" +#include "ceres/sized_cost_function.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { + +template // Number of parameters in block 9. +class NumericDiffCostFunction + : public SizedCostFunction { + public: + NumericDiffCostFunction( + CostFunctor* functor, + Ownership ownership = TAKE_OWNERSHIP, + int num_residuals = kNumResiduals, + const NumericDiffOptions& options = NumericDiffOptions()) + : functor_(functor), + ownership_(ownership), + options_(options) { + if (kNumResiduals == DYNAMIC) { + SizedCostFunction + ::set_num_residuals(num_residuals); + } + } + + ~NumericDiffCostFunction() { + if (ownership_ != TAKE_OWNERSHIP) { + functor_.release(); + } + } + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + using internal::FixedArray; + using internal::NumericDiff; + + const int kNumParameters = N0 + N1 + N2 + N3 + N4 + N5 + N6 + N7 + N8 + N9; + const int kNumParameterBlocks = + (N0 > 0) + (N1 > 0) + (N2 > 0) + (N3 > 0) + (N4 > 0) + + (N5 > 0) + (N6 > 0) + (N7 > 0) + (N8 > 0) + (N9 > 0); + + // Get the function value (residuals) at the the point to evaluate. + if (!internal::EvaluateImpl( + functor_.get(), + parameters, + residuals, + functor_.get())) { + return false; + } + + if (jacobians == NULL) { + return true; + } + + // Create a copy of the parameters which will get mutated. + FixedArray parameters_copy(kNumParameters); + FixedArray parameters_reference_copy(kNumParameterBlocks); + + parameters_reference_copy[0] = parameters_copy.get(); + if (N1) parameters_reference_copy[1] = parameters_reference_copy[0] + N0; + if (N2) parameters_reference_copy[2] = parameters_reference_copy[1] + N1; + if (N3) parameters_reference_copy[3] = parameters_reference_copy[2] + N2; + if (N4) parameters_reference_copy[4] = parameters_reference_copy[3] + N3; + if (N5) parameters_reference_copy[5] = parameters_reference_copy[4] + N4; + if (N6) parameters_reference_copy[6] = parameters_reference_copy[5] + N5; + if (N7) parameters_reference_copy[7] = parameters_reference_copy[6] + N6; + if (N8) parameters_reference_copy[8] = parameters_reference_copy[7] + N7; + if (N9) parameters_reference_copy[9] = parameters_reference_copy[8] + N8; + +#define CERES_COPY_PARAMETER_BLOCK(block) \ + if (N ## block) memcpy(parameters_reference_copy[block], \ + parameters[block], \ + sizeof(double) * N ## block); // NOLINT + + CERES_COPY_PARAMETER_BLOCK(0); + CERES_COPY_PARAMETER_BLOCK(1); + CERES_COPY_PARAMETER_BLOCK(2); + CERES_COPY_PARAMETER_BLOCK(3); + CERES_COPY_PARAMETER_BLOCK(4); + CERES_COPY_PARAMETER_BLOCK(5); + CERES_COPY_PARAMETER_BLOCK(6); + CERES_COPY_PARAMETER_BLOCK(7); + CERES_COPY_PARAMETER_BLOCK(8); + CERES_COPY_PARAMETER_BLOCK(9); + +#undef CERES_COPY_PARAMETER_BLOCK + +#define CERES_EVALUATE_JACOBIAN_FOR_BLOCK(block) \ + if (N ## block && jacobians[block] != NULL) { \ + if (!NumericDiff::EvaluateJacobianForParameterBlock( \ + functor_.get(), \ + residuals, \ + options_, \ + SizedCostFunction::num_residuals(), \ + block, \ + N ## block, \ + parameters_reference_copy.get(), \ + jacobians[block])) { \ + return false; \ + } \ + } + + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(0); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(1); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(2); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(3); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(4); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(5); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(6); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(7); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(8); + CERES_EVALUATE_JACOBIAN_FOR_BLOCK(9); + +#undef CERES_EVALUATE_JACOBIAN_FOR_BLOCK + + return true; + } + + private: + internal::scoped_ptr functor_; + Ownership ownership_; + NumericDiffOptions options_; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_NUMERIC_DIFF_COST_FUNCTION_H_ diff --git a/include/ceres/numeric_diff_options.h b/include/ceres/numeric_diff_options.h new file mode 100644 index 0000000..119c8a8 --- /dev/null +++ b/include/ceres/numeric_diff_options.h @@ -0,0 +1,79 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: tbennun@gmail.com (Tal Ben-Nun) +// + +#ifndef CERES_PUBLIC_NUMERIC_DIFF_OPTIONS_H_ +#define CERES_PUBLIC_NUMERIC_DIFF_OPTIONS_H_ + +namespace ceres { + +// Options pertaining to numeric differentiation (e.g., convergence criteria, +// step sizes). +struct CERES_EXPORT NumericDiffOptions { + NumericDiffOptions() { + relative_step_size = 1e-6; + ridders_relative_initial_step_size = 1e-2; + max_num_ridders_extrapolations = 10; + ridders_epsilon = 1e-12; + ridders_step_shrink_factor = 2.0; + } + + // Numeric differentiation step size (multiplied by parameter block's + // order of magnitude). If parameters are close to zero, the step size + // is set to sqrt(machine_epsilon). + double relative_step_size; + + // Initial step size for Ridders adaptive numeric differentiation (multiplied + // by parameter block's order of magnitude). + // If parameters are close to zero, Ridders' method sets the step size + // directly to this value. This parameter is separate from + // "relative_step_size" in order to set a different default value. + // + // Note: For Ridders' method to converge, the step size should be initialized + // to a value that is large enough to produce a significant change in the + // function. As the derivative is estimated, the step size decreases. + double ridders_relative_initial_step_size; + + // Maximal number of adaptive extrapolations (sampling) in Ridders' method. + int max_num_ridders_extrapolations; + + // Convergence criterion on extrapolation error for Ridders adaptive + // differentiation. The available error estimation methods are defined in + // NumericDiffErrorType and set in the "ridders_error_method" field. + double ridders_epsilon; + + // The factor in which to shrink the step size with each extrapolation in + // Ridders' method. + double ridders_step_shrink_factor; +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_NUMERIC_DIFF_OPTIONS_H_ diff --git a/include/ceres/ordered_groups.h b/include/ceres/ordered_groups.h new file mode 100644 index 0000000..aa1bd3a --- /dev/null +++ b/include/ceres/ordered_groups.h @@ -0,0 +1,208 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_ORDERED_GROUPS_H_ +#define CERES_PUBLIC_ORDERED_GROUPS_H_ + +#include +#include +#include +#include "ceres/internal/port.h" +#include "glog/logging.h" + +namespace ceres { + +// A class for storing and manipulating an ordered collection of +// groups/sets with the following semantics: +// +// Group ids are non-negative integer values. Elements are any type +// that can serve as a key in a map or an element of a set. +// +// An element can only belong to one group at a time. A group may +// contain an arbitrary number of elements. +// +// Groups are ordered by their group id. +template +class OrderedGroups { + public: + // Add an element to a group. If a group with this id does not + // exist, one is created. This method can be called any number of + // times for the same element. Group ids should be non-negative + // numbers. + // + // Return value indicates if adding the element was a success. + bool AddElementToGroup(const T element, const int group) { + if (group < 0) { + return false; + } + + typename std::map::const_iterator it = + element_to_group_.find(element); + if (it != element_to_group_.end()) { + if (it->second == group) { + // Element is already in the right group, nothing to do. + return true; + } + + group_to_elements_[it->second].erase(element); + if (group_to_elements_[it->second].size() == 0) { + group_to_elements_.erase(it->second); + } + } + + element_to_group_[element] = group; + group_to_elements_[group].insert(element); + return true; + } + + void Clear() { + group_to_elements_.clear(); + element_to_group_.clear(); + } + + // Remove the element, no matter what group it is in. Return value + // indicates if the element was actually removed. + bool Remove(const T element) { + const int current_group = GroupId(element); + if (current_group < 0) { + return false; + } + + group_to_elements_[current_group].erase(element); + + if (group_to_elements_[current_group].size() == 0) { + // If the group is empty, then get rid of it. + group_to_elements_.erase(current_group); + } + + element_to_group_.erase(element); + return true; + } + + // Bulk remove elements. The return value indicates the number of + // elements successfully removed. + int Remove(const std::vector& elements) { + if (NumElements() == 0 || elements.size() == 0) { + return 0; + } + + int num_removed = 0; + for (int i = 0; i < elements.size(); ++i) { + num_removed += Remove(elements[i]); + } + return num_removed; + } + + // Reverse the order of the groups in place. + void Reverse() { + if (NumGroups() == 0) { + return; + } + + typename std::map >::reverse_iterator it = + group_to_elements_.rbegin(); + std::map > new_group_to_elements; + new_group_to_elements[it->first] = it->second; + + int new_group_id = it->first + 1; + for (++it; it != group_to_elements_.rend(); ++it) { + for (typename std::set::const_iterator element_it = it->second.begin(); + element_it != it->second.end(); + ++element_it) { + element_to_group_[*element_it] = new_group_id; + } + new_group_to_elements[new_group_id] = it->second; + new_group_id++; + } + + group_to_elements_.swap(new_group_to_elements); + } + + // Return the group id for the element. If the element is not a + // member of any group, return -1. + int GroupId(const T element) const { + typename std::map::const_iterator it = + element_to_group_.find(element); + if (it == element_to_group_.end()) { + return -1; + } + return it->second; + } + + bool IsMember(const T element) const { + typename std::map::const_iterator it = + element_to_group_.find(element); + return (it != element_to_group_.end()); + } + + // This function always succeeds, i.e., implicitly there exists a + // group for every integer. + int GroupSize(const int group) const { + typename std::map >::const_iterator it = + group_to_elements_.find(group); + return (it == group_to_elements_.end()) ? 0 : it->second.size(); + } + + int NumElements() const { + return element_to_group_.size(); + } + + // Number of groups with one or more elements. + int NumGroups() const { + return group_to_elements_.size(); + } + + // The first group with one or more elements. Calling this when + // there are no groups with non-zero elements will result in a + // crash. + int MinNonZeroGroup() const { + CHECK_NE(NumGroups(), 0); + return group_to_elements_.begin()->first; + } + + const std::map >& group_to_elements() const { + return group_to_elements_; + } + + const std::map& element_to_group() const { + return element_to_group_; + } + + private: + std::map > group_to_elements_; + std::map element_to_group_; +}; + +// Typedef for the most commonly used version of OrderedGroups. +typedef OrderedGroups ParameterBlockOrdering; + +} // namespace ceres + +#endif // CERES_PUBLIC_ORDERED_GROUP_H_ diff --git a/include/ceres/problem.h b/include/ceres/problem.h new file mode 100644 index 0000000..27ed4ef --- /dev/null +++ b/include/ceres/problem.h @@ -0,0 +1,488 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// keir@google.com (Keir Mierle) +// +// The Problem object is used to build and hold least squares problems. + +#ifndef CERES_PUBLIC_PROBLEM_H_ +#define CERES_PUBLIC_PROBLEM_H_ + +#include +#include +#include +#include + +#include "glog/logging.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + + +namespace ceres { + +class CostFunction; +class LossFunction; +class LocalParameterization; +class Solver; +struct CRSMatrix; + +namespace internal { +class Preprocessor; +class ProblemImpl; +class ParameterBlock; +class ResidualBlock; +} // namespace internal + +// A ResidualBlockId is an opaque handle clients can use to remove residual +// blocks from a Problem after adding them. +typedef internal::ResidualBlock* ResidualBlockId; + +// A class to represent non-linear least squares problems. Such +// problems have a cost function that is a sum of error terms (known +// as "residuals"), where each residual is a function of some subset +// of the parameters. The cost function takes the form +// +// N 1 +// SUM --- loss( || r_i1, r_i2,..., r_ik ||^2 ), +// i=1 2 +// +// where +// +// r_ij is residual number i, component j; the residual is a +// function of some subset of the parameters x1...xk. For +// example, in a structure from motion problem a residual +// might be the difference between a measured point in an +// image and the reprojected position for the matching +// camera, point pair. The residual would have two +// components, error in x and error in y. +// +// loss(y) is the loss function; for example, squared error or +// Huber L1 loss. If loss(y) = y, then the cost function is +// non-robustified least squares. +// +// This class is specifically designed to address the important subset +// of "sparse" least squares problems, where each component of the +// residual depends only on a small number number of parameters, even +// though the total number of residuals and parameters may be very +// large. This property affords tremendous gains in scale, allowing +// efficient solving of large problems that are otherwise +// inaccessible. +// +// The canonical example of a sparse least squares problem is +// "structure-from-motion" (SFM), where the parameters are points and +// cameras, and residuals are reprojection errors. Typically a single +// residual will depend only on 9 parameters (3 for the point, 6 for +// the camera). +// +// To create a least squares problem, use the AddResidualBlock() and +// AddParameterBlock() methods, documented below. Here is an example least +// squares problem containing 3 parameter blocks of sizes 3, 4 and 5 +// respectively and two residual terms of size 2 and 6: +// +// double x1[] = { 1.0, 2.0, 3.0 }; +// double x2[] = { 1.0, 2.0, 3.0, 5.0 }; +// double x3[] = { 1.0, 2.0, 3.0, 6.0, 7.0 }; +// +// Problem problem; +// +// problem.AddResidualBlock(new MyUnaryCostFunction(...), x1); +// problem.AddResidualBlock(new MyBinaryCostFunction(...), x2, x3); +// +// Please see cost_function.h for details of the CostFunction object. +class CERES_EXPORT Problem { + public: + struct CERES_EXPORT Options { + Options() + : cost_function_ownership(TAKE_OWNERSHIP), + loss_function_ownership(TAKE_OWNERSHIP), + local_parameterization_ownership(TAKE_OWNERSHIP), + enable_fast_removal(false), + disable_all_safety_checks(false) {} + + // These flags control whether the Problem object owns the cost + // functions, loss functions, and parameterizations passed into + // the Problem. If set to TAKE_OWNERSHIP, then the problem object + // will delete the corresponding cost or loss functions on + // destruction. The destructor is careful to delete the pointers + // only once, since sharing cost/loss/parameterizations is + // allowed. + Ownership cost_function_ownership; + Ownership loss_function_ownership; + Ownership local_parameterization_ownership; + + // If true, trades memory for faster RemoveResidualBlock() and + // RemoveParameterBlock() operations. + // + // By default, RemoveParameterBlock() and RemoveResidualBlock() take time + // proportional to the size of the entire problem. If you only ever remove + // parameters or residuals from the problem occassionally, this might be + // acceptable. However, if you have memory to spare, enable this option to + // make RemoveParameterBlock() take time proportional to the number of + // residual blocks that depend on it, and RemoveResidualBlock() take (on + // average) constant time. + // + // The increase in memory usage is twofold: an additonal hash set per + // parameter block containing all the residuals that depend on the parameter + // block; and a hash set in the problem containing all residuals. + bool enable_fast_removal; + + // By default, Ceres performs a variety of safety checks when constructing + // the problem. There is a small but measurable performance penalty to + // these checks, typically around 5% of construction time. If you are sure + // your problem construction is correct, and 5% of the problem construction + // time is truly an overhead you want to avoid, then you can set + // disable_all_safety_checks to true. + // + // WARNING: Do not set this to true, unless you are absolutely sure of what + // you are doing. + bool disable_all_safety_checks; + }; + + // The default constructor is equivalent to the + // invocation Problem(Problem::Options()). + Problem(); + explicit Problem(const Options& options); + + ~Problem(); + + // Add a residual block to the overall cost function. The cost + // function carries with it information about the sizes of the + // parameter blocks it expects. The function checks that these match + // the sizes of the parameter blocks listed in parameter_blocks. The + // program aborts if a mismatch is detected. loss_function can be + // NULL, in which case the cost of the term is just the squared norm + // of the residuals. + // + // The user has the option of explicitly adding the parameter blocks + // using AddParameterBlock. This causes additional correctness + // checking; however, AddResidualBlock implicitly adds the parameter + // blocks if they are not present, so calling AddParameterBlock + // explicitly is not required. + // + // The Problem object by default takes ownership of the + // cost_function and loss_function pointers. These objects remain + // live for the life of the Problem object. If the user wishes to + // keep control over the destruction of these objects, then they can + // do this by setting the corresponding enums in the Options struct. + // + // Note: Even though the Problem takes ownership of cost_function + // and loss_function, it does not preclude the user from re-using + // them in another residual block. The destructor takes care to call + // delete on each cost_function or loss_function pointer only once, + // regardless of how many residual blocks refer to them. + // + // Example usage: + // + // double x1[] = {1.0, 2.0, 3.0}; + // double x2[] = {1.0, 2.0, 5.0, 6.0}; + // double x3[] = {3.0, 6.0, 2.0, 5.0, 1.0}; + // + // Problem problem; + // + // problem.AddResidualBlock(new MyUnaryCostFunction(...), NULL, x1); + // problem.AddResidualBlock(new MyBinaryCostFunction(...), NULL, x2, x1); + // + ResidualBlockId AddResidualBlock( + CostFunction* cost_function, + LossFunction* loss_function, + const std::vector& parameter_blocks); + + // Convenience methods for adding residuals with a small number of + // parameters. This is the common case. Instead of specifying the + // parameter block arguments as a vector, list them as pointers. + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4, double* x5); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4, double* x5, + double* x6); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4, double* x5, + double* x6, double* x7); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4, double* x5, + double* x6, double* x7, double* x8); + ResidualBlockId AddResidualBlock(CostFunction* cost_function, + LossFunction* loss_function, + double* x0, double* x1, double* x2, + double* x3, double* x4, double* x5, + double* x6, double* x7, double* x8, + double* x9); + + // Add a parameter block with appropriate size to the problem. + // Repeated calls with the same arguments are ignored. Repeated + // calls with the same double pointer but a different size results + // in undefined behaviour. + void AddParameterBlock(double* values, int size); + + // Add a parameter block with appropriate size and parameterization + // to the problem. Repeated calls with the same arguments are + // ignored. Repeated calls with the same double pointer but a + // different size results in undefined behaviour. + void AddParameterBlock(double* values, + int size, + LocalParameterization* local_parameterization); + + // Remove a parameter block from the problem. The parameterization of the + // parameter block, if it exists, will persist until the deletion of the + // problem (similar to cost/loss functions in residual block removal). Any + // residual blocks that depend on the parameter are also removed, as + // described above in RemoveResidualBlock(). + // + // If Problem::Options::enable_fast_removal is true, then the + // removal is fast (almost constant time). Otherwise, removing a parameter + // block will incur a scan of the entire Problem object. + // + // WARNING: Removing a residual or parameter block will destroy the implicit + // ordering, rendering the jacobian or residuals returned from the solver + // uninterpretable. If you depend on the evaluated jacobian, do not use + // remove! This may change in a future release. + void RemoveParameterBlock(double* values); + + // Remove a residual block from the problem. Any parameters that the residual + // block depends on are not removed. The cost and loss functions for the + // residual block will not get deleted immediately; won't happen until the + // problem itself is deleted. + // + // WARNING: Removing a residual or parameter block will destroy the implicit + // ordering, rendering the jacobian or residuals returned from the solver + // uninterpretable. If you depend on the evaluated jacobian, do not use + // remove! This may change in a future release. + void RemoveResidualBlock(ResidualBlockId residual_block); + + // Hold the indicated parameter block constant during optimization. + void SetParameterBlockConstant(double* values); + + // Allow the indicated parameter block to vary during optimization. + void SetParameterBlockVariable(double* values); + + // Returns true if a parameter block is set constant, and false otherwise. + bool IsParameterBlockConstant(double* values) const; + + // Set the local parameterization for one of the parameter blocks. + // The local_parameterization is owned by the Problem by default. It + // is acceptable to set the same parameterization for multiple + // parameters; the destructor is careful to delete local + // parameterizations only once. The local parameterization can only + // be set once per parameter, and cannot be changed once set. + void SetParameterization(double* values, + LocalParameterization* local_parameterization); + + // Get the local parameterization object associated with this + // parameter block. If there is no parameterization object + // associated then NULL is returned. + const LocalParameterization* GetParameterization(double* values) const; + + // Set the lower/upper bound for the parameter with position "index". + void SetParameterLowerBound(double* values, int index, double lower_bound); + void SetParameterUpperBound(double* values, int index, double upper_bound); + + // Number of parameter blocks in the problem. Always equals + // parameter_blocks().size() and parameter_block_sizes().size(). + int NumParameterBlocks() const; + + // The size of the parameter vector obtained by summing over the + // sizes of all the parameter blocks. + int NumParameters() const; + + // Number of residual blocks in the problem. Always equals + // residual_blocks().size(). + int NumResidualBlocks() const; + + // The size of the residual vector obtained by summing over the + // sizes of all of the residual blocks. + int NumResiduals() const; + + // The size of the parameter block. + int ParameterBlockSize(const double* values) const; + + // The size of local parameterization for the parameter block. If + // there is no local parameterization associated with this parameter + // block, then ParameterBlockLocalSize = ParameterBlockSize. + int ParameterBlockLocalSize(const double* values) const; + + // Is the given parameter block present in this problem or not? + bool HasParameterBlock(const double* values) const; + + // Fills the passed parameter_blocks vector with pointers to the + // parameter blocks currently in the problem. After this call, + // parameter_block.size() == NumParameterBlocks. + void GetParameterBlocks(std::vector* parameter_blocks) const; + + // Fills the passed residual_blocks vector with pointers to the + // residual blocks currently in the problem. After this call, + // residual_blocks.size() == NumResidualBlocks. + void GetResidualBlocks(std::vector* residual_blocks) const; + + // Get all the parameter blocks that depend on the given residual block. + void GetParameterBlocksForResidualBlock( + const ResidualBlockId residual_block, + std::vector* parameter_blocks) const; + + // Get the CostFunction for the given residual block. + const CostFunction* GetCostFunctionForResidualBlock( + const ResidualBlockId residual_block) const; + + // Get the LossFunction for the given residual block. Returns NULL + // if no loss function is associated with this residual block. + const LossFunction* GetLossFunctionForResidualBlock( + const ResidualBlockId residual_block) const; + + // Get all the residual blocks that depend on the given parameter block. + // + // If Problem::Options::enable_fast_removal is true, then + // getting the residual blocks is fast and depends only on the number of + // residual blocks. Otherwise, getting the residual blocks for a parameter + // block will incur a scan of the entire Problem object. + void GetResidualBlocksForParameterBlock( + const double* values, + std::vector* residual_blocks) const; + + // Options struct to control Problem::Evaluate. + struct EvaluateOptions { + EvaluateOptions() + : apply_loss_function(true), + num_threads(1) { + } + + // The set of parameter blocks for which evaluation should be + // performed. This vector determines the order that parameter + // blocks occur in the gradient vector and in the columns of the + // jacobian matrix. If parameter_blocks is empty, then it is + // assumed to be equal to vector containing ALL the parameter + // blocks. Generally speaking the parameter blocks will occur in + // the order in which they were added to the problem. But, this + // may change if the user removes any parameter blocks from the + // problem. + // + // NOTE: This vector should contain the same pointers as the ones + // used to add parameter blocks to the Problem. These parameter + // block should NOT point to new memory locations. Bad things will + // happen otherwise. + std::vector parameter_blocks; + + // The set of residual blocks to evaluate. This vector determines + // the order in which the residuals occur, and how the rows of the + // jacobian are ordered. If residual_blocks is empty, then it is + // assumed to be equal to the vector containing ALL the residual + // blocks. Generally speaking the residual blocks will occur in + // the order in which they were added to the problem. But, this + // may change if the user removes any residual blocks from the + // problem. + std::vector residual_blocks; + + // Even though the residual blocks in the problem may contain loss + // functions, setting apply_loss_function to false will turn off + // the application of the loss function to the output of the cost + // function. This is of use for example if the user wishes to + // analyse the solution quality by studying the distribution of + // residuals before and after the solve. + bool apply_loss_function; + + int num_threads; + }; + + // Evaluate Problem. Any of the output pointers can be NULL. Which + // residual blocks and parameter blocks are used is controlled by + // the EvaluateOptions struct above. + // + // Note 1: The evaluation will use the values stored in the memory + // locations pointed to by the parameter block pointers used at the + // time of the construction of the problem. i.e., + // + // Problem problem; + // double x = 1; + // problem.AddResidualBlock(new MyCostFunction, NULL, &x); + // + // double cost = 0.0; + // problem.Evaluate(Problem::EvaluateOptions(), &cost, NULL, NULL, NULL); + // + // The cost is evaluated at x = 1. If you wish to evaluate the + // problem at x = 2, then + // + // x = 2; + // problem.Evaluate(Problem::EvaluateOptions(), &cost, NULL, NULL, NULL); + // + // is the way to do so. + // + // Note 2: If no local parameterizations are used, then the size of + // the gradient vector (and the number of columns in the jacobian) + // is the sum of the sizes of all the parameter blocks. If a + // parameter block has a local parameterization, then it contributes + // "LocalSize" entries to the gradient vector (and the number of + // columns in the jacobian). + // + // Note 3: This function cannot be called while the problem is being + // solved, for example it cannot be called from an IterationCallback + // at the end of an iteration during a solve. + bool Evaluate(const EvaluateOptions& options, + double* cost, + std::vector* residuals, + std::vector* gradient, + CRSMatrix* jacobian); + + private: + friend class Solver; + friend class Covariance; + internal::scoped_ptr problem_impl_; + CERES_DISALLOW_COPY_AND_ASSIGN(Problem); +}; + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_PROBLEM_H_ diff --git a/include/ceres/rotation.h b/include/ceres/rotation.h new file mode 100644 index 0000000..d05d190 --- /dev/null +++ b/include/ceres/rotation.h @@ -0,0 +1,626 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) +// +// Templated functions for manipulating rotations. The templated +// functions are useful when implementing functors for automatic +// differentiation. +// +// In the following, the Quaternions are laid out as 4-vectors, thus: +// +// q[0] scalar part. +// q[1] coefficient of i. +// q[2] coefficient of j. +// q[3] coefficient of k. +// +// where: i*i = j*j = k*k = -1 and i*j = k, j*k = i, k*i = j. + +#ifndef CERES_PUBLIC_ROTATION_H_ +#define CERES_PUBLIC_ROTATION_H_ + +#include +#include +#include + +namespace ceres { + +// Trivial wrapper to index linear arrays as matrices, given a fixed +// column and row stride. When an array "T* array" is wrapped by a +// +// (const) MatrixAdapter M" +// +// the expression M(i, j) is equivalent to +// +// arrary[i * row_stride + j * col_stride] +// +// Conversion functions to and from rotation matrices accept +// MatrixAdapters to permit using row-major and column-major layouts, +// and rotation matrices embedded in larger matrices (such as a 3x4 +// projection matrix). +template +struct MatrixAdapter; + +// Convenience functions to create a MatrixAdapter that treats the +// array pointed to by "pointer" as a 3x3 (contiguous) column-major or +// row-major matrix. +template +MatrixAdapter ColumnMajorAdapter3x3(T* pointer); + +template +MatrixAdapter RowMajorAdapter3x3(T* pointer); + +// Convert a value in combined axis-angle representation to a quaternion. +// The value angle_axis is a triple whose norm is an angle in radians, +// and whose direction is aligned with the axis of rotation, +// and quaternion is a 4-tuple that will contain the resulting quaternion. +// The implementation may be used with auto-differentiation up to the first +// derivative, higher derivatives may have unexpected results near the origin. +template +void AngleAxisToQuaternion(const T* angle_axis, T* quaternion); + +// Convert a quaternion to the equivalent combined axis-angle representation. +// The value quaternion must be a unit quaternion - it is not normalized first, +// and angle_axis will be filled with a value whose norm is the angle of +// rotation in radians, and whose direction is the axis of rotation. +// The implemention may be used with auto-differentiation up to the first +// derivative, higher derivatives may have unexpected results near the origin. +template +void QuaternionToAngleAxis(const T* quaternion, T* angle_axis); + +// Conversions between 3x3 rotation matrix (in column major order) and +// quaternion rotation representations. Templated for use with +// autodifferentiation. +template +void RotationMatrixToQuaternion(const T* R, T* quaternion); + +template +void RotationMatrixToQuaternion( + const MatrixAdapter& R, + T* quaternion); + +// Conversions between 3x3 rotation matrix (in column major order) and +// axis-angle rotation representations. Templated for use with +// autodifferentiation. +template +void RotationMatrixToAngleAxis(const T* R, T* angle_axis); + +template +void RotationMatrixToAngleAxis( + const MatrixAdapter& R, + T* angle_axis); + +template +void AngleAxisToRotationMatrix(const T* angle_axis, T* R); + +template +void AngleAxisToRotationMatrix( + const T* angle_axis, + const MatrixAdapter& R); + +// Conversions between 3x3 rotation matrix (in row major order) and +// Euler angle (in degrees) rotation representations. +// +// The {pitch,roll,yaw} Euler angles are rotations around the {x,y,z} +// axes, respectively. They are applied in that same order, so the +// total rotation R is Rz * Ry * Rx. +template +void EulerAnglesToRotationMatrix(const T* euler, int row_stride, T* R); + +template +void EulerAnglesToRotationMatrix( + const T* euler, + const MatrixAdapter& R); + +// Convert a 4-vector to a 3x3 scaled rotation matrix. +// +// The choice of rotation is such that the quaternion [1 0 0 0] goes to an +// identity matrix and for small a, b, c the quaternion [1 a b c] goes to +// the matrix +// +// [ 0 -c b ] +// I + 2 [ c 0 -a ] + higher order terms +// [ -b a 0 ] +// +// which corresponds to a Rodrigues approximation, the last matrix being +// the cross-product matrix of [a b c]. Together with the property that +// R(q1 * q2) = R(q1) * R(q2) this uniquely defines the mapping from q to R. +// +// No normalization of the quaternion is performed, i.e. +// R = ||q||^2 * Q, where Q is an orthonormal matrix +// such that det(Q) = 1 and Q*Q' = I +// +// WARNING: The rotation matrix is ROW MAJOR +template inline +void QuaternionToScaledRotation(const T q[4], T R[3 * 3]); + +template inline +void QuaternionToScaledRotation( + const T q[4], + const MatrixAdapter& R); + +// Same as above except that the rotation matrix is normalized by the +// Frobenius norm, so that R * R' = I (and det(R) = 1). +// +// WARNING: The rotation matrix is ROW MAJOR +template inline +void QuaternionToRotation(const T q[4], T R[3 * 3]); + +template inline +void QuaternionToRotation( + const T q[4], + const MatrixAdapter& R); + +// Rotates a point pt by a quaternion q: +// +// result = R(q) * pt +// +// Assumes the quaternion is unit norm. This assumption allows us to +// write the transform as (something)*pt + pt, as is clear from the +// formula below. If you pass in a quaternion with |q|^2 = 2 then you +// WILL NOT get back 2 times the result you get for a unit quaternion. +template inline +void UnitQuaternionRotatePoint(const T q[4], const T pt[3], T result[3]); + +// With this function you do not need to assume that q has unit norm. +// It does assume that the norm is non-zero. +template inline +void QuaternionRotatePoint(const T q[4], const T pt[3], T result[3]); + +// zw = z * w, where * is the Quaternion product between 4 vectors. +template inline +void QuaternionProduct(const T z[4], const T w[4], T zw[4]); + +// xy = x cross y; +template inline +void CrossProduct(const T x[3], const T y[3], T x_cross_y[3]); + +template inline +T DotProduct(const T x[3], const T y[3]); + +// y = R(angle_axis) * x; +template inline +void AngleAxisRotatePoint(const T angle_axis[3], const T pt[3], T result[3]); + +// --- IMPLEMENTATION + +template +struct MatrixAdapter { + T* pointer_; + explicit MatrixAdapter(T* pointer) + : pointer_(pointer) + {} + + T& operator()(int r, int c) const { + return pointer_[r * row_stride + c * col_stride]; + } +}; + +template +MatrixAdapter ColumnMajorAdapter3x3(T* pointer) { + return MatrixAdapter(pointer); +} + +template +MatrixAdapter RowMajorAdapter3x3(T* pointer) { + return MatrixAdapter(pointer); +} + +template +inline void AngleAxisToQuaternion(const T* angle_axis, T* quaternion) { + const T& a0 = angle_axis[0]; + const T& a1 = angle_axis[1]; + const T& a2 = angle_axis[2]; + const T theta_squared = a0 * a0 + a1 * a1 + a2 * a2; + + // For points not at the origin, the full conversion is numerically stable. + if (theta_squared > T(0.0)) { + const T theta = sqrt(theta_squared); + const T half_theta = theta * T(0.5); + const T k = sin(half_theta) / theta; + quaternion[0] = cos(half_theta); + quaternion[1] = a0 * k; + quaternion[2] = a1 * k; + quaternion[3] = a2 * k; + } else { + // At the origin, sqrt() will produce NaN in the derivative since + // the argument is zero. By approximating with a Taylor series, + // and truncating at one term, the value and first derivatives will be + // computed correctly when Jets are used. + const T k(0.5); + quaternion[0] = T(1.0); + quaternion[1] = a0 * k; + quaternion[2] = a1 * k; + quaternion[3] = a2 * k; + } +} + +template +inline void QuaternionToAngleAxis(const T* quaternion, T* angle_axis) { + const T& q1 = quaternion[1]; + const T& q2 = quaternion[2]; + const T& q3 = quaternion[3]; + const T sin_squared_theta = q1 * q1 + q2 * q2 + q3 * q3; + + // For quaternions representing non-zero rotation, the conversion + // is numerically stable. + if (sin_squared_theta > T(0.0)) { + const T sin_theta = sqrt(sin_squared_theta); + const T& cos_theta = quaternion[0]; + + // If cos_theta is negative, theta is greater than pi/2, which + // means that angle for the angle_axis vector which is 2 * theta + // would be greater than pi. + // + // While this will result in the correct rotation, it does not + // result in a normalized angle-axis vector. + // + // In that case we observe that 2 * theta ~ 2 * theta - 2 * pi, + // which is equivalent saying + // + // theta - pi = atan(sin(theta - pi), cos(theta - pi)) + // = atan(-sin(theta), -cos(theta)) + // + const T two_theta = + T(2.0) * ((cos_theta < 0.0) + ? atan2(-sin_theta, -cos_theta) + : atan2(sin_theta, cos_theta)); + const T k = two_theta / sin_theta; + angle_axis[0] = q1 * k; + angle_axis[1] = q2 * k; + angle_axis[2] = q3 * k; + } else { + // For zero rotation, sqrt() will produce NaN in the derivative since + // the argument is zero. By approximating with a Taylor series, + // and truncating at one term, the value and first derivatives will be + // computed correctly when Jets are used. + const T k(2.0); + angle_axis[0] = q1 * k; + angle_axis[1] = q2 * k; + angle_axis[2] = q3 * k; + } +} + +template +void RotationMatrixToQuaternion(const T* R, T* angle_axis) { + RotationMatrixToQuaternion(ColumnMajorAdapter3x3(R), angle_axis); +} + +// This algorithm comes from "Quaternion Calculus and Fast Animation", +// Ken Shoemake, 1987 SIGGRAPH course notes +template +void RotationMatrixToQuaternion( + const MatrixAdapter& R, + T* quaternion) { + const T trace = R(0, 0) + R(1, 1) + R(2, 2); + if (trace >= 0.0) { + T t = sqrt(trace + T(1.0)); + quaternion[0] = T(0.5) * t; + t = T(0.5) / t; + quaternion[1] = (R(2, 1) - R(1, 2)) * t; + quaternion[2] = (R(0, 2) - R(2, 0)) * t; + quaternion[3] = (R(1, 0) - R(0, 1)) * t; + } else { + int i = 0; + if (R(1, 1) > R(0, 0)) { + i = 1; + } + + if (R(2, 2) > R(i, i)) { + i = 2; + } + + const int j = (i + 1) % 3; + const int k = (j + 1) % 3; + T t = sqrt(R(i, i) - R(j, j) - R(k, k) + T(1.0)); + quaternion[i + 1] = T(0.5) * t; + t = T(0.5) / t; + quaternion[0] = (R(k, j) - R(j, k)) * t; + quaternion[j + 1] = (R(j, i) + R(i, j)) * t; + quaternion[k + 1] = (R(k, i) + R(i, k)) * t; + } +} + +// The conversion of a rotation matrix to the angle-axis form is +// numerically problematic when then rotation angle is close to zero +// or to Pi. The following implementation detects when these two cases +// occurs and deals with them by taking code paths that are guaranteed +// to not perform division by a small number. +template +inline void RotationMatrixToAngleAxis(const T* R, T* angle_axis) { + RotationMatrixToAngleAxis(ColumnMajorAdapter3x3(R), angle_axis); +} + +template +void RotationMatrixToAngleAxis( + const MatrixAdapter& R, + T* angle_axis) { + T quaternion[4]; + RotationMatrixToQuaternion(R, quaternion); + QuaternionToAngleAxis(quaternion, angle_axis); + return; +} + +template +inline void AngleAxisToRotationMatrix(const T* angle_axis, T* R) { + AngleAxisToRotationMatrix(angle_axis, ColumnMajorAdapter3x3(R)); +} + +template +void AngleAxisToRotationMatrix( + const T* angle_axis, + const MatrixAdapter& R) { + static const T kOne = T(1.0); + const T theta2 = DotProduct(angle_axis, angle_axis); + if (theta2 > T(std::numeric_limits::epsilon())) { + // We want to be careful to only evaluate the square root if the + // norm of the angle_axis vector is greater than zero. Otherwise + // we get a division by zero. + const T theta = sqrt(theta2); + const T wx = angle_axis[0] / theta; + const T wy = angle_axis[1] / theta; + const T wz = angle_axis[2] / theta; + + const T costheta = cos(theta); + const T sintheta = sin(theta); + + R(0, 0) = costheta + wx*wx*(kOne - costheta); + R(1, 0) = wz*sintheta + wx*wy*(kOne - costheta); + R(2, 0) = -wy*sintheta + wx*wz*(kOne - costheta); + R(0, 1) = wx*wy*(kOne - costheta) - wz*sintheta; + R(1, 1) = costheta + wy*wy*(kOne - costheta); + R(2, 1) = wx*sintheta + wy*wz*(kOne - costheta); + R(0, 2) = wy*sintheta + wx*wz*(kOne - costheta); + R(1, 2) = -wx*sintheta + wy*wz*(kOne - costheta); + R(2, 2) = costheta + wz*wz*(kOne - costheta); + } else { + // Near zero, we switch to using the first order Taylor expansion. + R(0, 0) = kOne; + R(1, 0) = angle_axis[2]; + R(2, 0) = -angle_axis[1]; + R(0, 1) = -angle_axis[2]; + R(1, 1) = kOne; + R(2, 1) = angle_axis[0]; + R(0, 2) = angle_axis[1]; + R(1, 2) = -angle_axis[0]; + R(2, 2) = kOne; + } +} + +template +inline void EulerAnglesToRotationMatrix(const T* euler, + const int row_stride_parameter, + T* R) { + EulerAnglesToRotationMatrix(euler, RowMajorAdapter3x3(R)); +} + +template +void EulerAnglesToRotationMatrix( + const T* euler, + const MatrixAdapter& R) { + const double kPi = 3.14159265358979323846; + const T degrees_to_radians(kPi / 180.0); + + const T pitch(euler[0] * degrees_to_radians); + const T roll(euler[1] * degrees_to_radians); + const T yaw(euler[2] * degrees_to_radians); + + const T c1 = cos(yaw); + const T s1 = sin(yaw); + const T c2 = cos(roll); + const T s2 = sin(roll); + const T c3 = cos(pitch); + const T s3 = sin(pitch); + + R(0, 0) = c1*c2; + R(0, 1) = -s1*c3 + c1*s2*s3; + R(0, 2) = s1*s3 + c1*s2*c3; + + R(1, 0) = s1*c2; + R(1, 1) = c1*c3 + s1*s2*s3; + R(1, 2) = -c1*s3 + s1*s2*c3; + + R(2, 0) = -s2; + R(2, 1) = c2*s3; + R(2, 2) = c2*c3; +} + +template inline +void QuaternionToScaledRotation(const T q[4], T R[3 * 3]) { + QuaternionToScaledRotation(q, RowMajorAdapter3x3(R)); +} + +template inline +void QuaternionToScaledRotation( + const T q[4], + const MatrixAdapter& R) { + // Make convenient names for elements of q. + T a = q[0]; + T b = q[1]; + T c = q[2]; + T d = q[3]; + // This is not to eliminate common sub-expression, but to + // make the lines shorter so that they fit in 80 columns! + T aa = a * a; + T ab = a * b; + T ac = a * c; + T ad = a * d; + T bb = b * b; + T bc = b * c; + T bd = b * d; + T cc = c * c; + T cd = c * d; + T dd = d * d; + + R(0, 0) = aa + bb - cc - dd; R(0, 1) = T(2) * (bc - ad); R(0, 2) = T(2) * (ac + bd); // NOLINT + R(1, 0) = T(2) * (ad + bc); R(1, 1) = aa - bb + cc - dd; R(1, 2) = T(2) * (cd - ab); // NOLINT + R(2, 0) = T(2) * (bd - ac); R(2, 1) = T(2) * (ab + cd); R(2, 2) = aa - bb - cc + dd; // NOLINT +} + +template inline +void QuaternionToRotation(const T q[4], T R[3 * 3]) { + QuaternionToRotation(q, RowMajorAdapter3x3(R)); +} + +template inline +void QuaternionToRotation(const T q[4], + const MatrixAdapter& R) { + QuaternionToScaledRotation(q, R); + + T normalizer = q[0]*q[0] + q[1]*q[1] + q[2]*q[2] + q[3]*q[3]; + normalizer = T(1) / normalizer; + + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < 3; ++j) { + R(i, j) *= normalizer; + } + } +} + +template inline +void UnitQuaternionRotatePoint(const T q[4], const T pt[3], T result[3]) { + const T t2 = q[0] * q[1]; + const T t3 = q[0] * q[2]; + const T t4 = q[0] * q[3]; + const T t5 = -q[1] * q[1]; + const T t6 = q[1] * q[2]; + const T t7 = q[1] * q[3]; + const T t8 = -q[2] * q[2]; + const T t9 = q[2] * q[3]; + const T t1 = -q[3] * q[3]; + result[0] = T(2) * ((t8 + t1) * pt[0] + (t6 - t4) * pt[1] + (t3 + t7) * pt[2]) + pt[0]; // NOLINT + result[1] = T(2) * ((t4 + t6) * pt[0] + (t5 + t1) * pt[1] + (t9 - t2) * pt[2]) + pt[1]; // NOLINT + result[2] = T(2) * ((t7 - t3) * pt[0] + (t2 + t9) * pt[1] + (t5 + t8) * pt[2]) + pt[2]; // NOLINT +} + +template inline +void QuaternionRotatePoint(const T q[4], const T pt[3], T result[3]) { + // 'scale' is 1 / norm(q). + const T scale = T(1) / sqrt(q[0] * q[0] + + q[1] * q[1] + + q[2] * q[2] + + q[3] * q[3]); + + // Make unit-norm version of q. + const T unit[4] = { + scale * q[0], + scale * q[1], + scale * q[2], + scale * q[3], + }; + + UnitQuaternionRotatePoint(unit, pt, result); +} + +template inline +void QuaternionProduct(const T z[4], const T w[4], T zw[4]) { + zw[0] = z[0] * w[0] - z[1] * w[1] - z[2] * w[2] - z[3] * w[3]; + zw[1] = z[0] * w[1] + z[1] * w[0] + z[2] * w[3] - z[3] * w[2]; + zw[2] = z[0] * w[2] - z[1] * w[3] + z[2] * w[0] + z[3] * w[1]; + zw[3] = z[0] * w[3] + z[1] * w[2] - z[2] * w[1] + z[3] * w[0]; +} + +// xy = x cross y; +template inline +void CrossProduct(const T x[3], const T y[3], T x_cross_y[3]) { + x_cross_y[0] = x[1] * y[2] - x[2] * y[1]; + x_cross_y[1] = x[2] * y[0] - x[0] * y[2]; + x_cross_y[2] = x[0] * y[1] - x[1] * y[0]; +} + +template inline +T DotProduct(const T x[3], const T y[3]) { + return (x[0] * y[0] + x[1] * y[1] + x[2] * y[2]); +} + +template inline +void AngleAxisRotatePoint(const T angle_axis[3], const T pt[3], T result[3]) { + const T theta2 = DotProduct(angle_axis, angle_axis); + if (theta2 > T(std::numeric_limits::epsilon())) { + // Away from zero, use the rodriguez formula + // + // result = pt costheta + + // (w x pt) * sintheta + + // w (w . pt) (1 - costheta) + // + // We want to be careful to only evaluate the square root if the + // norm of the angle_axis vector is greater than zero. Otherwise + // we get a division by zero. + // + const T theta = sqrt(theta2); + const T costheta = cos(theta); + const T sintheta = sin(theta); + const T theta_inverse = T(1.0) / theta; + + const T w[3] = { angle_axis[0] * theta_inverse, + angle_axis[1] * theta_inverse, + angle_axis[2] * theta_inverse }; + + // Explicitly inlined evaluation of the cross product for + // performance reasons. + const T w_cross_pt[3] = { w[1] * pt[2] - w[2] * pt[1], + w[2] * pt[0] - w[0] * pt[2], + w[0] * pt[1] - w[1] * pt[0] }; + const T tmp = + (w[0] * pt[0] + w[1] * pt[1] + w[2] * pt[2]) * (T(1.0) - costheta); + + result[0] = pt[0] * costheta + w_cross_pt[0] * sintheta + w[0] * tmp; + result[1] = pt[1] * costheta + w_cross_pt[1] * sintheta + w[1] * tmp; + result[2] = pt[2] * costheta + w_cross_pt[2] * sintheta + w[2] * tmp; + } else { + // Near zero, the first order Taylor approximation of the rotation + // matrix R corresponding to a vector w and angle w is + // + // R = I + hat(w) * sin(theta) + // + // But sintheta ~ theta and theta * w = angle_axis, which gives us + // + // R = I + hat(w) + // + // and actually performing multiplication with the point pt, gives us + // R * pt = pt + w x pt. + // + // Switching to the Taylor expansion near zero provides meaningful + // derivatives when evaluated using Jets. + // + // Explicitly inlined evaluation of the cross product for + // performance reasons. + const T w_cross_pt[3] = { angle_axis[1] * pt[2] - angle_axis[2] * pt[1], + angle_axis[2] * pt[0] - angle_axis[0] * pt[2], + angle_axis[0] * pt[1] - angle_axis[1] * pt[0] }; + + result[0] = pt[0] + w_cross_pt[0]; + result[1] = pt[1] + w_cross_pt[1]; + result[2] = pt[2] + w_cross_pt[2]; + } +} + +} // namespace ceres + +#endif // CERES_PUBLIC_ROTATION_H_ diff --git a/include/ceres/sized_cost_function.h b/include/ceres/sized_cost_function.h new file mode 100644 index 0000000..b10421e --- /dev/null +++ b/include/ceres/sized_cost_function.h @@ -0,0 +1,96 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A convenience class for cost functions which are statically sized. +// Compared to the dynamically-sized base class, this reduces boilerplate. +// +// The kNumResiduals template parameter can be a constant such as 2 or 5, or it +// can be ceres::DYNAMIC. If kNumResiduals is ceres::DYNAMIC, then subclasses +// are responsible for calling set_num_residuals() at runtime. + +#ifndef CERES_PUBLIC_SIZED_COST_FUNCTION_H_ +#define CERES_PUBLIC_SIZED_COST_FUNCTION_H_ + +#include "ceres/types.h" +#include "ceres/cost_function.h" +#include "glog/logging.h" + +namespace ceres { + +template +class SizedCostFunction : public CostFunction { + public: + SizedCostFunction() { + CHECK(kNumResiduals > 0 || kNumResiduals == DYNAMIC) + << "Cost functions must have at least one residual block."; + + // This block breaks the 80 column rule to keep it somewhat readable. + CHECK((!N1 && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && !N2 && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || + ((N1 > 0) && (N2 > 0) && !N3 && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && !N4 && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && !N5 && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && !N6 && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && !N7 && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && !N8 && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && !N9) || // NOLINT + ((N1 > 0) && (N2 > 0) && (N3 > 0) && (N4 > 0) && (N5 > 0) && (N6 > 0) && (N7 > 0) && (N8 > 0) && (N9 > 0))) // NOLINT + << "Zero block cannot precede a non-zero block. Block sizes are " + << "(ignore trailing 0s): " << N0 << ", " << N1 << ", " << N2 << ", " + << N3 << ", " << N4 << ", " << N5 << ", " << N6 << ", " << N7 << ", " + << N8 << ", " << N9; + + set_num_residuals(kNumResiduals); + +#define CERES_ADD_PARAMETER_BLOCK(N) \ + if (N) mutable_parameter_block_sizes()->push_back(N); + CERES_ADD_PARAMETER_BLOCK(N0); + CERES_ADD_PARAMETER_BLOCK(N1); + CERES_ADD_PARAMETER_BLOCK(N2); + CERES_ADD_PARAMETER_BLOCK(N3); + CERES_ADD_PARAMETER_BLOCK(N4); + CERES_ADD_PARAMETER_BLOCK(N5); + CERES_ADD_PARAMETER_BLOCK(N6); + CERES_ADD_PARAMETER_BLOCK(N7); + CERES_ADD_PARAMETER_BLOCK(N8); + CERES_ADD_PARAMETER_BLOCK(N9); +#undef CERES_ADD_PARAMETER_BLOCK + } + + virtual ~SizedCostFunction() { } + + // Subclasses must implement Evaluate(). +}; + +} // namespace ceres + +#endif // CERES_PUBLIC_SIZED_COST_FUNCTION_H_ diff --git a/include/ceres/solver.h b/include/ceres/solver.h new file mode 100644 index 0000000..96391ba --- /dev/null +++ b/include/ceres/solver.h @@ -0,0 +1,1059 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_PUBLIC_SOLVER_H_ +#define CERES_PUBLIC_SOLVER_H_ + +#include +#include +#include +#include "ceres/crs_matrix.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/iteration_callback.h" +#include "ceres/ordered_groups.h" +#include "ceres/types.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +class Problem; + +// Interface for non-linear least squares solvers. +class CERES_EXPORT Solver { + public: + virtual ~Solver(); + + // The options structure contains, not surprisingly, options that control how + // the solver operates. The defaults should be suitable for a wide range of + // problems; however, better performance is often obtainable with tweaking. + // + // The constants are defined inside types.h + struct CERES_EXPORT Options { + // Default constructor that sets up a generic sparse problem. + Options() { + minimizer_type = TRUST_REGION; + line_search_direction_type = LBFGS; + line_search_type = WOLFE; + nonlinear_conjugate_gradient_type = FLETCHER_REEVES; + max_lbfgs_rank = 20; + use_approximate_eigenvalue_bfgs_scaling = false; + line_search_interpolation_type = CUBIC; + min_line_search_step_size = 1e-9; + line_search_sufficient_function_decrease = 1e-4; + max_line_search_step_contraction = 1e-3; + min_line_search_step_contraction = 0.6; + max_num_line_search_step_size_iterations = 20; + max_num_line_search_direction_restarts = 5; + line_search_sufficient_curvature_decrease = 0.9; + max_line_search_step_expansion = 10.0; + trust_region_strategy_type = LEVENBERG_MARQUARDT; + dogleg_type = TRADITIONAL_DOGLEG; + use_nonmonotonic_steps = false; + max_consecutive_nonmonotonic_steps = 5; + max_num_iterations = 50; + max_solver_time_in_seconds = 1e9; + num_threads = 1; + initial_trust_region_radius = 1e4; + max_trust_region_radius = 1e16; + min_trust_region_radius = 1e-32; + min_relative_decrease = 1e-3; + min_lm_diagonal = 1e-6; + max_lm_diagonal = 1e32; + max_num_consecutive_invalid_steps = 5; + function_tolerance = 1e-6; + gradient_tolerance = 1e-10; + parameter_tolerance = 1e-8; + +#if defined(CERES_NO_SUITESPARSE) && defined(CERES_NO_CXSPARSE) && !defined(CERES_ENABLE_LGPL_CODE) // NOLINT + linear_solver_type = DENSE_QR; +#else + linear_solver_type = SPARSE_NORMAL_CHOLESKY; +#endif + + preconditioner_type = JACOBI; + visibility_clustering_type = CANONICAL_VIEWS; + dense_linear_algebra_library_type = EIGEN; + + // Choose a default sparse linear algebra library in the order: + // + // SUITE_SPARSE > CX_SPARSE > EIGEN_SPARSE > NO_SPARSE + sparse_linear_algebra_library_type = NO_SPARSE; +#if !defined(CERES_NO_SUITESPARSE) + sparse_linear_algebra_library_type = SUITE_SPARSE; +#else + #if !defined(CERES_NO_CXSPARSE) + sparse_linear_algebra_library_type = CX_SPARSE; + #else + #if defined(CERES_USE_EIGEN_SPARSE) + sparse_linear_algebra_library_type = EIGEN_SPARSE; + #endif + #endif +#endif + + num_linear_solver_threads = 1; + use_explicit_schur_complement = false; + use_postordering = false; + dynamic_sparsity = false; + min_linear_solver_iterations = 0; + max_linear_solver_iterations = 500; + eta = 1e-1; + jacobi_scaling = true; + use_inner_iterations = false; + inner_iteration_tolerance = 1e-3; + logging_type = PER_MINIMIZER_ITERATION; + minimizer_progress_to_stdout = false; + trust_region_problem_dump_directory = "/tmp"; + trust_region_problem_dump_format_type = TEXTFILE; + check_gradients = false; + gradient_check_relative_precision = 1e-8; + gradient_check_numeric_derivative_relative_step_size = 1e-6; + update_state_every_iteration = false; + } + + // Returns true if the options struct has a valid + // configuration. Returns false otherwise, and fills in *error + // with a message describing the problem. + bool IsValid(std::string* error) const; + + // Minimizer options ---------------------------------------- + + // Ceres supports the two major families of optimization strategies - + // Trust Region and Line Search. + // + // 1. The line search approach first finds a descent direction + // along which the objective function will be reduced and then + // computes a step size that decides how far should move along + // that direction. The descent direction can be computed by + // various methods, such as gradient descent, Newton's method and + // Quasi-Newton method. The step size can be determined either + // exactly or inexactly. + // + // 2. The trust region approach approximates the objective + // function using using a model function (often a quadratic) over + // a subset of the search space known as the trust region. If the + // model function succeeds in minimizing the true objective + // function the trust region is expanded; conversely, otherwise it + // is contracted and the model optimization problem is solved + // again. + // + // Trust region methods are in some sense dual to line search methods: + // trust region methods first choose a step size (the size of the + // trust region) and then a step direction while line search methods + // first choose a step direction and then a step size. + MinimizerType minimizer_type; + + LineSearchDirectionType line_search_direction_type; + LineSearchType line_search_type; + NonlinearConjugateGradientType nonlinear_conjugate_gradient_type; + + // The LBFGS hessian approximation is a low rank approximation to + // the inverse of the Hessian matrix. The rank of the + // approximation determines (linearly) the space and time + // complexity of using the approximation. Higher the rank, the + // better is the quality of the approximation. The increase in + // quality is however is bounded for a number of reasons. + // + // 1. The method only uses secant information and not actual + // derivatives. + // + // 2. The Hessian approximation is constrained to be positive + // definite. + // + // So increasing this rank to a large number will cost time and + // space complexity without the corresponding increase in solution + // quality. There are no hard and fast rules for choosing the + // maximum rank. The best choice usually requires some problem + // specific experimentation. + // + // For more theoretical and implementation details of the LBFGS + // method, please see: + // + // Nocedal, J. (1980). "Updating Quasi-Newton Matrices with + // Limited Storage". Mathematics of Computation 35 (151): 773–782. + int max_lbfgs_rank; + + // As part of the (L)BFGS update step (BFGS) / right-multiply step (L-BFGS), + // the initial inverse Hessian approximation is taken to be the Identity. + // However, Oren showed that using instead I * \gamma, where \gamma is + // chosen to approximate an eigenvalue of the true inverse Hessian can + // result in improved convergence in a wide variety of cases. Setting + // use_approximate_eigenvalue_bfgs_scaling to true enables this scaling. + // + // It is important to note that approximate eigenvalue scaling does not + // always improve convergence, and that it can in fact significantly degrade + // performance for certain classes of problem, which is why it is disabled + // by default. In particular it can degrade performance when the + // sensitivity of the problem to different parameters varies significantly, + // as in this case a single scalar factor fails to capture this variation + // and detrimentally downscales parts of the jacobian approximation which + // correspond to low-sensitivity parameters. It can also reduce the + // robustness of the solution to errors in the jacobians. + // + // Oren S.S., Self-scaling variable metric (SSVM) algorithms + // Part II: Implementation and experiments, Management Science, + // 20(5), 863-874, 1974. + bool use_approximate_eigenvalue_bfgs_scaling; + + // Degree of the polynomial used to approximate the objective + // function. Valid values are BISECTION, QUADRATIC and CUBIC. + // + // BISECTION corresponds to pure backtracking search with no + // interpolation. + LineSearchInterpolationType line_search_interpolation_type; + + // If during the line search, the step_size falls below this + // value, it is truncated to zero. + double min_line_search_step_size; + + // Line search parameters. + + // Solving the line search problem exactly is computationally + // prohibitive. Fortunately, line search based optimization + // algorithms can still guarantee convergence if instead of an + // exact solution, the line search algorithm returns a solution + // which decreases the value of the objective function + // sufficiently. More precisely, we are looking for a step_size + // s.t. + // + // f(step_size) <= f(0) + sufficient_decrease * f'(0) * step_size + // + double line_search_sufficient_function_decrease; + + // In each iteration of the line search, + // + // new_step_size >= max_line_search_step_contraction * step_size + // + // Note that by definition, for contraction: + // + // 0 < max_step_contraction < min_step_contraction < 1 + // + double max_line_search_step_contraction; + + // In each iteration of the line search, + // + // new_step_size <= min_line_search_step_contraction * step_size + // + // Note that by definition, for contraction: + // + // 0 < max_step_contraction < min_step_contraction < 1 + // + double min_line_search_step_contraction; + + // Maximum number of trial step size iterations during each line search, + // if a step size satisfying the search conditions cannot be found within + // this number of trials, the line search will terminate. + int max_num_line_search_step_size_iterations; + + // Maximum number of restarts of the line search direction algorithm before + // terminating the optimization. Restarts of the line search direction + // algorithm occur when the current algorithm fails to produce a new descent + // direction. This typically indicates a numerical failure, or a breakdown + // in the validity of the approximations used. + int max_num_line_search_direction_restarts; + + // The strong Wolfe conditions consist of the Armijo sufficient + // decrease condition, and an additional requirement that the + // step-size be chosen s.t. the _magnitude_ ('strong' Wolfe + // conditions) of the gradient along the search direction + // decreases sufficiently. Precisely, this second condition + // is that we seek a step_size s.t. + // + // |f'(step_size)| <= sufficient_curvature_decrease * |f'(0)| + // + // Where f() is the line search objective and f'() is the derivative + // of f w.r.t step_size (d f / d step_size). + double line_search_sufficient_curvature_decrease; + + // During the bracketing phase of the Wolfe search, the step size is + // increased until either a point satisfying the Wolfe conditions is + // found, or an upper bound for a bracket containing a point satisfying + // the conditions is found. Precisely, at each iteration of the + // expansion: + // + // new_step_size <= max_step_expansion * step_size. + // + // By definition for expansion, max_step_expansion > 1.0. + double max_line_search_step_expansion; + + TrustRegionStrategyType trust_region_strategy_type; + + // Type of dogleg strategy to use. + DoglegType dogleg_type; + + // The classical trust region methods are descent methods, in that + // they only accept a point if it strictly reduces the value of + // the objective function. + // + // Relaxing this requirement allows the algorithm to be more + // efficient in the long term at the cost of some local increase + // in the value of the objective function. + // + // This is because allowing for non-decreasing objective function + // values in a princpled manner allows the algorithm to "jump over + // boulders" as the method is not restricted to move into narrow + // valleys while preserving its convergence properties. + // + // Setting use_nonmonotonic_steps to true enables the + // non-monotonic trust region algorithm as described by Conn, + // Gould & Toint in "Trust Region Methods", Section 10.1. + // + // The parameter max_consecutive_nonmonotonic_steps controls the + // window size used by the step selection algorithm to accept + // non-monotonic steps. + // + // Even though the value of the objective function may be larger + // than the minimum value encountered over the course of the + // optimization, the final parameters returned to the user are the + // ones corresponding to the minimum cost over all iterations. + bool use_nonmonotonic_steps; + int max_consecutive_nonmonotonic_steps; + + // Maximum number of iterations for the minimizer to run for. + int max_num_iterations; + + // Maximum time for which the minimizer should run for. + double max_solver_time_in_seconds; + + // Number of threads used by Ceres for evaluating the cost and + // jacobians. + int num_threads; + + // Trust region minimizer settings. + double initial_trust_region_radius; + double max_trust_region_radius; + + // Minimizer terminates when the trust region radius becomes + // smaller than this value. + double min_trust_region_radius; + + // Lower bound for the relative decrease before a step is + // accepted. + double min_relative_decrease; + + // For the Levenberg-Marquadt algorithm, the scaled diagonal of + // the normal equations J'J is used to control the size of the + // trust region. Extremely small and large values along the + // diagonal can make this regularization scheme + // fail. max_lm_diagonal and min_lm_diagonal, clamp the values of + // diag(J'J) from above and below. In the normal course of + // operation, the user should not have to modify these parameters. + double min_lm_diagonal; + double max_lm_diagonal; + + // Sometimes due to numerical conditioning problems or linear + // solver flakiness, the trust region strategy may return a + // numerically invalid step that can be fixed by reducing the + // trust region size. So the TrustRegionMinimizer allows for a few + // successive invalid steps before it declares NUMERICAL_FAILURE. + int max_num_consecutive_invalid_steps; + + // Minimizer terminates when + // + // (new_cost - old_cost) < function_tolerance * old_cost; + // + double function_tolerance; + + // Minimizer terminates when + // + // max_i |x - Project(Plus(x, -g(x))| < gradient_tolerance + // + // This value should typically be 1e-4 * function_tolerance. + double gradient_tolerance; + + // Minimizer terminates when + // + // |step|_2 <= parameter_tolerance * ( |x|_2 + parameter_tolerance) + // + double parameter_tolerance; + + // Linear least squares solver options ------------------------------------- + + LinearSolverType linear_solver_type; + + // Type of preconditioner to use with the iterative linear solvers. + PreconditionerType preconditioner_type; + + // Type of clustering algorithm to use for visibility based + // preconditioning. This option is used only when the + // preconditioner_type is CLUSTER_JACOBI or CLUSTER_TRIDIAGONAL. + VisibilityClusteringType visibility_clustering_type; + + // Ceres supports using multiple dense linear algebra libraries + // for dense matrix factorizations. Currently EIGEN and LAPACK are + // the valid choices. EIGEN is always available, LAPACK refers to + // the system BLAS + LAPACK library which may or may not be + // available. + // + // This setting affects the DENSE_QR, DENSE_NORMAL_CHOLESKY and + // DENSE_SCHUR solvers. For small to moderate sized probem EIGEN + // is a fine choice but for large problems, an optimized LAPACK + + // BLAS implementation can make a substantial difference in + // performance. + DenseLinearAlgebraLibraryType dense_linear_algebra_library_type; + + // Ceres supports using multiple sparse linear algebra libraries + // for sparse matrix ordering and factorizations. Currently, + // SUITE_SPARSE and CX_SPARSE are the valid choices, depending on + // whether they are linked into Ceres at build time. + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; + + // Number of threads used by Ceres to solve the Newton + // step. Currently only the SPARSE_SCHUR solver is capable of + // using this setting. + int num_linear_solver_threads; + + // The order in which variables are eliminated in a linear solver + // can have a significant of impact on the efficiency and accuracy + // of the method. e.g., when doing sparse Cholesky factorization, + // there are matrices for which a good ordering will give a + // Cholesky factor with O(n) storage, where as a bad ordering will + // result in an completely dense factor. + // + // Ceres allows the user to provide varying amounts of hints to + // the solver about the variable elimination ordering to use. This + // can range from no hints, where the solver is free to decide the + // best possible ordering based on the user's choices like the + // linear solver being used, to an exact order in which the + // variables should be eliminated, and a variety of possibilities + // in between. + // + // Instances of the ParameterBlockOrdering class are used to + // communicate this information to Ceres. + // + // Formally an ordering is an ordered partitioning of the + // parameter blocks, i.e, each parameter block belongs to exactly + // one group, and each group has a unique non-negative integer + // associated with it, that determines its order in the set of + // groups. + // + // Given such an ordering, Ceres ensures that the parameter blocks in + // the lowest numbered group are eliminated first, and then the + // parmeter blocks in the next lowest numbered group and so on. Within + // each group, Ceres is free to order the parameter blocks as it + // chooses. + // + // If NULL, then all parameter blocks are assumed to be in the + // same group and the solver is free to decide the best + // ordering. + // + // e.g. Consider the linear system + // + // x + y = 3 + // 2x + 3y = 7 + // + // There are two ways in which it can be solved. First eliminating x + // from the two equations, solving for y and then back substituting + // for x, or first eliminating y, solving for x and back substituting + // for y. The user can construct three orderings here. + // + // {0: x}, {1: y} - eliminate x first. + // {0: y}, {1: x} - eliminate y first. + // {0: x, y} - Solver gets to decide the elimination order. + // + // Thus, to have Ceres determine the ordering automatically using + // heuristics, put all the variables in group 0 and to control the + // ordering for every variable, create groups 0..N-1, one per + // variable, in the desired order. + // + // Bundle Adjustment + // ----------------- + // + // A particular case of interest is bundle adjustment, where the user + // has two options. The default is to not specify an ordering at all, + // the solver will see that the user wants to use a Schur type solver + // and figure out the right elimination ordering. + // + // But if the user already knows what parameter blocks are points and + // what are cameras, they can save preprocessing time by partitioning + // the parameter blocks into two groups, one for the points and one + // for the cameras, where the group containing the points has an id + // smaller than the group containing cameras. + shared_ptr linear_solver_ordering; + + // Use an explicitly computed Schur complement matrix with + // ITERATIVE_SCHUR. + // + // By default this option is disabled and ITERATIVE_SCHUR + // evaluates evaluates matrix-vector products between the Schur + // complement and a vector implicitly by exploiting the algebraic + // expression for the Schur complement. + // + // The cost of this evaluation scales with the number of non-zeros + // in the Jacobian. + // + // For small to medium sized problems there is a sweet spot where + // computing the Schur complement is cheap enough that it is much + // more efficient to explicitly compute it and use it for evaluating + // the matrix-vector products. + // + // Enabling this option tells ITERATIVE_SCHUR to use an explicitly + // computed Schur complement. + // + // NOTE: This option can only be used with the SCHUR_JACOBI + // preconditioner. + bool use_explicit_schur_complement; + + // Sparse Cholesky factorization algorithms use a fill-reducing + // ordering to permute the columns of the Jacobian matrix. There + // are two ways of doing this. + + // 1. Compute the Jacobian matrix in some order and then have the + // factorization algorithm permute the columns of the Jacobian. + + // 2. Compute the Jacobian with its columns already permuted. + + // The first option incurs a significant memory penalty. The + // factorization algorithm has to make a copy of the permuted + // Jacobian matrix, thus Ceres pre-permutes the columns of the + // Jacobian matrix and generally speaking, there is no performance + // penalty for doing so. + + // In some rare cases, it is worth using a more complicated + // reordering algorithm which has slightly better runtime + // performance at the expense of an extra copy of the Jacobian + // matrix. Setting use_postordering to true enables this tradeoff. + bool use_postordering; + + // Some non-linear least squares problems are symbolically dense but + // numerically sparse. i.e. at any given state only a small number + // of jacobian entries are non-zero, but the position and number of + // non-zeros is different depending on the state. For these problems + // it can be useful to factorize the sparse jacobian at each solver + // iteration instead of including all of the zero entries in a single + // general factorization. + // + // If your problem does not have this property (or you do not know), + // then it is probably best to keep this false, otherwise it will + // likely lead to worse performance. + + // This settings affects the SPARSE_NORMAL_CHOLESKY solver. + bool dynamic_sparsity; + + // Some non-linear least squares problems have additional + // structure in the way the parameter blocks interact that it is + // beneficial to modify the way the trust region step is computed. + // + // e.g., consider the following regression problem + // + // y = a_1 exp(b_1 x) + a_2 exp(b_3 x^2 + c_1) + // + // Given a set of pairs{(x_i, y_i)}, the user wishes to estimate + // a_1, a_2, b_1, b_2, and c_1. + // + // Notice here that the expression on the left is linear in a_1 + // and a_2, and given any value for b_1, b_2 and c_1, it is + // possible to use linear regression to estimate the optimal + // values of a_1 and a_2. Indeed, its possible to analytically + // eliminate the variables a_1 and a_2 from the problem all + // together. Problems like these are known as separable least + // squares problem and the most famous algorithm for solving them + // is the Variable Projection algorithm invented by Golub & + // Pereyra. + // + // Similar structure can be found in the matrix factorization with + // missing data problem. There the corresponding algorithm is + // known as Wiberg's algorithm. + // + // Ruhe & Wedin (Algorithms for Separable Nonlinear Least Squares + // Problems, SIAM Reviews, 22(3), 1980) present an analyis of + // various algorithms for solving separable non-linear least + // squares problems and refer to "Variable Projection" as + // Algorithm I in their paper. + // + // Implementing Variable Projection is tedious and expensive, and + // they present a simpler algorithm, which they refer to as + // Algorithm II, where once the Newton/Trust Region step has been + // computed for the whole problem (a_1, a_2, b_1, b_2, c_1) and + // additional optimization step is performed to estimate a_1 and + // a_2 exactly. + // + // This idea can be generalized to cases where the residual is not + // linear in a_1 and a_2, i.e., Solve for the trust region step + // for the full problem, and then use it as the starting point to + // further optimize just a_1 and a_2. For the linear case, this + // amounts to doing a single linear least squares solve. For + // non-linear problems, any method for solving the a_1 and a_2 + // optimization problems will do. The only constraint on a_1 and + // a_2 is that they do not co-occur in any residual block. + // + // This idea can be further generalized, by not just optimizing + // (a_1, a_2), but decomposing the graph corresponding to the + // Hessian matrix's sparsity structure in a collection of + // non-overlapping independent sets and optimizing each of them. + // + // Setting "use_inner_iterations" to true enables the use of this + // non-linear generalization of Ruhe & Wedin's Algorithm II. This + // version of Ceres has a higher iteration complexity, but also + // displays better convergence behaviour per iteration. Setting + // Solver::Options::num_threads to the maximum number possible is + // highly recommended. + bool use_inner_iterations; + + // If inner_iterations is true, then the user has two choices. + // + // 1. Let the solver heuristically decide which parameter blocks + // to optimize in each inner iteration. To do this leave + // Solver::Options::inner_iteration_ordering untouched. + // + // 2. Specify a collection of of ordered independent sets. Where + // the lower numbered groups are optimized before the higher + // number groups. Each group must be an independent set. Not + // all parameter blocks need to be present in the ordering. + shared_ptr inner_iteration_ordering; + + // Generally speaking, inner iterations make significant progress + // in the early stages of the solve and then their contribution + // drops down sharply, at which point the time spent doing inner + // iterations is not worth it. + // + // Once the relative decrease in the objective function due to + // inner iterations drops below inner_iteration_tolerance, the use + // of inner iterations in subsequent trust region minimizer + // iterations is disabled. + double inner_iteration_tolerance; + + // Minimum number of iterations for which the linear solver should + // run, even if the convergence criterion is satisfied. + int min_linear_solver_iterations; + + // Maximum number of iterations for which the linear solver should + // run. If the solver does not converge in less than + // max_linear_solver_iterations, then it returns MAX_ITERATIONS, + // as its termination type. + int max_linear_solver_iterations; + + // Forcing sequence parameter. The truncated Newton solver uses + // this number to control the relative accuracy with which the + // Newton step is computed. + // + // This constant is passed to ConjugateGradientsSolver which uses + // it to terminate the iterations when + // + // (Q_i - Q_{i-1})/Q_i < eta/i + double eta; + + // Normalize the jacobian using Jacobi scaling before calling + // the linear least squares solver. + bool jacobi_scaling; + + // Logging options --------------------------------------------------------- + + LoggingType logging_type; + + // By default the Minimizer progress is logged to VLOG(1), which + // is sent to STDERR depending on the vlog level. If this flag is + // set to true, and logging_type is not SILENT, the logging output + // is sent to STDOUT. + bool minimizer_progress_to_stdout; + + // List of iterations at which the minimizer should dump the trust + // region problem. Useful for testing and benchmarking. If empty + // (default), no problems are dumped. + std::vector trust_region_minimizer_iterations_to_dump; + + // Directory to which the problems should be written to. Should be + // non-empty if trust_region_minimizer_iterations_to_dump is + // non-empty and trust_region_problem_dump_format_type is not + // CONSOLE. + std::string trust_region_problem_dump_directory; + DumpFormatType trust_region_problem_dump_format_type; + + // Finite differences options ---------------------------------------------- + + // Check all jacobians computed by each residual block with finite + // differences. This is expensive since it involves computing the + // derivative by normal means (e.g. user specified, autodiff, + // etc), then also computing it using finite differences. The + // results are compared, and if they differ substantially, details + // are printed to the log. + bool check_gradients; + + // Relative precision to check for in the gradient checker. If the + // relative difference between an element in a jacobian exceeds + // this number, then the jacobian for that cost term is dumped. + double gradient_check_relative_precision; + + // WARNING: This option only applies to the to the numeric + // differentiation used for checking the user provided derivatives + // when when Solver::Options::check_gradients is true. If you are + // using NumericDiffCostFunction and are interested in changing + // the step size for numeric differentiation in your cost + // function, please have a look at + // include/ceres/numeric_diff_options.h. + // + // Relative shift used for taking numeric derivatives when + // Solver::Options::check_gradients is true. + // + // For finite differencing, each dimension is evaluated at + // slightly shifted values; for the case of central difference, + // this is what gets evaluated: + // + // delta = gradient_check_numeric_derivative_relative_step_size; + // f_initial = f(x) + // f_forward = f((1 + delta) * x) + // f_backward = f((1 - delta) * x) + // + // The finite differencing is done along each dimension. The + // reason to use a relative (rather than absolute) step size is + // that this way, numeric differentation works for functions where + // the arguments are typically large (e.g. 1e9) and when the + // values are small (e.g. 1e-5). It is possible to construct + // "torture cases" which break this finite difference heuristic, + // but they do not come up often in practice. + // + // TODO(keir): Pick a smarter number than the default above! In + // theory a good choice is sqrt(eps) * x, which for doubles means + // about 1e-8 * x. However, I have found this number too + // optimistic. This number should be exposed for users to change. + double gradient_check_numeric_derivative_relative_step_size; + + // If true, the user's parameter blocks are updated at the end of + // every Minimizer iteration, otherwise they are updated when the + // Minimizer terminates. This is useful if, for example, the user + // wishes to visualize the state of the optimization every + // iteration. + bool update_state_every_iteration; + + // Callbacks that are executed at the end of each iteration of the + // Minimizer. An iteration may terminate midway, either due to + // numerical failures or because one of the convergence tests has + // been satisfied. In this case none of the callbacks are + // executed. + + // Callbacks are executed in the order that they are specified in + // this vector. By default, parameter blocks are updated only at + // the end of the optimization, i.e when the Minimizer + // terminates. This behaviour is controlled by + // update_state_every_variable. If the user wishes to have access + // to the update parameter blocks when his/her callbacks are + // executed, then set update_state_every_iteration to true. + // + // The solver does NOT take ownership of these pointers. + std::vector callbacks; + }; + + struct CERES_EXPORT Summary { + Summary(); + + // A brief one line description of the state of the solver after + // termination. + std::string BriefReport() const; + + // A full multiline description of the state of the solver after + // termination. + std::string FullReport() const; + + bool IsSolutionUsable() const; + + // Minimizer summary ------------------------------------------------- + MinimizerType minimizer_type; + + TerminationType termination_type; + + // Reason why the solver terminated. + std::string message; + + // Cost of the problem (value of the objective function) before + // the optimization. + double initial_cost; + + // Cost of the problem (value of the objective function) after the + // optimization. + double final_cost; + + // The part of the total cost that comes from residual blocks that + // were held fixed by the preprocessor because all the parameter + // blocks that they depend on were fixed. + double fixed_cost; + + // IterationSummary for each minimizer iteration in order. + std::vector iterations; + + // Number of minimizer iterations in which the step was + // accepted. Unless use_non_monotonic_steps is true this is also + // the number of steps in which the objective function value/cost + // went down. + int num_successful_steps; + + // Number of minimizer iterations in which the step was rejected + // either because it did not reduce the cost enough or the step + // was not numerically valid. + int num_unsuccessful_steps; + + // Number of times inner iterations were performed. + int num_inner_iteration_steps; + + // Total number of iterations inside the line search algorithm + // across all invocations. We call these iterations "steps" to + // distinguish them from the outer iterations of the line search + // and trust region minimizer algorithms which call the line + // search algorithm as a subroutine. + int num_line_search_steps; + + // All times reported below are wall times. + + // When the user calls Solve, before the actual optimization + // occurs, Ceres performs a number of preprocessing steps. These + // include error checks, memory allocations, and reorderings. This + // time is accounted for as preprocessing time. + double preprocessor_time_in_seconds; + + // Time spent in the TrustRegionMinimizer. + double minimizer_time_in_seconds; + + // After the Minimizer is finished, some time is spent in + // re-evaluating residuals etc. This time is accounted for in the + // postprocessor time. + double postprocessor_time_in_seconds; + + // Some total of all time spent inside Ceres when Solve is called. + double total_time_in_seconds; + + // Time (in seconds) spent in the linear solver computing the + // trust region step. + double linear_solver_time_in_seconds; + + // Time (in seconds) spent evaluating the residual vector. + double residual_evaluation_time_in_seconds; + + // Time (in seconds) spent evaluating the jacobian matrix. + double jacobian_evaluation_time_in_seconds; + + // Time (in seconds) spent doing inner iterations. + double inner_iteration_time_in_seconds; + + // Cumulative timing information for line searches performed as part of the + // solve. Note that in addition to the case when the Line Search minimizer + // is used, the Trust Region minimizer also uses a line search when + // solving a constrained problem. + + // Time (in seconds) spent evaluating the univariate cost function as part + // of a line search. + double line_search_cost_evaluation_time_in_seconds; + + // Time (in seconds) spent evaluating the gradient of the univariate cost + // function as part of a line search. + double line_search_gradient_evaluation_time_in_seconds; + + // Time (in seconds) spent minimizing the interpolating polynomial + // to compute the next candidate step size as part of a line search. + double line_search_polynomial_minimization_time_in_seconds; + + // Total time (in seconds) spent performing line searches. + double line_search_total_time_in_seconds; + + // Number of parameter blocks in the problem. + int num_parameter_blocks; + + // Number of parameters in the probem. + int num_parameters; + + // Dimension of the tangent space of the problem (or the number of + // columns in the Jacobian for the problem). This is different + // from num_parameters if a parameter block is associated with a + // LocalParameterization + int num_effective_parameters; + + // Number of residual blocks in the problem. + int num_residual_blocks; + + // Number of residuals in the problem. + int num_residuals; + + // Number of parameter blocks in the problem after the inactive + // and constant parameter blocks have been removed. A parameter + // block is inactive if no residual block refers to it. + int num_parameter_blocks_reduced; + + // Number of parameters in the reduced problem. + int num_parameters_reduced; + + // Dimension of the tangent space of the reduced problem (or the + // number of columns in the Jacobian for the reduced + // problem). This is different from num_parameters_reduced if a + // parameter block in the reduced problem is associated with a + // LocalParameterization. + int num_effective_parameters_reduced; + + // Number of residual blocks in the reduced problem. + int num_residual_blocks_reduced; + + // Number of residuals in the reduced problem. + int num_residuals_reduced; + + // Is the reduced problem bounds constrained. + bool is_constrained; + + // Number of threads specified by the user for Jacobian and + // residual evaluation. + int num_threads_given; + + // Number of threads actually used by the solver for Jacobian and + // residual evaluation. This number is not equal to + // num_threads_given if OpenMP is not available. + int num_threads_used; + + // Number of threads specified by the user for solving the trust + // region problem. + int num_linear_solver_threads_given; + + // Number of threads actually used by the solver for solving the + // trust region problem. This number is not equal to + // num_threads_given if OpenMP is not available. + int num_linear_solver_threads_used; + + // Type of the linear solver requested by the user. + LinearSolverType linear_solver_type_given; + + // Type of the linear solver actually used. This may be different + // from linear_solver_type_given if Ceres determines that the + // problem structure is not compatible with the linear solver + // requested or if the linear solver requested by the user is not + // available, e.g. The user requested SPARSE_NORMAL_CHOLESKY but + // no sparse linear algebra library was available. + LinearSolverType linear_solver_type_used; + + // Size of the elimination groups given by the user as hints to + // the linear solver. + std::vector linear_solver_ordering_given; + + // Size of the parameter groups used by the solver when ordering + // the columns of the Jacobian. This maybe different from + // linear_solver_ordering_given if the user left + // linear_solver_ordering_given blank and asked for an automatic + // ordering, or if the problem contains some constant or inactive + // parameter blocks. + std::vector linear_solver_ordering_used; + + // For Schur type linear solvers, this string describes the + // template specialization which was detected in the problem and + // should be used. + std::string schur_structure_given; + + // This is the Schur template specialization that was actually + // instantiated and used. The reason this will be different from + // schur_structure_given is because the corresponding template + // specialization does not exist. + // + // Template specializations can be added to ceres by editing + // internal/ceres/generate_template_specializations.py + std::string schur_structure_used; + + // True if the user asked for inner iterations to be used as part + // of the optimization. + bool inner_iterations_given; + + // True if the user asked for inner iterations to be used as part + // of the optimization and the problem structure was such that + // they were actually performed. e.g., in a problem with just one + // parameter block, inner iterations are not performed. + bool inner_iterations_used; + + // Size of the parameter groups given by the user for performing + // inner iterations. + std::vector inner_iteration_ordering_given; + + // Size of the parameter groups given used by the solver for + // performing inner iterations. This maybe different from + // inner_iteration_ordering_given if the user left + // inner_iteration_ordering_given blank and asked for an automatic + // ordering, or if the problem contains some constant or inactive + // parameter blocks. + std::vector inner_iteration_ordering_used; + + // Type of the preconditioner requested by the user. + PreconditionerType preconditioner_type_given; + + // Type of the preconditioner actually used. This may be different + // from linear_solver_type_given if Ceres determines that the + // problem structure is not compatible with the linear solver + // requested or if the linear solver requested by the user is not + // available. + PreconditionerType preconditioner_type_used; + + // Type of clustering algorithm used for visibility based + // preconditioning. Only meaningful when the preconditioner_type + // is CLUSTER_JACOBI or CLUSTER_TRIDIAGONAL. + VisibilityClusteringType visibility_clustering_type; + + // Type of trust region strategy. + TrustRegionStrategyType trust_region_strategy_type; + + // Type of dogleg strategy used for solving the trust region + // problem. + DoglegType dogleg_type; + + // Type of the dense linear algebra library used. + DenseLinearAlgebraLibraryType dense_linear_algebra_library_type; + + // Type of the sparse linear algebra library used. + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; + + // Type of line search direction used. + LineSearchDirectionType line_search_direction_type; + + // Type of the line search algorithm used. + LineSearchType line_search_type; + + // When performing line search, the degree of the polynomial used + // to approximate the objective function. + LineSearchInterpolationType line_search_interpolation_type; + + // If the line search direction is NONLINEAR_CONJUGATE_GRADIENT, + // then this indicates the particular variant of non-linear + // conjugate gradient used. + NonlinearConjugateGradientType nonlinear_conjugate_gradient_type; + + // If the type of the line search direction is LBFGS, then this + // indicates the rank of the Hessian approximation. + int max_lbfgs_rank; + }; + + // Once a least squares problem has been built, this function takes + // the problem and optimizes it based on the values of the options + // parameters. Upon return, a detailed summary of the work performed + // by the preprocessor, the non-linear minmizer and the linear + // solver are reported in the summary object. + virtual void Solve(const Options& options, + Problem* problem, + Solver::Summary* summary); +}; + +// Helper function which avoids going through the interface. +CERES_EXPORT void Solve(const Solver::Options& options, + Problem* problem, + Solver::Summary* summary); + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_SOLVER_H_ diff --git a/include/ceres/types.h b/include/ceres/types.h new file mode 100644 index 0000000..a4a4861 --- /dev/null +++ b/include/ceres/types.h @@ -0,0 +1,514 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Enums and other top level class definitions. +// +// Note: internal/types.cc defines stringification routines for some +// of these enums. Please update those routines if you extend or +// remove enums from here. + +#ifndef CERES_PUBLIC_TYPES_H_ +#define CERES_PUBLIC_TYPES_H_ + +#include + +#include "ceres/internal/port.h" +#include "ceres/internal/disable_warnings.h" + +namespace ceres { + +// Basic integer types. These typedefs are in the Ceres namespace to avoid +// conflicts with other packages having similar typedefs. +typedef int int32; + +// Argument type used in interfaces that can optionally take ownership +// of a passed in argument. If TAKE_OWNERSHIP is passed, the called +// object takes ownership of the pointer argument, and will call +// delete on it upon completion. +enum Ownership { + DO_NOT_TAKE_OWNERSHIP, + TAKE_OWNERSHIP +}; + +// TODO(keir): Considerably expand the explanations of each solver type. +enum LinearSolverType { + // These solvers are for general rectangular systems formed from the + // normal equations A'A x = A'b. They are direct solvers and do not + // assume any special problem structure. + + // Solve the normal equations using a dense Cholesky solver; based + // on Eigen. + DENSE_NORMAL_CHOLESKY, + + // Solve the normal equations using a dense QR solver; based on + // Eigen. + DENSE_QR, + + // Solve the normal equations using a sparse cholesky solver; requires + // SuiteSparse or CXSparse. + SPARSE_NORMAL_CHOLESKY, + + // Specialized solvers, specific to problems with a generalized + // bi-partitite structure. + + // Solves the reduced linear system using a dense Cholesky solver; + // based on Eigen. + DENSE_SCHUR, + + // Solves the reduced linear system using a sparse Cholesky solver; + // based on CHOLMOD. + SPARSE_SCHUR, + + // Solves the reduced linear system using Conjugate Gradients, based + // on a new Ceres implementation. Suitable for large scale + // problems. + ITERATIVE_SCHUR, + + // Conjugate gradients on the normal equations. + CGNR +}; + +enum PreconditionerType { + // Trivial preconditioner - the identity matrix. + IDENTITY, + + // Block diagonal of the Gauss-Newton Hessian. + JACOBI, + + // Note: The following three preconditioners can only be used with + // the ITERATIVE_SCHUR solver. They are well suited for Structure + // from Motion problems. + + // Block diagonal of the Schur complement. This preconditioner may + // only be used with the ITERATIVE_SCHUR solver. + SCHUR_JACOBI, + + // Visibility clustering based preconditioners. + // + // The following two preconditioners use the visibility structure of + // the scene to determine the sparsity structure of the + // preconditioner. This is done using a clustering algorithm. The + // available visibility clustering algorithms are described below. + // + // Note: Requires SuiteSparse. + CLUSTER_JACOBI, + CLUSTER_TRIDIAGONAL +}; + +enum VisibilityClusteringType { + // Canonical views algorithm as described in + // + // "Scene Summarization for Online Image Collections", Ian Simon, Noah + // Snavely, Steven M. Seitz, ICCV 2007. + // + // This clustering algorithm can be quite slow, but gives high + // quality clusters. The original visibility based clustering paper + // used this algorithm. + CANONICAL_VIEWS, + + // The classic single linkage algorithm. It is extremely fast as + // compared to CANONICAL_VIEWS, but can give slightly poorer + // results. For problems with large number of cameras though, this + // is generally a pretty good option. + // + // If you are using SCHUR_JACOBI preconditioner and have SuiteSparse + // available, CLUSTER_JACOBI and CLUSTER_TRIDIAGONAL in combination + // with the SINGLE_LINKAGE algorithm will generally give better + // results. + SINGLE_LINKAGE +}; + +enum SparseLinearAlgebraLibraryType { + // High performance sparse Cholesky factorization and approximate + // minimum degree ordering. + SUITE_SPARSE, + + // A lightweight replacment for SuiteSparse, which does not require + // a LAPACK/BLAS implementation. Consequently, its performance is + // also a bit lower than SuiteSparse. + CX_SPARSE, + + // Eigen's sparse linear algebra routines. In particular Ceres uses + // the Simplicial LDLT routines. + EIGEN_SPARSE, + + // No sparse linear solver should be used. This does not necessarily + // imply that Ceres was built without any sparse library, although that + // is the likely use case, merely that one should not be used. + NO_SPARSE +}; + +enum DenseLinearAlgebraLibraryType { + EIGEN, + LAPACK +}; + +// Logging options +// The options get progressively noisier. +enum LoggingType { + SILENT, + PER_MINIMIZER_ITERATION +}; + +enum MinimizerType { + LINE_SEARCH, + TRUST_REGION +}; + +enum LineSearchDirectionType { + // Negative of the gradient. + STEEPEST_DESCENT, + + // A generalization of the Conjugate Gradient method to non-linear + // functions. The generalization can be performed in a number of + // different ways, resulting in a variety of search directions. The + // precise choice of the non-linear conjugate gradient algorithm + // used is determined by NonlinerConjuateGradientType. + NONLINEAR_CONJUGATE_GRADIENT, + + // BFGS, and it's limited memory approximation L-BFGS, are quasi-Newton + // algorithms that approximate the Hessian matrix by iteratively refining + // an initial estimate with rank-one updates using the gradient at each + // iteration. They are a generalisation of the Secant method and satisfy + // the Secant equation. The Secant equation has an infinium of solutions + // in multiple dimensions, as there are N*(N+1)/2 degrees of freedom in a + // symmetric matrix but only N conditions are specified by the Secant + // equation. The requirement that the Hessian approximation be positive + // definite imposes another N additional constraints, but that still leaves + // remaining degrees-of-freedom. (L)BFGS methods uniquely deteremine the + // approximate Hessian by imposing the additional constraints that the + // approximation at the next iteration must be the 'closest' to the current + // approximation (the nature of how this proximity is measured is actually + // the defining difference between a family of quasi-Newton methods including + // (L)BFGS & DFP). (L)BFGS is currently regarded as being the best known + // general quasi-Newton method. + // + // The principal difference between BFGS and L-BFGS is that whilst BFGS + // maintains a full, dense approximation to the (inverse) Hessian, L-BFGS + // maintains only a window of the last M observations of the parameters and + // gradients. Using this observation history, the calculation of the next + // search direction can be computed without requiring the construction of the + // full dense inverse Hessian approximation. This is particularly important + // for problems with a large number of parameters, where storage of an N-by-N + // matrix in memory would be prohibitive. + // + // For more details on BFGS see: + // + // Broyden, C.G., "The Convergence of a Class of Double-rank Minimization + // Algorithms,"; J. Inst. Maths. Applics., Vol. 6, pp 76–90, 1970. + // + // Fletcher, R., "A New Approach to Variable Metric Algorithms," + // Computer Journal, Vol. 13, pp 317–322, 1970. + // + // Goldfarb, D., "A Family of Variable Metric Updates Derived by Variational + // Means," Mathematics of Computing, Vol. 24, pp 23–26, 1970. + // + // Shanno, D.F., "Conditioning of Quasi-Newton Methods for Function + // Minimization," Mathematics of Computing, Vol. 24, pp 647–656, 1970. + // + // For more details on L-BFGS see: + // + // Nocedal, J. (1980). "Updating Quasi-Newton Matrices with Limited + // Storage". Mathematics of Computation 35 (151): 773–782. + // + // Byrd, R. H.; Nocedal, J.; Schnabel, R. B. (1994). + // "Representations of Quasi-Newton Matrices and their use in + // Limited Memory Methods". Mathematical Programming 63 (4): + // 129–156. + // + // A general reference for both methods: + // + // Nocedal J., Wright S., Numerical Optimization, 2nd Ed. Springer, 1999. + LBFGS, + BFGS, +}; + +// Nonliner conjugate gradient methods are a generalization of the +// method of Conjugate Gradients for linear systems. The +// generalization can be carried out in a number of different ways +// leading to number of different rules for computing the search +// direction. Ceres provides a number of different variants. For more +// details see Numerical Optimization by Nocedal & Wright. +enum NonlinearConjugateGradientType { + FLETCHER_REEVES, + POLAK_RIBIERE, + HESTENES_STIEFEL, +}; + +enum LineSearchType { + // Backtracking line search with polynomial interpolation or + // bisection. + ARMIJO, + WOLFE, +}; + +// Ceres supports different strategies for computing the trust region +// step. +enum TrustRegionStrategyType { + // The default trust region strategy is to use the step computation + // used in the Levenberg-Marquardt algorithm. For more details see + // levenberg_marquardt_strategy.h + LEVENBERG_MARQUARDT, + + // Powell's dogleg algorithm interpolates between the Cauchy point + // and the Gauss-Newton step. It is particularly useful if the + // LEVENBERG_MARQUARDT algorithm is making a large number of + // unsuccessful steps. For more details see dogleg_strategy.h. + // + // NOTES: + // + // 1. This strategy has not been experimented with or tested as + // extensively as LEVENBERG_MARQUARDT, and therefore it should be + // considered EXPERIMENTAL for now. + // + // 2. For now this strategy should only be used with exact + // factorization based linear solvers, i.e., SPARSE_SCHUR, + // DENSE_SCHUR, DENSE_QR and SPARSE_NORMAL_CHOLESKY. + DOGLEG +}; + +// Ceres supports two different dogleg strategies. +// The "traditional" dogleg method by Powell and the +// "subspace" method described in +// R. H. Byrd, R. B. Schnabel, and G. A. Shultz, +// "Approximate solution of the trust region problem by minimization +// over two-dimensional subspaces", Mathematical Programming, +// 40 (1988), pp. 247--263 +enum DoglegType { + // The traditional approach constructs a dogleg path + // consisting of two line segments and finds the furthest + // point on that path that is still inside the trust region. + TRADITIONAL_DOGLEG, + + // The subspace approach finds the exact minimum of the model + // constrained to the subspace spanned by the dogleg path. + SUBSPACE_DOGLEG +}; + +enum TerminationType { + // Minimizer terminated because one of the convergence criterion set + // by the user was satisfied. + // + // 1. (new_cost - old_cost) < function_tolerance * old_cost; + // 2. max_i |gradient_i| < gradient_tolerance + // 3. |step|_2 <= parameter_tolerance * ( |x|_2 + parameter_tolerance) + // + // The user's parameter blocks will be updated with the solution. + CONVERGENCE, + + // The solver ran for maximum number of iterations or maximum amount + // of time specified by the user, but none of the convergence + // criterion specified by the user were met. The user's parameter + // blocks will be updated with the solution found so far. + NO_CONVERGENCE, + + // The minimizer terminated because of an error. The user's + // parameter blocks will not be updated. + FAILURE, + + // Using an IterationCallback object, user code can control the + // minimizer. The following enums indicate that the user code was + // responsible for termination. + // + // Minimizer terminated successfully because a user + // IterationCallback returned SOLVER_TERMINATE_SUCCESSFULLY. + // + // The user's parameter blocks will be updated with the solution. + USER_SUCCESS, + + // Minimizer terminated because because a user IterationCallback + // returned SOLVER_ABORT. + // + // The user's parameter blocks will not be updated. + USER_FAILURE +}; + +// Enums used by the IterationCallback instances to indicate to the +// solver whether it should continue solving, the user detected an +// error or the solution is good enough and the solver should +// terminate. +enum CallbackReturnType { + // Continue solving to next iteration. + SOLVER_CONTINUE, + + // Terminate solver, and do not update the parameter blocks upon + // return. Unless the user has set + // Solver:Options:::update_state_every_iteration, in which case the + // state would have been updated every iteration + // anyways. Solver::Summary::termination_type is set to USER_ABORT. + SOLVER_ABORT, + + // Terminate solver, update state and + // return. Solver::Summary::termination_type is set to USER_SUCCESS. + SOLVER_TERMINATE_SUCCESSFULLY +}; + +// The format in which linear least squares problems should be logged +// when Solver::Options::lsqp_iterations_to_dump is non-empty. +enum DumpFormatType { + // Print the linear least squares problem in a human readable format + // to stderr. The Jacobian is printed as a dense matrix. The vectors + // D, x and f are printed as dense vectors. This should only be used + // for small problems. + CONSOLE, + + // Write out the linear least squares problem to the directory + // pointed to by Solver::Options::lsqp_dump_directory as text files + // which can be read into MATLAB/Octave. The Jacobian is dumped as a + // text file containing (i,j,s) triplets, the vectors D, x and f are + // dumped as text files containing a list of their values. + // + // A MATLAB/octave script called lm_iteration_???.m is also output, + // which can be used to parse and load the problem into memory. + TEXTFILE +}; + +// For SizedCostFunction and AutoDiffCostFunction, DYNAMIC can be +// specified for the number of residuals. If specified, then the +// number of residuas for that cost function can vary at runtime. +enum DimensionType { + DYNAMIC = -1 +}; + +// The differentiation method used to compute numerical derivatives in +// NumericDiffCostFunction and DynamicNumericDiffCostFunction. +enum NumericDiffMethodType { + // Compute central finite difference: f'(x) ~ (f(x+h) - f(x-h)) / 2h. + CENTRAL, + + // Compute forward finite difference: f'(x) ~ (f(x+h) - f(x)) / h. + FORWARD, + + // Adaptive numerical differentiation using Ridders' method. Provides more + // accurate and robust derivatives at the expense of additional cost + // function evaluations. + RIDDERS +}; + +enum LineSearchInterpolationType { + BISECTION, + QUADRATIC, + CUBIC +}; + +enum CovarianceAlgorithmType { + DENSE_SVD, + SPARSE_QR, +}; + +// It is a near impossibility that user code generates this exact +// value in normal operation, thus we will use it to fill arrays +// before passing them to user code. If on return an element of the +// array still contains this value, we will assume that the user code +// did not write to that memory location. +const double kImpossibleValue = 1e302; + +CERES_EXPORT const char* LinearSolverTypeToString( + LinearSolverType type); +CERES_EXPORT bool StringToLinearSolverType(std::string value, + LinearSolverType* type); + +CERES_EXPORT const char* PreconditionerTypeToString(PreconditionerType type); +CERES_EXPORT bool StringToPreconditionerType(std::string value, + PreconditionerType* type); + +CERES_EXPORT const char* VisibilityClusteringTypeToString( + VisibilityClusteringType type); +CERES_EXPORT bool StringToVisibilityClusteringType(std::string value, + VisibilityClusteringType* type); + +CERES_EXPORT const char* SparseLinearAlgebraLibraryTypeToString( + SparseLinearAlgebraLibraryType type); +CERES_EXPORT bool StringToSparseLinearAlgebraLibraryType( + std::string value, + SparseLinearAlgebraLibraryType* type); + +CERES_EXPORT const char* DenseLinearAlgebraLibraryTypeToString( + DenseLinearAlgebraLibraryType type); +CERES_EXPORT bool StringToDenseLinearAlgebraLibraryType( + std::string value, + DenseLinearAlgebraLibraryType* type); + +CERES_EXPORT const char* TrustRegionStrategyTypeToString( + TrustRegionStrategyType type); +CERES_EXPORT bool StringToTrustRegionStrategyType(std::string value, + TrustRegionStrategyType* type); + +CERES_EXPORT const char* DoglegTypeToString(DoglegType type); +CERES_EXPORT bool StringToDoglegType(std::string value, DoglegType* type); + +CERES_EXPORT const char* MinimizerTypeToString(MinimizerType type); +CERES_EXPORT bool StringToMinimizerType(std::string value, MinimizerType* type); + +CERES_EXPORT const char* LineSearchDirectionTypeToString( + LineSearchDirectionType type); +CERES_EXPORT bool StringToLineSearchDirectionType(std::string value, + LineSearchDirectionType* type); + +CERES_EXPORT const char* LineSearchTypeToString(LineSearchType type); +CERES_EXPORT bool StringToLineSearchType(std::string value, LineSearchType* type); + +CERES_EXPORT const char* NonlinearConjugateGradientTypeToString( + NonlinearConjugateGradientType type); +CERES_EXPORT bool StringToNonlinearConjugateGradientType( + std::string value, + NonlinearConjugateGradientType* type); + +CERES_EXPORT const char* LineSearchInterpolationTypeToString( + LineSearchInterpolationType type); +CERES_EXPORT bool StringToLineSearchInterpolationType( + std::string value, + LineSearchInterpolationType* type); + +CERES_EXPORT const char* CovarianceAlgorithmTypeToString( + CovarianceAlgorithmType type); +CERES_EXPORT bool StringToCovarianceAlgorithmType( + std::string value, + CovarianceAlgorithmType* type); + +CERES_EXPORT const char* NumericDiffMethodTypeToString( + NumericDiffMethodType type); +CERES_EXPORT bool StringToNumericDiffMethodType( + std::string value, + NumericDiffMethodType* type); + +CERES_EXPORT const char* TerminationTypeToString(TerminationType type); + +CERES_EXPORT bool IsSchurType(LinearSolverType type); +CERES_EXPORT bool IsSparseLinearAlgebraLibraryTypeAvailable( + SparseLinearAlgebraLibraryType type); +CERES_EXPORT bool IsDenseLinearAlgebraLibraryTypeAvailable( + DenseLinearAlgebraLibraryType type); + +} // namespace ceres + +#include "ceres/internal/reenable_warnings.h" + +#endif // CERES_PUBLIC_TYPES_H_ diff --git a/include/ceres/version.h b/include/ceres/version.h new file mode 100644 index 0000000..beab7d9 --- /dev/null +++ b/include/ceres/version.h @@ -0,0 +1,48 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: mierle@gmail.com (Keir Mierle) + +#ifndef CERES_PUBLIC_VERSION_H_ +#define CERES_PUBLIC_VERSION_H_ + +#define CERES_VERSION_MAJOR 1 +#define CERES_VERSION_MINOR 13 +#define CERES_VERSION_REVISION 0 + +// Classic CPP stringifcation; the extra level of indirection allows the +// preprocessor to expand the macro before being converted to a string. +#define CERES_TO_STRING_HELPER(x) #x +#define CERES_TO_STRING(x) CERES_TO_STRING_HELPER(x) + +// The Ceres version as a string; for example "1.9.0". +#define CERES_VERSION_STRING CERES_TO_STRING(CERES_VERSION_MAJOR) "." \ + CERES_TO_STRING(CERES_VERSION_MINOR) "." \ + CERES_TO_STRING(CERES_VERSION_REVISION) + +#endif // CERES_PUBLIC_VERSION_H_ diff --git a/internal/ceres/CMakeLists.txt b/internal/ceres/CMakeLists.txt new file mode 100644 index 0000000..21669d0 --- /dev/null +++ b/internal/ceres/CMakeLists.txt @@ -0,0 +1,363 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: keir@google.com (Keir Mierle) + +set(CERES_INTERNAL_SRC + array_utils.cc + blas.cc + block_evaluate_preparer.cc + block_jacobi_preconditioner.cc + block_jacobian_writer.cc + block_random_access_dense_matrix.cc + block_random_access_diagonal_matrix.cc + block_random_access_matrix.cc + block_random_access_sparse_matrix.cc + block_sparse_matrix.cc + block_structure.cc + c_api.cc + canonical_views_clustering.cc + cgnr_solver.cc + callbacks.cc + compressed_col_sparse_matrix_utils.cc + compressed_row_jacobian_writer.cc + compressed_row_sparse_matrix.cc + conditioned_cost_function.cc + conjugate_gradients_solver.cc + coordinate_descent_minimizer.cc + corrector.cc + covariance.cc + covariance_impl.cc + cxsparse.cc + dense_normal_cholesky_solver.cc + dense_qr_solver.cc + dense_sparse_matrix.cc + detect_structure.cc + dogleg_strategy.cc + dynamic_compressed_row_jacobian_writer.cc + dynamic_compressed_row_sparse_matrix.cc + dynamic_sparse_normal_cholesky_solver.cc + evaluator.cc + eigensparse.cc + file.cc + function_sample.cc + gradient_checker.cc + gradient_checking_cost_function.cc + gradient_problem.cc + gradient_problem_solver.cc + implicit_schur_complement.cc + inner_product_computer.cc + is_close.cc + iterative_schur_complement_solver.cc + levenberg_marquardt_strategy.cc + lapack.cc + line_search.cc + line_search_direction.cc + line_search_minimizer.cc + line_search_preprocessor.cc + linear_least_squares_problems.cc + linear_operator.cc + linear_solver.cc + local_parameterization.cc + loss_function.cc + low_rank_inverse_hessian.cc + minimizer.cc + normal_prior.cc + parameter_block_ordering.cc + partitioned_matrix_view.cc + polynomial.cc + preconditioner.cc + preprocessor.cc + problem.cc + problem_impl.cc + program.cc + reorder_program.cc + residual_block.cc + residual_block_utils.cc + schur_complement_solver.cc + schur_eliminator.cc + schur_jacobi_preconditioner.cc + schur_templates.cc + scratch_evaluate_preparer.cc + single_linkage_clustering.cc + solver.cc + solver_utils.cc + sparse_matrix.cc + sparse_cholesky.cc + sparse_normal_cholesky_solver.cc + split.cc + stringprintf.cc + suitesparse.cc + triplet_sparse_matrix.cc + trust_region_preprocessor.cc + trust_region_minimizer.cc + trust_region_step_evaluator.cc + trust_region_strategy.cc + types.cc + visibility.cc + visibility_based_preconditioner.cc + wall_time.cc +) + +# Also depend on the header files so that they appear in IDEs. +file(GLOB CERES_INTERNAL_HDRS *.h) +if (MINIGLOG) + file(GLOB MINIGLOG_HDRS miniglog/glog/*.h) + list(APPEND CERES_INTERNAL_HDRS ${MINIGLOG_HDRS}) +endif() + +# Depend also on public headers so they appear in IDEs. +file(GLOB CERES_PUBLIC_HDRS ${Ceres_SOURCE_DIR}/include/ceres/*.h) +file(GLOB CERES_PUBLIC_INTERNAL_HDRS ${Ceres_SOURCE_DIR}/include/ceres/internal/*.h) + +# Include the specialized schur solvers. +if (SCHUR_SPECIALIZATIONS) + file(GLOB CERES_INTERNAL_SCHUR_FILES generated/*.cc) +else (SCHUR_SPECIALIZATIONS) + # Only the fully dynamic solver. The build is much faster this way. + file(GLOB CERES_INTERNAL_SCHUR_FILES generated/*_d_d_d.cc) +endif (SCHUR_SPECIALIZATIONS) + +# Build the list of dependencies for Ceres based on the current configuration. +if (NOT MINIGLOG AND GLOG_FOUND) + list(APPEND CERES_LIBRARY_PUBLIC_DEPENDENCIES ${GLOG_LIBRARIES}) + if (GFLAGS_FOUND) + # If glog & gflags are both found, we assume that glog was built with + # gflags, as it is awkward to perform a try_compile() to verify this + # when gflags is an imported target (as it is in newer versions). + # As glog #includes gflags/gflags.h in glog/logging.h if compiled with + # gflags, it is thus a public dependency for Ceres in this case. + list(APPEND CERES_LIBRARY_PUBLIC_DEPENDENCIES ${GFLAGS_LIBRARIES}) + endif() +endif (NOT MINIGLOG AND GLOG_FOUND) + +if (SUITESPARSE AND SUITESPARSE_FOUND) + # Define version information for use in Solver::FullReport. + add_definitions(-DCERES_SUITESPARSE_VERSION="${SUITESPARSE_VERSION}") + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES ${SUITESPARSE_LIBRARIES}) +endif (SUITESPARSE AND SUITESPARSE_FOUND) + +if (CXSPARSE AND CXSPARSE_FOUND) + # Define version information for use in Solver::FullReport. + add_definitions(-DCERES_CXSPARSE_VERSION="${CXSPARSE_VERSION}") + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES ${CXSPARSE_LIBRARIES}) +endif (CXSPARSE AND CXSPARSE_FOUND) + +if (BLAS_FOUND AND LAPACK_FOUND) + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES ${LAPACK_LIBRARIES}) + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES ${BLAS_LIBRARIES}) +endif (BLAS_FOUND AND LAPACK_FOUND) + +if (OPENMP_FOUND) + # OpenMP support in Clang requires a non-GNU OpenMP library. + if (CMAKE_COMPILER_IS_GNUCXX) + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES gomp) + endif() + if (NOT MSVC) + list(APPEND CERES_LIBRARY_PRIVATE_DEPENDENCIES ${CMAKE_THREAD_LIBS_INIT}) + endif() +endif (OPENMP_FOUND) + +set(CERES_LIBRARY_SOURCE + ${CERES_INTERNAL_SRC} + ${CERES_INTERNAL_HDRS} + ${CERES_PUBLIC_HDRS} + ${CERES_PUBLIC_INTERNAL_HDRS} + ${CERES_INTERNAL_SCHUR_FILES}) + +# Primarily for Android, but optionally for others, compile the minimal +# glog implementation into Ceres. +if (MINIGLOG) + list(APPEND CERES_LIBRARY_SOURCE miniglog/glog/logging.cc) +endif (MINIGLOG) + +add_library(ceres ${CERES_LIBRARY_SOURCE}) +set_target_properties(ceres PROPERTIES + VERSION ${CERES_VERSION} + SOVERSION ${CERES_VERSION_MAJOR}) + +include(AppendTargetProperty) +# Always build position-independent code (PIC), even when building Ceres as a +# static library so that shared libraries can link against it, not just +# executables (PIC does not apply on Windows). +if (NOT WIN32 AND NOT BUILD_SHARED_LIBS) + # Use the explicit POSITION_INDEPENDENT_CODE target property on CMake versions + # that support it (>= 2.8.9). Otherwise, manually add the -fPIC flag as an + # additional compile definitions for the target. + if (CMAKE_VERSION VERSION_LESS "2.8.9") + append_target_property(ceres COMPILE_FLAGS "-fPIC") + else() + # Use set_target_properties() not append_target_property() here as + # POSITION_INDEPENDENT_CODE is a binary ON/OFF switch. + set_target_properties(ceres PROPERTIES POSITION_INDEPENDENT_CODE ON) + endif() +endif() + +if (CXX11) + include(AddCeresCXX11RequirementsToTarget) + add_ceres_cxx11_requirements_to_target(ceres) +endif() + +if (BUILD_SHARED_LIBS) + # When building a shared library, mark all external libraries as + # PRIVATE so they don't show up as a dependency. + target_link_libraries(ceres + LINK_PUBLIC ${CERES_LIBRARY_PUBLIC_DEPENDENCIES} + LINK_PRIVATE ${CERES_LIBRARY_PRIVATE_DEPENDENCIES}) +else (BUILD_SHARED_LIBS) + # When building a static library, all external libraries are + # PUBLIC(default) since the user needs to link to them. + # They will be listed in CeresTargets.cmake. + set(CERES_LIBRARY_DEPENDENCIES + ${CERES_LIBRARY_PUBLIC_DEPENDENCIES} + ${CERES_LIBRARY_PRIVATE_DEPENDENCIES}) + target_link_libraries(ceres ${CERES_LIBRARY_DEPENDENCIES}) +endif (BUILD_SHARED_LIBS) + +install(TARGETS ceres + EXPORT CeresExport + RUNTIME DESTINATION bin + LIBRARY DESTINATION lib${LIB_SUFFIX} + ARCHIVE DESTINATION lib${LIB_SUFFIX}) + +if (BUILD_TESTING AND GFLAGS) + add_library(gtest gmock_gtest_all.cc gmock_main.cc) + if (BUILD_SHARED_LIBS) + # Define gtest-specific shared library flags for compilation. + append_target_property(gtest COMPILE_DEFINITIONS + GTEST_CREATE_SHARED_LIBRARY) + endif() + + add_library(test_util + evaluator_test_utils.cc + numeric_diff_test_utils.cc + test_util.cc) + + if (MINIGLOG) + # When using miniglog, it is compiled into Ceres, thus Ceres becomes + # the library against which other libraries should link for logging. + target_link_libraries(gtest ${GFLAGS_LIBRARIES} ceres) + target_link_libraries(test_util ceres gtest) + else (MINIGLOG) + target_link_libraries(gtest ${GFLAGS_LIBRARIES} ${GLOG_LIBRARIES}) + target_link_libraries(test_util ceres gtest ${GLOG_LIBRARIES}) + endif (MINIGLOG) + + macro (CERES_TEST NAME) + add_executable(${NAME}_test ${NAME}_test.cc) + target_link_libraries(${NAME}_test test_util ceres gtest) + if (BUILD_SHARED_LIBS) + # Define gtest-specific shared library flags for linking. + append_target_property(${NAME}_test COMPILE_DEFINITIONS + GTEST_LINKED_AS_SHARED_LIBRARY) + endif() + add_test(NAME ${NAME}_test + COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/${NAME}_test + --test_srcdir + ${Ceres_SOURCE_DIR}/data) + endmacro (CERES_TEST) + + ceres_test(array_utils) + ceres_test(autodiff) + ceres_test(autodiff_cost_function) + ceres_test(autodiff_local_parameterization) + ceres_test(block_jacobi_preconditioner) + ceres_test(block_random_access_dense_matrix) + ceres_test(block_random_access_diagonal_matrix) + ceres_test(block_random_access_sparse_matrix) + ceres_test(block_sparse_matrix) + ceres_test(c_api) + ceres_test(canonical_views_clustering) + ceres_test(compressed_col_sparse_matrix_utils) + ceres_test(compressed_row_sparse_matrix) + ceres_test(conditioned_cost_function) + ceres_test(conjugate_gradients_solver) + ceres_test(corrector) + ceres_test(cost_function_to_functor) + ceres_test(covariance) + ceres_test(cubic_interpolation) + ceres_test(dense_linear_solver) + ceres_test(dense_sparse_matrix) + ceres_test(detect_structure) + ceres_test(dogleg_strategy) + ceres_test(dynamic_autodiff_cost_function) + ceres_test(dynamic_compressed_row_sparse_matrix) + ceres_test(dynamic_numeric_diff_cost_function) + ceres_test(dynamic_sparse_normal_cholesky_solver) + ceres_test(dynamic_sparsity) + ceres_test(evaluator) + ceres_test(gradient_checker) + ceres_test(gradient_checking_cost_function) + ceres_test(gradient_problem) + ceres_test(gradient_problem_solver) + ceres_test(graph) + ceres_test(graph_algorithms) + ceres_test(householder_vector) + ceres_test(implicit_schur_complement) + ceres_test(inner_product_computer) + ceres_test(invert_psd_matrix) + ceres_test(is_close) + ceres_test(iterative_schur_complement_solver) + ceres_test(jet) + ceres_test(levenberg_marquardt_strategy) + ceres_test(line_search_minimizer) + ceres_test(line_search_preprocessor) + ceres_test(local_parameterization) + ceres_test(loss_function) + ceres_test(minimizer) + ceres_test(normal_prior) + ceres_test(numeric_diff_cost_function) + ceres_test(ordered_groups) + ceres_test(parameter_block) + ceres_test(parameter_block_ordering) + ceres_test(partitioned_matrix_view) + ceres_test(polynomial) + ceres_test(problem) + ceres_test(program) + ceres_test(reorder_program) + ceres_test(residual_block) + ceres_test(residual_block_utils) + ceres_test(rotation) + ceres_test(schur_complement_solver) + ceres_test(schur_eliminator) + ceres_test(single_linkage_clustering) + ceres_test(small_blas) + ceres_test(solver) + ceres_test(sparse_cholesky) + ceres_test(sparse_normal_cholesky_solver) + ceres_test(system) + ceres_test(triplet_sparse_matrix) + ceres_test(trust_region_minimizer) + ceres_test(trust_region_preprocessor) + ceres_test(visibility) + ceres_test(visibility_based_preconditioner) + + # Put the large end to end test last. + ceres_test(bundle_adjustment) + +endif (BUILD_TESTING AND GFLAGS) diff --git a/internal/ceres/array_utils.cc b/internal/ceres/array_utils.cc new file mode 100644 index 0000000..a165a1b --- /dev/null +++ b/internal/ceres/array_utils.cc @@ -0,0 +1,108 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/array_utils.h" + +#include +#include +#include +#include +#include +#include "ceres/fpclassify.h" +#include "ceres/stringprintf.h" +#include "ceres/types.h" +namespace ceres { +namespace internal { + +using std::string; + +bool IsArrayValid(const int size, const double* x) { + if (x != NULL) { + for (int i = 0; i < size; ++i) { + if (!IsFinite(x[i]) || (x[i] == kImpossibleValue)) { + return false; + } + } + } + return true; +} + +int FindInvalidValue(const int size, const double* x) { + if (x == NULL) { + return size; + } + + for (int i = 0; i < size; ++i) { + if (!IsFinite(x[i]) || (x[i] == kImpossibleValue)) { + return i; + } + } + + return size; +} + +void InvalidateArray(const int size, double* x) { + if (x != NULL) { + for (int i = 0; i < size; ++i) { + x[i] = kImpossibleValue; + } + } +} + +void AppendArrayToString(const int size, const double* x, string* result) { + for (int i = 0; i < size; ++i) { + if (x == NULL) { + StringAppendF(result, "Not Computed "); + } else { + if (x[i] == kImpossibleValue) { + StringAppendF(result, "Uninitialized "); + } else { + StringAppendF(result, "%12g ", x[i]); + } + } + } +} + +void MapValuesToContiguousRange(const int size, int* array) { + std::vector unique_values(array, array + size); + std::sort(unique_values.begin(), unique_values.end()); + unique_values.erase(std::unique(unique_values.begin(), + unique_values.end()), + unique_values.end()); + + for (int i = 0; i < size; ++i) { + array[i] = std::lower_bound(unique_values.begin(), + unique_values.end(), + array[i]) - unique_values.begin(); + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/array_utils.h b/internal/ceres/array_utils.h new file mode 100644 index 0000000..baf112e --- /dev/null +++ b/internal/ceres/array_utils.h @@ -0,0 +1,87 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Utility routines for validating arrays. +// +// These are useful for detecting two common class of errors. +// +// 1. Uninitialized memory - where the user for some reason did not +// compute part of an array, but the code expects it. +// +// 2. Numerical failure while computing the cost/residual/jacobian, +// e.g. NaN, infinities etc. This is particularly useful since the +// automatic differentiation code does computations that are not +// evident to the user and can silently generate hard to debug errors. + +#ifndef CERES_INTERNAL_ARRAY_UTILS_H_ +#define CERES_INTERNAL_ARRAY_UTILS_H_ + +#include +#include "ceres/internal/port.h" + +namespace ceres { +namespace internal { + +// Fill the array x with an impossible value that the user code is +// never expected to compute. +void InvalidateArray(int size, double* x); + +// Check if all the entries of the array x are valid, i.e. all the +// values in the array should be finite and none of them should be +// equal to the "impossible" value used by InvalidateArray. +bool IsArrayValid(int size, const double* x); + +// If the array contains an invalid value, return the index for it, +// otherwise return size. +int FindInvalidValue(const int size, const double* x); + +// Utility routine to print an array of doubles to a string. If the +// array pointer is NULL, it is treated as an array of zeros. +void AppendArrayToString(const int size, const double* x, std::string* result); + +// This routine takes an array of integer values, sorts and uniques +// them and then maps each value in the array to its position in the +// sorted+uniqued array. By doing this, if there are are k unique +// values in the array, each value is replaced by an integer in the +// range [0, k-1], while preserving their relative order. +// +// For example +// +// [1 0 3 5 0 1 5] +// +// gets mapped to +// +// [1 0 2 3 0 1 3] +void MapValuesToContiguousRange(int size, int* array); + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_ARRAY_UTILS_H_ diff --git a/internal/ceres/array_utils_test.cc b/internal/ceres/array_utils_test.cc new file mode 100644 index 0000000..77379d9 --- /dev/null +++ b/internal/ceres/array_utils_test.cc @@ -0,0 +1,124 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/array_utils.h" + +#include +#include +#include +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::vector; + +TEST(ArrayUtils, IsArrayValid) { + double x[3]; + x[0] = 0.0; + x[1] = 1.0; + x[2] = 2.0; + EXPECT_TRUE(IsArrayValid(3, x)); + x[1] = std::numeric_limits::infinity(); + EXPECT_FALSE(IsArrayValid(3, x)); + x[1] = std::numeric_limits::quiet_NaN(); + EXPECT_FALSE(IsArrayValid(3, x)); + x[1] = std::numeric_limits::signaling_NaN(); + EXPECT_FALSE(IsArrayValid(3, x)); + EXPECT_TRUE(IsArrayValid(1, NULL)); + InvalidateArray(3, x); + EXPECT_FALSE(IsArrayValid(3, x)); +} + +TEST(ArrayUtils, FindInvalidIndex) { + double x[3]; + x[0] = 0.0; + x[1] = 1.0; + x[2] = 2.0; + EXPECT_EQ(FindInvalidValue(3, x), 3); + x[1] = std::numeric_limits::infinity(); + EXPECT_EQ(FindInvalidValue(3, x), 1); + x[1] = std::numeric_limits::quiet_NaN(); + EXPECT_EQ(FindInvalidValue(3, x), 1); + x[1] = std::numeric_limits::signaling_NaN(); + EXPECT_EQ(FindInvalidValue(3, x), 1); + EXPECT_EQ(FindInvalidValue(1, NULL), 1); + InvalidateArray(3, x); + EXPECT_EQ(FindInvalidValue(3, x), 0); +} + +TEST(MapValuesToContiguousRange, ContiguousEntries) { + vector array; + array.push_back(0); + array.push_back(1); + vector expected = array; + MapValuesToContiguousRange(array.size(), &array[0]); + EXPECT_EQ(array, expected); + array.clear(); + + array.push_back(1); + array.push_back(0); + expected = array; + MapValuesToContiguousRange(array.size(), &array[0]); + EXPECT_EQ(array, expected); +} + +TEST(MapValuesToContiguousRange, NonContiguousEntries) { + vector array; + array.push_back(0); + array.push_back(2); + vector expected; + expected.push_back(0); + expected.push_back(1); + MapValuesToContiguousRange(array.size(), &array[0]); + EXPECT_EQ(array, expected); +} + +TEST(MapValuesToContiguousRange, NonContiguousRepeatingEntries) { + vector array; + array.push_back(3); + array.push_back(1); + array.push_back(0); + array.push_back(0); + array.push_back(0); + array.push_back(5); + vector expected; + expected.push_back(2); + expected.push_back(1); + expected.push_back(0); + expected.push_back(0); + expected.push_back(0); + expected.push_back(3); + MapValuesToContiguousRange(array.size(), &array[0]); + EXPECT_EQ(array, expected); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/autodiff_cost_function_test.cc b/internal/ceres/autodiff_cost_function_test.cc new file mode 100644 index 0000000..d14fb82 --- /dev/null +++ b/internal/ceres/autodiff_cost_function_test.cc @@ -0,0 +1,172 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/autodiff_cost_function.h" + +#include + +#include "gtest/gtest.h" +#include "ceres/cost_function.h" +#include "ceres/array_utils.h" + +namespace ceres { +namespace internal { + +class BinaryScalarCost { + public: + explicit BinaryScalarCost(double a): a_(a) {} + template + bool operator()(const T* const x, const T* const y, + T* cost) const { + cost[0] = x[0] * y[0] + x[1] * y[1] - T(a_); + return true; + } + private: + double a_; +}; + +TEST(AutodiffCostFunction, BilinearDifferentiationTest) { + CostFunction* cost_function = + new AutoDiffCostFunction( + new BinaryScalarCost(1.0)); + + double** parameters = new double*[2]; + parameters[0] = new double[2]; + parameters[1] = new double[2]; + + parameters[0][0] = 1; + parameters[0][1] = 2; + + parameters[1][0] = 3; + parameters[1][1] = 4; + + double** jacobians = new double*[2]; + jacobians[0] = new double[2]; + jacobians[1] = new double[2]; + + double residuals = 0.0; + + cost_function->Evaluate(parameters, &residuals, NULL); + EXPECT_EQ(10.0, residuals); + cost_function->Evaluate(parameters, &residuals, jacobians); + + EXPECT_EQ(3, jacobians[0][0]); + EXPECT_EQ(4, jacobians[0][1]); + EXPECT_EQ(1, jacobians[1][0]); + EXPECT_EQ(2, jacobians[1][1]); + + delete[] jacobians[0]; + delete[] jacobians[1]; + delete[] parameters[0]; + delete[] parameters[1]; + delete[] jacobians; + delete[] parameters; + delete cost_function; +} + +struct TenParameterCost { + template + bool operator()(const T* const x0, + const T* const x1, + const T* const x2, + const T* const x3, + const T* const x4, + const T* const x5, + const T* const x6, + const T* const x7, + const T* const x8, + const T* const x9, + T* cost) const { + cost[0] = *x0 + *x1 + *x2 + *x3 + *x4 + *x5 + *x6 + *x7 + *x8 + *x9; + return true; + } +}; + +TEST(AutodiffCostFunction, ManyParameterAutodiffInstantiates) { + CostFunction* cost_function = + new AutoDiffCostFunction< + TenParameterCost, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1>( + new TenParameterCost); + + double** parameters = new double*[10]; + double** jacobians = new double*[10]; + for (int i = 0; i < 10; ++i) { + parameters[i] = new double[1]; + parameters[i][0] = i; + jacobians[i] = new double[1]; + } + + double residuals = 0.0; + + cost_function->Evaluate(parameters, &residuals, NULL); + EXPECT_EQ(45.0, residuals); + + cost_function->Evaluate(parameters, &residuals, jacobians); + EXPECT_EQ(residuals, 45.0); + for (int i = 0; i < 10; ++i) { + EXPECT_EQ(1.0, jacobians[i][0]); + } + + for (int i = 0; i < 10; ++i) { + delete[] jacobians[i]; + delete[] parameters[i]; + } + delete[] jacobians; + delete[] parameters; + delete cost_function; +} + +struct OnlyFillsOneOutputFunctor { + template + bool operator()(const T* x, T* output) const { + output[0] = x[0]; + return true; + } +}; + +TEST(AutoDiffCostFunction, PartiallyFilledResidualShouldFailEvaluation) { + double parameter = 1.0; + double jacobian[2]; + double residuals[2]; + double* parameters[] = {¶meter}; + double* jacobians[] = {jacobian}; + + scoped_ptr cost_function( + new AutoDiffCostFunction( + new OnlyFillsOneOutputFunctor)); + InvalidateArray(2, jacobian); + InvalidateArray(2, residuals); + EXPECT_TRUE(cost_function->Evaluate(parameters, residuals, jacobians)); + EXPECT_FALSE(IsArrayValid(2, jacobian)); + EXPECT_FALSE(IsArrayValid(2, residuals)); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/autodiff_local_parameterization_test.cc b/internal/ceres/autodiff_local_parameterization_test.cc new file mode 100644 index 0000000..2a0d2f0 --- /dev/null +++ b/internal/ceres/autodiff_local_parameterization_test.cc @@ -0,0 +1,224 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include +#include "ceres/autodiff_local_parameterization.h" +#include "ceres/fpclassify.h" +#include "ceres/local_parameterization.h" +#include "ceres/rotation.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +struct IdentityPlus { + template + bool operator()(const T* x, const T* delta, T* x_plus_delta) const { + for (int i = 0; i < 3; ++i) { + x_plus_delta[i] = x[i] + delta[i]; + } + return true; + } +}; + +TEST(AutoDiffLocalParameterizationTest, IdentityParameterization) { + AutoDiffLocalParameterization + parameterization; + + double x[3] = {1.0, 2.0, 3.0}; + double delta[3] = {0.0, 1.0, 2.0}; + double x_plus_delta[3] = {0.0, 0.0, 0.0}; + parameterization.Plus(x, delta, x_plus_delta); + + EXPECT_EQ(x_plus_delta[0], 1.0); + EXPECT_EQ(x_plus_delta[1], 3.0); + EXPECT_EQ(x_plus_delta[2], 5.0); + + double jacobian[9]; + parameterization.ComputeJacobian(x, jacobian); + int k = 0; + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < 3; ++j, ++k) { + EXPECT_EQ(jacobian[k], (i == j) ? 1.0 : 0.0); + } + } +} + +struct ScaledPlus { + explicit ScaledPlus(const double &scale_factor) + : scale_factor_(scale_factor) + {} + + template + bool operator()(const T* x, const T* delta, T* x_plus_delta) const { + for (int i = 0; i < 3; ++i) { + x_plus_delta[i] = x[i] + T(scale_factor_) * delta[i]; + } + return true; + } + + const double scale_factor_; +}; + +TEST(AutoDiffLocalParameterizationTest, ScaledParameterization) { + const double kTolerance = 1e-14; + + AutoDiffLocalParameterization + parameterization(new ScaledPlus(1.2345)); + + double x[3] = {1.0, 2.0, 3.0}; + double delta[3] = {0.0, 1.0, 2.0}; + double x_plus_delta[3] = {0.0, 0.0, 0.0}; + parameterization.Plus(x, delta, x_plus_delta); + + EXPECT_NEAR(x_plus_delta[0], 1.0, kTolerance); + EXPECT_NEAR(x_plus_delta[1], 3.2345, kTolerance); + EXPECT_NEAR(x_plus_delta[2], 5.469, kTolerance); + + double jacobian[9]; + parameterization.ComputeJacobian(x, jacobian); + int k = 0; + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < 3; ++j, ++k) { + EXPECT_NEAR(jacobian[k], (i == j) ? 1.2345 : 0.0, kTolerance); + } + } +} + +struct QuaternionPlus { + template + bool operator()(const T* x, const T* delta, T* x_plus_delta) const { + const T squared_norm_delta = + delta[0] * delta[0] + delta[1] * delta[1] + delta[2] * delta[2]; + + T q_delta[4]; + if (squared_norm_delta > T(0.0)) { + T norm_delta = sqrt(squared_norm_delta); + const T sin_delta_by_delta = sin(norm_delta) / norm_delta; + q_delta[0] = cos(norm_delta); + q_delta[1] = sin_delta_by_delta * delta[0]; + q_delta[2] = sin_delta_by_delta * delta[1]; + q_delta[3] = sin_delta_by_delta * delta[2]; + } else { + // We do not just use q_delta = [1,0,0,0] here because that is a + // constant and when used for automatic differentiation will + // lead to a zero derivative. Instead we take a first order + // approximation and evaluate it at zero. + q_delta[0] = T(1.0); + q_delta[1] = delta[0]; + q_delta[2] = delta[1]; + q_delta[3] = delta[2]; + } + + QuaternionProduct(q_delta, x, x_plus_delta); + return true; + } +}; + +void QuaternionParameterizationTestHelper(const double* x, + const double* delta) { + const double kTolerance = 1e-14; + double x_plus_delta_ref[4] = {0.0, 0.0, 0.0, 0.0}; + double jacobian_ref[12]; + + + QuaternionParameterization ref_parameterization; + ref_parameterization.Plus(x, delta, x_plus_delta_ref); + ref_parameterization.ComputeJacobian(x, jacobian_ref); + + double x_plus_delta[4] = {0.0, 0.0, 0.0, 0.0}; + double jacobian[12]; + AutoDiffLocalParameterization parameterization; + parameterization.Plus(x, delta, x_plus_delta); + parameterization.ComputeJacobian(x, jacobian); + + for (int i = 0; i < 4; ++i) { + EXPECT_NEAR(x_plus_delta[i], x_plus_delta_ref[i], kTolerance); + } + + const double x_plus_delta_norm = + sqrt(x_plus_delta[0] * x_plus_delta[0] + + x_plus_delta[1] * x_plus_delta[1] + + x_plus_delta[2] * x_plus_delta[2] + + x_plus_delta[3] * x_plus_delta[3]); + + EXPECT_NEAR(x_plus_delta_norm, 1.0, kTolerance); + + for (int i = 0; i < 12; ++i) { + EXPECT_TRUE(IsFinite(jacobian[i])); + EXPECT_NEAR(jacobian[i], jacobian_ref[i], kTolerance) + << "Jacobian mismatch: i = " << i + << "\n Expected \n" << ConstMatrixRef(jacobian_ref, 4, 3) + << "\n Actual \n" << ConstMatrixRef(jacobian, 4, 3); + } +} + +TEST(AutoDiffLocalParameterization, QuaternionParameterizationZeroTest) { + double x[4] = {0.5, 0.5, 0.5, 0.5}; + double delta[3] = {0.0, 0.0, 0.0}; + QuaternionParameterizationTestHelper(x, delta); +} + + +TEST(AutoDiffLocalParameterization, QuaternionParameterizationNearZeroTest) { + double x[4] = {0.52, 0.25, 0.15, 0.45}; + double norm_x = sqrt(x[0] * x[0] + + x[1] * x[1] + + x[2] * x[2] + + x[3] * x[3]); + for (int i = 0; i < 4; ++i) { + x[i] = x[i] / norm_x; + } + + double delta[3] = {0.24, 0.15, 0.10}; + for (int i = 0; i < 3; ++i) { + delta[i] = delta[i] * 1e-14; + } + + QuaternionParameterizationTestHelper(x, delta); +} + +TEST(AutoDiffLocalParameterization, QuaternionParameterizationNonZeroTest) { + double x[4] = {0.52, 0.25, 0.15, 0.45}; + double norm_x = sqrt(x[0] * x[0] + + x[1] * x[1] + + x[2] * x[2] + + x[3] * x[3]); + + for (int i = 0; i < 4; ++i) { + x[i] = x[i] / norm_x; + } + + double delta[3] = {0.24, 0.15, 0.10}; + QuaternionParameterizationTestHelper(x, delta); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/autodiff_test.cc b/internal/ceres/autodiff_test.cc new file mode 100644 index 0000000..20f4437 --- /dev/null +++ b/internal/ceres/autodiff_test.cc @@ -0,0 +1,677 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/internal/autodiff.h" + +#include "gtest/gtest.h" +#include "ceres/random.h" + +namespace ceres { +namespace internal { + +template inline +T &RowMajorAccess(T *base, int rows, int cols, int i, int j) { + return base[cols * i + j]; +} + +// Do (symmetric) finite differencing using the given function object 'b' of +// type 'B' and scalar type 'T' with step size 'del'. +// +// The type B should have a signature +// +// bool operator()(T const *, T *) const; +// +// which maps a vector of parameters to a vector of outputs. +template inline +bool SymmetricDiff(const B& b, + const T par[N], + T del, // step size. + T fun[M], + T jac[M * N]) { // row-major. + if (!b(par, fun)) { + return false; + } + + // Temporary parameter vector. + T tmp_par[N]; + for (int j = 0; j < N; ++j) { + tmp_par[j] = par[j]; + } + + // For each dimension, we do one forward step and one backward step in + // parameter space, and store the output vector vectors in these vectors. + T fwd_fun[M]; + T bwd_fun[M]; + + for (int j = 0; j < N; ++j) { + // Forward step. + tmp_par[j] = par[j] + del; + if (!b(tmp_par, fwd_fun)) { + return false; + } + + // Backward step. + tmp_par[j] = par[j] - del; + if (!b(tmp_par, bwd_fun)) { + return false; + } + + // Symmetric differencing: + // f'(a) = (f(a + h) - f(a - h)) / (2 h) + for (int i = 0; i < M; ++i) { + RowMajorAccess(jac, M, N, i, j) = + (fwd_fun[i] - bwd_fun[i]) / (T(2) * del); + } + + // Restore our temporary vector. + tmp_par[j] = par[j]; + } + + return true; +} + +template inline +void QuaternionToScaledRotation(A const q[4], A R[3 * 3]) { + // Make convenient names for elements of q. + A a = q[0]; + A b = q[1]; + A c = q[2]; + A d = q[3]; + // This is not to eliminate common sub-expression, but to + // make the lines shorter so that they fit in 80 columns! + A aa = a*a; + A ab = a*b; + A ac = a*c; + A ad = a*d; + A bb = b*b; + A bc = b*c; + A bd = b*d; + A cc = c*c; + A cd = c*d; + A dd = d*d; +#define R(i, j) RowMajorAccess(R, 3, 3, (i), (j)) + R(0, 0) = aa+bb-cc-dd; R(0, 1) = A(2)*(bc-ad); R(0, 2) = A(2)*(ac+bd); // NOLINT + R(1, 0) = A(2)*(ad+bc); R(1, 1) = aa-bb+cc-dd; R(1, 2) = A(2)*(cd-ab); // NOLINT + R(2, 0) = A(2)*(bd-ac); R(2, 1) = A(2)*(ab+cd); R(2, 2) = aa-bb-cc+dd; // NOLINT +#undef R +} + +// A structure for projecting a 3x4 camera matrix and a +// homogeneous 3D point, to a 2D inhomogeneous point. +struct Projective { + // Function that takes P and X as separate vectors: + // P, X -> x + template + bool operator()(A const P[12], A const X[4], A x[2]) const { + A PX[3]; + for (int i = 0; i < 3; ++i) { + PX[i] = RowMajorAccess(P, 3, 4, i, 0) * X[0] + + RowMajorAccess(P, 3, 4, i, 1) * X[1] + + RowMajorAccess(P, 3, 4, i, 2) * X[2] + + RowMajorAccess(P, 3, 4, i, 3) * X[3]; + } + if (PX[2] != 0.0) { + x[0] = PX[0] / PX[2]; + x[1] = PX[1] / PX[2]; + return true; + } + return false; + } + + // Version that takes P and X packed in one vector: + // + // (P, X) -> x + // + template + bool operator()(A const P_X[12 + 4], A x[2]) const { + return operator()(P_X + 0, P_X + 12, x); + } +}; + +// Test projective camera model projector. +TEST(AutoDiff, ProjectiveCameraModel) { + srand(5); + double const tol = 1e-10; // floating-point tolerance. + double const del = 1e-4; // finite-difference step. + double const err = 1e-6; // finite-difference tolerance. + + Projective b; + + // Make random P and X, in a single vector. + double PX[12 + 4]; + for (int i = 0; i < 12 + 4; ++i) { + PX[i] = RandDouble(); + } + + // Handy names for the P and X parts. + double *P = PX + 0; + double *X = PX + 12; + + // Apply the mapping, to get image point b_x. + double b_x[2]; + b(P, X, b_x); + + // Use finite differencing to estimate the Jacobian. + double fd_x[2]; + double fd_J[2 * (12 + 4)]; + ASSERT_TRUE((SymmetricDiff(b, PX, del, + fd_x, fd_J))); + + for (int i = 0; i < 2; ++i) { + ASSERT_NEAR(fd_x[i], b_x[i], tol); + } + + // Use automatic differentiation to compute the Jacobian. + double ad_x1[2]; + double J_PX[2 * (12 + 4)]; + { + double *parameters[] = { PX }; + double *jacobians[] = { J_PX }; + ASSERT_TRUE((AutoDiff::Differentiate( + b, parameters, 2, ad_x1, jacobians))); + + for (int i = 0; i < 2; ++i) { + ASSERT_NEAR(ad_x1[i], b_x[i], tol); + } + } + + // Use automatic differentiation (again), with two arguments. + { + double ad_x2[2]; + double J_P[2 * 12]; + double J_X[2 * 4]; + double *parameters[] = { P, X }; + double *jacobians[] = { J_P, J_X }; + ASSERT_TRUE((AutoDiff::Differentiate( + b, parameters, 2, ad_x2, jacobians))); + + for (int i = 0; i < 2; ++i) { + ASSERT_NEAR(ad_x2[i], b_x[i], tol); + } + + // Now compare the jacobians we got. + for (int i = 0; i < 2; ++i) { + for (int j = 0; j < 12 + 4; ++j) { + ASSERT_NEAR(J_PX[(12 + 4) * i + j], fd_J[(12 + 4) * i + j], err); + } + + for (int j = 0; j < 12; ++j) { + ASSERT_NEAR(J_PX[(12 + 4) * i + j], J_P[12 * i + j], tol); + } + for (int j = 0; j < 4; ++j) { + ASSERT_NEAR(J_PX[(12 + 4) * i + 12 + j], J_X[4 * i + j], tol); + } + } + } +} + +// Object to implement the projection by a calibrated camera. +struct Metric { + // The mapping is + // + // q, c, X -> x = dehomg(R(q) (X - c)) + // + // where q is a quaternion and c is the center of projection. + // + // This function takes three input vectors. + template + bool operator()(A const q[4], A const c[3], A const X[3], A x[2]) const { + A R[3 * 3]; + QuaternionToScaledRotation(q, R); + + // Convert the quaternion mapping all the way to projective matrix. + A P[3 * 4]; + + // Set P(:, 1:3) = R + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < 3; ++j) { + RowMajorAccess(P, 3, 4, i, j) = RowMajorAccess(R, 3, 3, i, j); + } + } + + // Set P(:, 4) = - R c + for (int i = 0; i < 3; ++i) { + RowMajorAccess(P, 3, 4, i, 3) = + - (RowMajorAccess(R, 3, 3, i, 0) * c[0] + + RowMajorAccess(R, 3, 3, i, 1) * c[1] + + RowMajorAccess(R, 3, 3, i, 2) * c[2]); + } + + A X1[4] = { X[0], X[1], X[2], A(1) }; + Projective p; + return p(P, X1, x); + } + + // A version that takes a single vector. + template + bool operator()(A const q_c_X[4 + 3 + 3], A x[2]) const { + return operator()(q_c_X, q_c_X + 4, q_c_X + 4 + 3, x); + } +}; + +// This test is similar in structure to the previous one. +TEST(AutoDiff, Metric) { + srand(5); + double const tol = 1e-10; // floating-point tolerance. + double const del = 1e-4; // finite-difference step. + double const err = 1e-5; // finite-difference tolerance. + + Metric b; + + // Make random parameter vector. + double qcX[4 + 3 + 3]; + for (int i = 0; i < 4 + 3 + 3; ++i) + qcX[i] = RandDouble(); + + // Handy names. + double *q = qcX; + double *c = qcX + 4; + double *X = qcX + 4 + 3; + + // Compute projection, b_x. + double b_x[2]; + ASSERT_TRUE(b(q, c, X, b_x)); + + // Finite differencing estimate of Jacobian. + double fd_x[2]; + double fd_J[2 * (4 + 3 + 3)]; + ASSERT_TRUE((SymmetricDiff(b, qcX, del, + fd_x, fd_J))); + + for (int i = 0; i < 2; ++i) { + ASSERT_NEAR(fd_x[i], b_x[i], tol); + } + + // Automatic differentiation. + double ad_x[2]; + double J_q[2 * 4]; + double J_c[2 * 3]; + double J_X[2 * 3]; + double *parameters[] = { q, c, X }; + double *jacobians[] = { J_q, J_c, J_X }; + ASSERT_TRUE((AutoDiff::Differentiate( + b, parameters, 2, ad_x, jacobians))); + + for (int i = 0; i < 2; ++i) { + ASSERT_NEAR(ad_x[i], b_x[i], tol); + } + + // Compare the pieces. + for (int i = 0; i < 2; ++i) { + for (int j = 0; j < 4; ++j) { + ASSERT_NEAR(J_q[4 * i + j], fd_J[(4 + 3 + 3) * i + j], err); + } + for (int j = 0; j < 3; ++j) { + ASSERT_NEAR(J_c[3 * i + j], fd_J[(4 + 3 + 3) * i + j + 4], err); + } + for (int j = 0; j < 3; ++j) { + ASSERT_NEAR(J_X[3 * i + j], fd_J[(4 + 3 + 3) * i + j + 4 + 3], err); + } + } +} + +struct VaryingResidualFunctor { + template + bool operator()(const T x[2], T* y) const { + for (int i = 0; i < num_residuals; ++i) { + y[i] = T(i) * x[0] * x[1] * x[1]; + } + return true; + } + + int num_residuals; +}; + +TEST(AutoDiff, VaryingNumberOfResidualsForOneCostFunctorType) { + double x[2] = { 1.0, 5.5 }; + double *parameters[] = { x }; + const int kMaxResiduals = 10; + double J_x[2 * kMaxResiduals]; + double residuals[kMaxResiduals]; + double *jacobians[] = { J_x }; + + // Use a single functor, but tweak it to produce different numbers of + // residuals. + VaryingResidualFunctor functor; + + for (int num_residuals = 1; num_residuals < kMaxResiduals; ++num_residuals) { + // Tweak the number of residuals to produce. + functor.num_residuals = num_residuals; + + // Run autodiff with the new number of residuals. + ASSERT_TRUE((AutoDiff::Differentiate( + functor, parameters, num_residuals, residuals, jacobians))); + + const double kTolerance = 1e-14; + for (int i = 0; i < num_residuals; ++i) { + EXPECT_NEAR(J_x[2 * i + 0], i * x[1] * x[1], kTolerance) << "i: " << i; + EXPECT_NEAR(J_x[2 * i + 1], 2 * i * x[0] * x[1], kTolerance) + << "i: " << i; + } + } +} + +struct Residual1Param { + template + bool operator()(const T* x0, T* y) const { + y[0] = *x0; + return true; + } +}; + +struct Residual2Param { + template + bool operator()(const T* x0, const T* x1, T* y) const { + y[0] = *x0 + pow(*x1, 2); + return true; + } +}; + +struct Residual3Param { + template + bool operator()(const T* x0, const T* x1, const T* x2, T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3); + return true; + } +}; + +struct Residual4Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4); + return true; + } +}; + +struct Residual5Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5); + return true; + } +}; + +struct Residual6Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + const T* x5, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5) + + pow(*x5, 6); + return true; + } +}; + +struct Residual7Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + const T* x5, + const T* x6, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5) + + pow(*x5, 6) + pow(*x6, 7); + return true; + } +}; + +struct Residual8Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + const T* x5, + const T* x6, + const T* x7, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5) + + pow(*x5, 6) + pow(*x6, 7) + pow(*x7, 8); + return true; + } +}; + +struct Residual9Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + const T* x5, + const T* x6, + const T* x7, + const T* x8, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5) + + pow(*x5, 6) + pow(*x6, 7) + pow(*x7, 8) + pow(*x8, 9); + return true; + } +}; + +struct Residual10Param { + template + bool operator()(const T* x0, + const T* x1, + const T* x2, + const T* x3, + const T* x4, + const T* x5, + const T* x6, + const T* x7, + const T* x8, + const T* x9, + T* y) const { + y[0] = *x0 + pow(*x1, 2) + pow(*x2, 3) + pow(*x3, 4) + pow(*x4, 5) + + pow(*x5, 6) + pow(*x6, 7) + pow(*x7, 8) + pow(*x8, 9) + pow(*x9, 10); + return true; + } +}; + +TEST(AutoDiff, VariadicAutoDiff) { + double x[10]; + double residual = 0; + double* parameters[10]; + double jacobian_values[10]; + double* jacobians[10]; + + for (int i = 0; i < 10; ++i) { + x[i] = 2.0; + parameters[i] = x + i; + jacobians[i] = jacobian_values + i; + } + + { + Residual1Param functor; + int num_variables = 1; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual2Param functor; + int num_variables = 2; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual3Param functor; + int num_variables = 3; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual4Param functor; + int num_variables = 4; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual5Param functor; + int num_variables = 5; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual6Param functor; + int num_variables = 6; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual7Param functor; + int num_variables = 7; + EXPECT_TRUE((AutoDiff::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual8Param functor; + int num_variables = 8; + EXPECT_TRUE((AutoDiff< + Residual8Param, + double, 1, 1, 1, 1, 1, 1, 1, 1>::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual9Param functor; + int num_variables = 9; + EXPECT_TRUE((AutoDiff< + Residual9Param, + double, + 1, 1, 1, 1, 1, 1, 1, 1, 1>::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } + + { + Residual10Param functor; + int num_variables = 10; + EXPECT_TRUE((AutoDiff< + Residual10Param, + double, + 1, 1, 1, 1, 1, 1, 1, 1, 1, 1>::Differentiate( + functor, parameters, 1, &residual, jacobians))); + EXPECT_EQ(residual, pow(2, num_variables + 1) - 2); + for (int i = 0; i < num_variables; ++i) { + EXPECT_EQ(jacobian_values[i], (i + 1) * pow(2, i)); + } + } +} + +// This is fragile test that triggers the alignment bug on +// i686-apple-darwin10-llvm-g++-4.2 (GCC) 4.2.1. It is quite possible, +// that other combinations of operating system + compiler will +// re-arrange the operations in this test. +// +// But this is the best (and only) way we know of to trigger this +// problem for now. A more robust solution that guarantees the +// alignment of Eigen types used for automatic differentiation would +// be nice. +TEST(AutoDiff, AlignedAllocationTest) { + // This int is needed to allocate 16 bits on the stack, so that the + // next allocation is not aligned by default. + char y = 0; + + // This is needed to prevent the compiler from optimizing y out of + // this function. + y += 1; + + typedef Jet JetT; + FixedArray x(3); + + // Need this to makes sure that x does not get optimized out. + x[0] = x[0] + JetT(1.0); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/blas.cc b/internal/ceres/blas.cc new file mode 100644 index 0000000..3ba63bb --- /dev/null +++ b/internal/ceres/blas.cc @@ -0,0 +1,81 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/blas.h" +#include "ceres/internal/port.h" +#include "glog/logging.h" + +#ifndef CERES_NO_LAPACK +extern "C" void dsyrk_(char* uplo, + char* trans, + int* n, + int* k, + double* alpha, + double* a, + int* lda, + double* beta, + double* c, + int* ldc); +#endif + +namespace ceres { +namespace internal { + +void BLAS::SymmetricRankKUpdate(int num_rows, + int num_cols, + const double* a, + bool transpose, + double alpha, + double beta, + double* c) { +#ifdef CERES_NO_LAPACK + LOG(FATAL) << "Ceres was built without a BLAS library."; +#else + char uplo = 'L'; + char trans = transpose ? 'T' : 'N'; + int n = transpose ? num_cols : num_rows; + int k = transpose ? num_rows : num_cols; + int lda = k; + int ldc = n; + dsyrk_(&uplo, + &trans, + &n, + &k, + &alpha, + const_cast(a), + &lda, + &beta, + c, + &ldc); +#endif +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/blas.h b/internal/ceres/blas.h new file mode 100644 index 0000000..a43301c --- /dev/null +++ b/internal/ceres/blas.h @@ -0,0 +1,57 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Wrapper functions around BLAS functions. + +#ifndef CERES_INTERNAL_BLAS_H_ +#define CERES_INTERNAL_BLAS_H_ + +namespace ceres { +namespace internal { + +class BLAS { + public: + // transpose = true : c = alpha * a'a + beta * c; + // transpose = false : c = alpha * aa' + beta * c; + // + // Assumes column major matrices. + static void SymmetricRankKUpdate(int num_rows, + int num_cols, + const double* a, + bool transpose, + double alpha, + double beta, + double* c); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLAS_H_ diff --git a/internal/ceres/block_evaluate_preparer.cc b/internal/ceres/block_evaluate_preparer.cc new file mode 100644 index 0000000..59c0d3e --- /dev/null +++ b/internal/ceres/block_evaluate_preparer.cc @@ -0,0 +1,83 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/block_evaluate_preparer.h" + +#include +#include "ceres/block_sparse_matrix.h" +#include "ceres/casts.h" +#include "ceres/parameter_block.h" +#include "ceres/residual_block.h" +#include "ceres/sparse_matrix.h" + +namespace ceres { +namespace internal { + +void BlockEvaluatePreparer::Init(int const* const* jacobian_layout, + int max_derivatives_per_residual_block) { + jacobian_layout_ = jacobian_layout; + scratch_evaluate_preparer_.Init(max_derivatives_per_residual_block); +} + +// Point the jacobian blocks directly into the block sparse matrix. +void BlockEvaluatePreparer::Prepare(const ResidualBlock* residual_block, + int residual_block_index, + SparseMatrix* jacobian, + double** jacobians) { + // If the overall jacobian is not available, use the scratch space. + if (jacobian == NULL) { + scratch_evaluate_preparer_.Prepare(residual_block, + residual_block_index, + jacobian, + jacobians); + return; + } + + double* jacobian_values = + down_cast(jacobian)->mutable_values(); + + const int* jacobian_block_offset = jacobian_layout_[residual_block_index]; + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + for (int j = 0; j < num_parameter_blocks; ++j) { + if (!residual_block->parameter_blocks()[j]->IsConstant()) { + jacobians[j] = jacobian_values + *jacobian_block_offset; + + // The jacobian_block_offset can't be indexed with 'j' since the code + // that creates the layout strips out any blocks for inactive + // parameters. Instead, bump the pointer for active parameters only. + jacobian_block_offset++; + } else { + jacobians[j] = NULL; + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_evaluate_preparer.h b/internal/ceres/block_evaluate_preparer.h new file mode 100644 index 0000000..4378689 --- /dev/null +++ b/internal/ceres/block_evaluate_preparer.h @@ -0,0 +1,77 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A evaluate preparer which puts jacobian the evaluated jacobian blocks +// directly into their final resting place in an overall block sparse matrix. +// The evaluator takes care to avoid evaluating the jacobian for fixed +// parameters. + +#ifndef CERES_INTERNAL_BLOCK_EVALUATE_PREPARER_H_ +#define CERES_INTERNAL_BLOCK_EVALUATE_PREPARER_H_ + +#include "ceres/scratch_evaluate_preparer.h" + +namespace ceres { +namespace internal { + +class ResidualBlock; +class SparseMatrix; + +class BlockEvaluatePreparer { + public: + // Using Init() instead of a constructor allows for allocating this structure + // with new[]. This is because C++ doesn't allow passing arguments to objects + // constructed with new[] (as opposed to plain 'new'). + void Init(int const* const* jacobian_layout, + int max_derivatives_per_residual_block); + + // EvaluatePreparer interface + + // Point the jacobian blocks directly into the block sparse matrix, if + // jacobian is non-null. Otherwise, uses an internal per-thread buffer to + // store the jacobians temporarily. + void Prepare(const ResidualBlock* residual_block, + int residual_block_index, + SparseMatrix* jacobian, + double** jacobians); + + private: + int const* const* jacobian_layout_; + + // For the case that the overall jacobian is not available, but the + // individual jacobians are requested, use a pass-through scratch evaluate + // preparer. + ScratchEvaluatePreparer scratch_evaluate_preparer_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_EVALUATE_PREPARER_H_ diff --git a/internal/ceres/block_jacobi_preconditioner.cc b/internal/ceres/block_jacobi_preconditioner.cc new file mode 100644 index 0000000..22d4b35 --- /dev/null +++ b/internal/ceres/block_jacobi_preconditioner.cc @@ -0,0 +1,106 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/block_jacobi_preconditioner.h" + +#include "ceres/block_sparse_matrix.h" +#include "ceres/block_structure.h" +#include "ceres/block_random_access_diagonal_matrix.h" +#include "ceres/casts.h" +#include "ceres/integral_types.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +BlockJacobiPreconditioner::BlockJacobiPreconditioner( + const BlockSparseMatrix& A) { + const CompressedRowBlockStructure* bs = A.block_structure(); + std::vector blocks(bs->cols.size()); + for (int i = 0; i < blocks.size(); ++i) { + blocks[i] = bs->cols[i].size; + } + + m_.reset(new BlockRandomAccessDiagonalMatrix(blocks)); +} + +BlockJacobiPreconditioner::~BlockJacobiPreconditioner() {} + +bool BlockJacobiPreconditioner::UpdateImpl(const BlockSparseMatrix& A, + const double* D) { + const CompressedRowBlockStructure* bs = A.block_structure(); + const double* values = A.values(); + m_->SetZero(); + for (int i = 0; i < bs->rows.size(); ++i) { + const int row_block_size = bs->rows[i].block.size; + const std::vector& cells = bs->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + const int block_id = cells[j].block_id; + const int col_block_size = bs->cols[block_id].size; + + int r, c, row_stride, col_stride; + CellInfo* cell_info = m_->GetCell(block_id, block_id, + &r, &c, + &row_stride, &col_stride); + MatrixRef m(cell_info->values, row_stride, col_stride); + ConstMatrixRef b(values + cells[j].position, + row_block_size, + col_block_size); + m.block(r, c, col_block_size, col_block_size) += b.transpose() * b; + } + } + + if (D != NULL) { + // Add the diagonal. + int position = 0; + for (int i = 0; i < bs->cols.size(); ++i) { + const int block_size = bs->cols[i].size; + int r, c, row_stride, col_stride; + CellInfo* cell_info = m_->GetCell(i, i, + &r, &c, + &row_stride, &col_stride); + MatrixRef m(cell_info->values, row_stride, col_stride); + m.block(r, c, block_size, block_size).diagonal() += + ConstVectorRef(D + position, block_size).array().square().matrix(); + position += block_size; + } + } + + m_->Invert(); + return true; +} + +void BlockJacobiPreconditioner::RightMultiply(const double* x, + double* y) const { + m_->RightMultiply(x, y); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_jacobi_preconditioner.h b/internal/ceres/block_jacobi_preconditioner.h new file mode 100644 index 0000000..0541db5 --- /dev/null +++ b/internal/ceres/block_jacobi_preconditioner.h @@ -0,0 +1,75 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#ifndef CERES_INTERNAL_BLOCK_JACOBI_PRECONDITIONER_H_ +#define CERES_INTERNAL_BLOCK_JACOBI_PRECONDITIONER_H_ + +#include "ceres/block_random_access_diagonal_matrix.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/preconditioner.h" + +namespace ceres { +namespace internal { + +class BlockSparseMatrix; +struct CompressedRowBlockStructure; + +// A block Jacobi preconditioner. This is intended for use with +// conjugate gradients, or other iterative symmetric solvers. To use +// the preconditioner, create one by passing a BlockSparseMatrix "A" +// to the constructor. This fixes the sparsity pattern to the pattern +// of the matrix A^TA. +// +// Before each use of the preconditioner in a solve with conjugate gradients, +// update the matrix by running Update(A, D). The values of the matrix A are +// inspected to construct the preconditioner. The vector D is applied as the +// D^TD diagonal term. +class BlockJacobiPreconditioner : public BlockSparseMatrixPreconditioner { + public: + // A must remain valid while the BlockJacobiPreconditioner is. + explicit BlockJacobiPreconditioner(const BlockSparseMatrix& A); + virtual ~BlockJacobiPreconditioner(); + + // Preconditioner interface + virtual void RightMultiply(const double* x, double* y) const; + virtual int num_rows() const { return m_->num_rows(); } + virtual int num_cols() const { return m_->num_rows(); } + const BlockRandomAccessDiagonalMatrix& matrix() const { return *m_; } + + private: + virtual bool UpdateImpl(const BlockSparseMatrix& A, const double* D); + + scoped_ptr m_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_JACOBI_PRECONDITIONER_H_ diff --git a/internal/ceres/block_jacobi_preconditioner_test.cc b/internal/ceres/block_jacobi_preconditioner_test.cc new file mode 100644 index 0000000..0fb9dc6 --- /dev/null +++ b/internal/ceres/block_jacobi_preconditioner_test.cc @@ -0,0 +1,105 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_jacobi_preconditioner.h" + +#include +#include "ceres/block_random_access_diagonal_matrix.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/block_sparse_matrix.h" +#include "ceres/internal/scoped_ptr.h" +#include "gtest/gtest.h" +#include "Eigen/Dense" + +namespace ceres { +namespace internal { + + +class BlockJacobiPreconditionerTest : public ::testing::Test { + protected: + void SetUpFromProblemId(int problem_id) { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(problem_id)); + + CHECK_NOTNULL(problem.get()); + A.reset(down_cast(problem->A.release())); + D.reset(problem->D.release()); + + Matrix dense_a; + A->ToDenseMatrix(&dense_a); + dense_ata = dense_a.transpose() * dense_a; + dense_ata += VectorRef(D.get(), A->num_cols()) + .array().square().matrix().asDiagonal(); + } + + void VerifyDiagonalBlocks(const int problem_id) { + SetUpFromProblemId(problem_id); + + BlockJacobiPreconditioner pre(*A); + pre.Update(*A, D.get()); + BlockRandomAccessDiagonalMatrix* m = + const_cast(&pre.matrix()); + EXPECT_EQ(m->num_rows(), A->num_cols()); + EXPECT_EQ(m->num_cols(), A->num_cols()); + + const CompressedRowBlockStructure* bs = A->block_structure(); + for (int i = 0; i < bs->cols.size(); ++i) { + const int block_size = bs->cols[i].size; + int r, c, row_stride, col_stride; + CellInfo* cell_info = m->GetCell(i, i, + &r, &c, + &row_stride, &col_stride); + MatrixRef m(cell_info->values, row_stride, col_stride); + Matrix actual_block_inverse = m.block(r, c, block_size, block_size); + Matrix expected_block = dense_ata.block(bs->cols[i].position, + bs->cols[i].position, + block_size, + block_size); + const double residual = (actual_block_inverse * expected_block - + Matrix::Identity(block_size, block_size)).norm(); + EXPECT_NEAR(residual, 0.0, 1e-12) << "Block: " << i; + } + } + + scoped_ptr A; + scoped_array D; + Matrix dense_ata; +}; + +TEST_F(BlockJacobiPreconditionerTest, SmallProblem) { + VerifyDiagonalBlocks(2); +} + +TEST_F(BlockJacobiPreconditionerTest, LargeProblem) { + VerifyDiagonalBlocks(3); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_jacobian_writer.cc b/internal/ceres/block_jacobian_writer.cc new file mode 100644 index 0000000..7a3fee4 --- /dev/null +++ b/internal/ceres/block_jacobian_writer.cc @@ -0,0 +1,214 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/block_jacobian_writer.h" + +#include "ceres/block_evaluate_preparer.h" +#include "ceres/block_sparse_matrix.h" +#include "ceres/parameter_block.h" +#include "ceres/program.h" +#include "ceres/residual_block.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { +namespace internal { + +using std::vector; + +namespace { + +// Given the residual block ordering, build a lookup table to determine which +// per-parameter jacobian goes where in the overall program jacobian. +// +// Since we expect to use a Schur type linear solver to solve the LM step, take +// extra care to place the E blocks and the F blocks contiguously. E blocks are +// the first num_eliminate_blocks parameter blocks as indicated by the parameter +// block ordering. The remaining parameter blocks are the F blocks. +// +// TODO(keir): Consider if we should use a boolean for each parameter block +// instead of num_eliminate_blocks. +void BuildJacobianLayout(const Program& program, + int num_eliminate_blocks, + vector* jacobian_layout, + vector* jacobian_layout_storage) { + const vector& residual_blocks = program.residual_blocks(); + + // Iterate over all the active residual blocks and determine how many E blocks + // are there. This will determine where the F blocks start in the jacobian + // matrix. Also compute the number of jacobian blocks. + int f_block_pos = 0; + int num_jacobian_blocks = 0; + for (int i = 0; i < residual_blocks.size(); ++i) { + ResidualBlock* residual_block = residual_blocks[i]; + const int num_residuals = residual_block->NumResiduals(); + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + + // Advance f_block_pos over each E block for this residual. + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + if (!parameter_block->IsConstant()) { + // Only count blocks for active parameters. + num_jacobian_blocks++; + if (parameter_block->index() < num_eliminate_blocks) { + f_block_pos += num_residuals * parameter_block->LocalSize(); + } + } + } + } + + // We now know that the E blocks are laid out starting at zero, and the F + // blocks are laid out starting at f_block_pos. Iterate over the residual + // blocks again, and this time fill the jacobian_layout array with the + // position information. + + jacobian_layout->resize(program.NumResidualBlocks()); + jacobian_layout_storage->resize(num_jacobian_blocks); + + int e_block_pos = 0; + int* jacobian_pos = &(*jacobian_layout_storage)[0]; + for (int i = 0; i < residual_blocks.size(); ++i) { + const ResidualBlock* residual_block = residual_blocks[i]; + const int num_residuals = residual_block->NumResiduals(); + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + + (*jacobian_layout)[i] = jacobian_pos; + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + const int parameter_block_index = parameter_block->index(); + if (parameter_block->IsConstant()) { + continue; + } + const int jacobian_block_size = + num_residuals * parameter_block->LocalSize(); + if (parameter_block_index < num_eliminate_blocks) { + *jacobian_pos = e_block_pos; + e_block_pos += jacobian_block_size; + } else { + *jacobian_pos = f_block_pos; + f_block_pos += jacobian_block_size; + } + jacobian_pos++; + } + } +} + +} // namespace + +BlockJacobianWriter::BlockJacobianWriter(const Evaluator::Options& options, + Program* program) + : program_(program) { + CHECK_GE(options.num_eliminate_blocks, 0) + << "num_eliminate_blocks must be greater than 0."; + + BuildJacobianLayout(*program, + options.num_eliminate_blocks, + &jacobian_layout_, + &jacobian_layout_storage_); +} + +// Create evaluate prepareres that point directly into the final jacobian. This +// makes the final Write() a nop. +BlockEvaluatePreparer* BlockJacobianWriter::CreateEvaluatePreparers( + int num_threads) { + int max_derivatives_per_residual_block = + program_->MaxDerivativesPerResidualBlock(); + + BlockEvaluatePreparer* preparers = new BlockEvaluatePreparer[num_threads]; + for (int i = 0; i < num_threads; i++) { + preparers[i].Init(&jacobian_layout_[0], max_derivatives_per_residual_block); + } + return preparers; +} + +SparseMatrix* BlockJacobianWriter::CreateJacobian() const { + CompressedRowBlockStructure* bs = new CompressedRowBlockStructure; + + const vector& parameter_blocks = + program_->parameter_blocks(); + + // Construct the column blocks. + bs->cols.resize(parameter_blocks.size()); + for (int i = 0, cursor = 0; i < parameter_blocks.size(); ++i) { + CHECK_NE(parameter_blocks[i]->index(), -1); + CHECK(!parameter_blocks[i]->IsConstant()); + bs->cols[i].size = parameter_blocks[i]->LocalSize(); + bs->cols[i].position = cursor; + cursor += bs->cols[i].size; + } + + // Construct the cells in each row. + const vector& residual_blocks = program_->residual_blocks(); + int row_block_position = 0; + bs->rows.resize(residual_blocks.size()); + for (int i = 0; i < residual_blocks.size(); ++i) { + const ResidualBlock* residual_block = residual_blocks[i]; + CompressedRow* row = &bs->rows[i]; + + row->block.size = residual_block->NumResiduals(); + row->block.position = row_block_position; + row_block_position += row->block.size; + + // Size the row by the number of active parameters in this residual. + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + int num_active_parameter_blocks = 0; + for (int j = 0; j < num_parameter_blocks; ++j) { + if (residual_block->parameter_blocks()[j]->index() != -1) { + num_active_parameter_blocks++; + } + } + row->cells.resize(num_active_parameter_blocks); + + // Add layout information for the active parameters in this row. + for (int j = 0, k = 0; j < num_parameter_blocks; ++j) { + const ParameterBlock* parameter_block = + residual_block->parameter_blocks()[j]; + if (!parameter_block->IsConstant()) { + Cell& cell = row->cells[k]; + cell.block_id = parameter_block->index(); + cell.position = jacobian_layout_[i][k]; + + // Only increment k for active parameters, since there is only layout + // information for active parameters. + k++; + } + } + + sort(row->cells.begin(), row->cells.end(), CellLessThan); + } + + BlockSparseMatrix* jacobian = new BlockSparseMatrix(bs); + CHECK_NOTNULL(jacobian); + return jacobian; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_jacobian_writer.h b/internal/ceres/block_jacobian_writer.h new file mode 100644 index 0000000..c94a0d3 --- /dev/null +++ b/internal/ceres/block_jacobian_writer.h @@ -0,0 +1,128 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A jacobian writer that writes to block sparse matrices. The "writer" name is +// misleading, since the Write() operation on the block jacobian writer does not +// write anything. Instead, the Prepare() method on the BlockEvaluatePreparers +// makes a jacobians array which has direct pointers into the block sparse +// jacobian. When the cost function is evaluated, the jacobian blocks get placed +// directly in their final location. + +#ifndef CERES_INTERNAL_BLOCK_JACOBIAN_WRITER_H_ +#define CERES_INTERNAL_BLOCK_JACOBIAN_WRITER_H_ + +#include +#include "ceres/evaluator.h" +#include "ceres/internal/port.h" + +namespace ceres { +namespace internal { + +class BlockEvaluatePreparer; +class Program; +class SparseMatrix; + +// TODO(sameeragarwal): This class needs documemtation. +class BlockJacobianWriter { + public: + BlockJacobianWriter(const Evaluator::Options& options, + Program* program); + + // JacobianWriter interface. + + // Create evaluate prepareres that point directly into the final jacobian. + // This makes the final Write() a nop. + BlockEvaluatePreparer* CreateEvaluatePreparers(int num_threads); + + SparseMatrix* CreateJacobian() const; + + void Write(int /* residual_id */, + int /* residual_offset */, + double** /* jacobians */, + SparseMatrix* /* jacobian */) { + // This is a noop since the blocks were written directly into their final + // position by the outside evaluate call, thanks to the jacobians array + // prepared by the BlockEvaluatePreparers. + } + + private: + Program* program_; + + // Stores the position of each residual / parameter jacobian. + // + // The block sparse matrix that this writer writes to is stored as a set of + // contiguos dense blocks, one after each other; see BlockSparseMatrix. The + // "double* values_" member of the block sparse matrix contains all of these + // blocks. Given a pointer to the first element of a block and the size of + // that block, it's possible to write to it. + // + // In the case of a block sparse jacobian, the jacobian writer needs a way to + // find the offset in the values_ array of each residual/parameter jacobian + // block. + // + // That is the purpose of jacobian_layout_. + // + // In particular, jacobian_layout_[i][j] is the offset in the values_ array of + // the derivative of residual block i with respect to the parameter block at + // active argument position j. + // + // The active qualifier means that non-active parameters do not count. Care + // must be taken when indexing into jacobian_layout_ to account for this. + // Consider a single residual example: + // + // r(x, y, z) + // + // with r in R^3, x in R^4, y in R^2, and z in R^5. + // Take y as a constant (non-active) parameter. + // Take r as residual number 0. + // + // In this case, the active arguments are only (x, z), so the active argument + // position for x is 0, and the active argument position for z is 1. This is + // similar to thinking of r as taking only 2 parameters: + // + // r(x, z) + // + // There are only 2 jacobian blocks: dr/dx and dr/dz. jacobian_layout_ would + // have the following contents: + // + // jacobian_layout_[0] = { 0, 12 } + // + // which indicates that dr/dx is located at values_[0], and dr/dz is at + // values_[12]. See BlockEvaluatePreparer::Prepare()'s comments about 'j'. + std::vector jacobian_layout_; + + // The pointers in jacobian_layout_ point directly into this vector. + std::vector jacobian_layout_storage_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_JACOBIAN_WRITER_H_ diff --git a/internal/ceres/block_random_access_dense_matrix.cc b/internal/ceres/block_random_access_dense_matrix.cc new file mode 100644 index 0000000..61748ef --- /dev/null +++ b/internal/ceres/block_random_access_dense_matrix.cc @@ -0,0 +1,88 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_random_access_dense_matrix.h" + +#include +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +BlockRandomAccessDenseMatrix::BlockRandomAccessDenseMatrix( + const std::vector& blocks) { + const int num_blocks = blocks.size(); + block_layout_.resize(num_blocks, 0); + num_rows_ = 0; + for (int i = 0; i < num_blocks; ++i) { + block_layout_[i] = num_rows_; + num_rows_ += blocks[i]; + } + + values_.reset(new double[num_rows_ * num_rows_]); + + cell_infos_.reset(new CellInfo[num_blocks * num_blocks]); + for (int i = 0; i < num_blocks * num_blocks; ++i) { + cell_infos_[i].values = values_.get(); + } + + SetZero(); +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +BlockRandomAccessDenseMatrix::~BlockRandomAccessDenseMatrix() { +} + +CellInfo* BlockRandomAccessDenseMatrix::GetCell(const int row_block_id, + const int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride) { + *row = block_layout_[row_block_id]; + *col = block_layout_[col_block_id]; + *row_stride = num_rows_; + *col_stride = num_rows_; + return &cell_infos_[row_block_id * block_layout_.size() + col_block_id]; +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +void BlockRandomAccessDenseMatrix::SetZero() { + if (num_rows_) { + VectorRef(values_.get(), num_rows_ * num_rows_).setZero(); + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_dense_matrix.h b/internal/ceres/block_random_access_dense_matrix.h new file mode 100644 index 0000000..8968908 --- /dev/null +++ b/internal/ceres/block_random_access_dense_matrix.h @@ -0,0 +1,98 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DENSE_MATRIX_H_ +#define CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DENSE_MATRIX_H_ + +#include "ceres/block_random_access_matrix.h" + +#include + +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { +namespace internal { + +// A square block random accessible matrix with the same row and +// column block structure. All cells are stored in the same single +// array, so that its also accessible as a dense matrix of size +// num_rows x num_cols. +// +// This class is NOT thread safe. Since all n^2 cells are stored, +// GetCell never returns NULL for any (row_block_id, col_block_id) +// pair. +// +// ReturnCell is a nop. +class BlockRandomAccessDenseMatrix : public BlockRandomAccessMatrix { + public: + // blocks is a vector of block sizes. The resulting matrix has + // blocks.size() * blocks.size() cells. + explicit BlockRandomAccessDenseMatrix(const std::vector& blocks); + + // The destructor is not thread safe. It assumes that no one is + // modifying any cells when the matrix is being destroyed. + virtual ~BlockRandomAccessDenseMatrix(); + + // BlockRandomAccessMatrix interface. + virtual CellInfo* GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride); + + // This is not a thread safe method, it assumes that no cell is + // locked. + virtual void SetZero(); + + // Since the matrix is square with the same row and column block + // structure, num_rows() = num_cols(). + virtual int num_rows() const { return num_rows_; } + virtual int num_cols() const { return num_rows_; } + + // The underlying matrix storing the cells. + const double* values() const { return values_.get(); } + double* mutable_values() { return values_.get(); } + + private: + int num_rows_; + std::vector block_layout_; + scoped_array values_; + scoped_array cell_infos_; + + CERES_DISALLOW_COPY_AND_ASSIGN(BlockRandomAccessDenseMatrix); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DENSE_MATRIX_H_ diff --git a/internal/ceres/block_random_access_dense_matrix_test.cc b/internal/ceres/block_random_access_dense_matrix_test.cc new file mode 100644 index 0000000..8a5ba59 --- /dev/null +++ b/internal/ceres/block_random_access_dense_matrix_test.cc @@ -0,0 +1,115 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include +#include "gtest/gtest.h" +#include "ceres/block_random_access_dense_matrix.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +TEST(BlockRandomAccessDenseMatrix, GetCell) { + std::vector blocks; + blocks.push_back(3); + blocks.push_back(4); + blocks.push_back(5); + const int num_rows = 3 + 4 + 5; + BlockRandomAccessDenseMatrix m(blocks); + EXPECT_EQ(m.num_rows(), num_rows); + EXPECT_EQ(m.num_cols(), num_rows); + + int row_idx = 0; + for (int i = 0; i < blocks.size(); ++i) { + int col_idx = 0; + for (int j = 0; j < blocks.size(); ++j) { + int row; + int col; + int row_stride; + int col_stride; + CellInfo* cell = + m.GetCell(i, j, &row, &col, &row_stride, &col_stride); + + EXPECT_TRUE(cell != NULL); + EXPECT_EQ(row, row_idx); + EXPECT_EQ(col, col_idx); + EXPECT_EQ(row_stride, 3 + 4 + 5); + EXPECT_EQ(col_stride, 3 + 4 + 5); + col_idx += blocks[j]; + } + row_idx += blocks[i]; + } +} + +TEST(BlockRandomAccessDenseMatrix, WriteCell) { + std::vector blocks; + blocks.push_back(3); + blocks.push_back(4); + blocks.push_back(5); + const int num_rows = 3 + 4 + 5; + + BlockRandomAccessDenseMatrix m(blocks); + + // Fill the cell (i,j) with (i + 1) * (j + 1) + for (int i = 0; i < blocks.size(); ++i) { + for (int j = 0; j < blocks.size(); ++j) { + int row; + int col; + int row_stride; + int col_stride; + CellInfo* cell = m.GetCell( + i, j, &row, &col, &row_stride, &col_stride); + MatrixRef(cell->values, row_stride, col_stride).block( + row, col, blocks[i], blocks[j]) = + (i+1) * (j+1) * Matrix::Ones(blocks[i], blocks[j]); + } + } + + // Check the values in the array are correct by going over the + // entries of each block manually. + int row_idx = 0; + for (int i = 0; i < blocks.size(); ++i) { + int col_idx = 0; + for (int j = 0; j < blocks.size(); ++j) { + // Check the values of this block. + for (int r = 0; r < blocks[i]; ++r) { + for (int c = 0; c < blocks[j]; ++c) { + int pos = row_idx * num_rows + col_idx; + EXPECT_EQ(m.values()[pos], (i + 1) * (j + 1)); + } + } + col_idx += blocks[j]; + } + row_idx += blocks[i]; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_diagonal_matrix.cc b/internal/ceres/block_random_access_diagonal_matrix.cc new file mode 100644 index 0000000..052690d --- /dev/null +++ b/internal/ceres/block_random_access_diagonal_matrix.cc @@ -0,0 +1,154 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_random_access_diagonal_matrix.h" + +#include +#include +#include +#include +#include "Eigen/Dense" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/stl_util.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +// TODO(sameeragarwal): Drop the dependence on TripletSparseMatrix. + +BlockRandomAccessDiagonalMatrix::BlockRandomAccessDiagonalMatrix( + const vector& blocks) + : blocks_(blocks) { + // Build the row/column layout vector and count the number of scalar + // rows/columns. + int num_cols = 0; + int num_nonzeros = 0; + vector block_positions; + for (int i = 0; i < blocks_.size(); ++i) { + block_positions.push_back(num_cols); + num_cols += blocks_[i]; + num_nonzeros += blocks_[i] * blocks_[i]; + } + + VLOG(1) << "Matrix Size [" << num_cols + << "," << num_cols + << "] " << num_nonzeros; + + tsm_.reset(new TripletSparseMatrix(num_cols, num_cols, num_nonzeros)); + tsm_->set_num_nonzeros(num_nonzeros); + int* rows = tsm_->mutable_rows(); + int* cols = tsm_->mutable_cols(); + double* values = tsm_->mutable_values(); + + int pos = 0; + for (int i = 0; i < blocks_.size(); ++i) { + const int block_size = blocks_[i]; + layout_.push_back(new CellInfo(values + pos)); + const int block_begin = block_positions[i]; + for (int r = 0; r < block_size; ++r) { + for (int c = 0; c < block_size; ++c, ++pos) { + rows[pos] = block_begin + r; + cols[pos] = block_begin + c; + } + } + } +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +BlockRandomAccessDiagonalMatrix::~BlockRandomAccessDiagonalMatrix() { + STLDeleteContainerPointers(layout_.begin(), layout_.end()); +} + +CellInfo* BlockRandomAccessDiagonalMatrix::GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride) { + if (row_block_id != col_block_id) { + return NULL; + } + const int stride = blocks_[row_block_id]; + + // Each cell is stored contiguously as its own little dense matrix. + *row = 0; + *col = 0; + *row_stride = stride; + *col_stride = stride; + return layout_[row_block_id]; +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +void BlockRandomAccessDiagonalMatrix::SetZero() { + if (tsm_->num_nonzeros()) { + VectorRef(tsm_->mutable_values(), + tsm_->num_nonzeros()).setZero(); + } +} + +void BlockRandomAccessDiagonalMatrix::Invert() { + double* values = tsm_->mutable_values(); + for (int i = 0; i < blocks_.size(); ++i) { + const int block_size = blocks_[i]; + MatrixRef block(values, block_size, block_size); + block = + block + .selfadjointView() + .llt() + .solve(Matrix::Identity(block_size, block_size)); + values += block_size * block_size; + } +} + +void BlockRandomAccessDiagonalMatrix::RightMultiply(const double* x, + double* y) const { + CHECK_NOTNULL(x); + CHECK_NOTNULL(y); + const double* values = tsm_->values(); + for (int i = 0; i < blocks_.size(); ++i) { + const int block_size = blocks_[i]; + ConstMatrixRef block(values, block_size, block_size); + VectorRef(y, block_size).noalias() += block * ConstVectorRef(x, block_size); + x += block_size; + y += block_size; + values += block_size * block_size; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_diagonal_matrix.h b/internal/ceres/block_random_access_diagonal_matrix.h new file mode 100644 index 0000000..07ffc9d --- /dev/null +++ b/internal/ceres/block_random_access_diagonal_matrix.h @@ -0,0 +1,101 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DIAGONAL_MATRIX_H_ +#define CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DIAGONAL_MATRIX_H_ + +#include +#include +#include +#include "ceres/mutex.h" +#include "ceres/block_random_access_matrix.h" +#include "ceres/collections_port.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/integral_types.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" + +namespace ceres { +namespace internal { + +// A thread safe block diagonal matrix implementation of +// BlockRandomAccessMatrix. +class BlockRandomAccessDiagonalMatrix : public BlockRandomAccessMatrix { + public: + // blocks is an array of block sizes. + explicit BlockRandomAccessDiagonalMatrix(const std::vector& blocks); + + // The destructor is not thread safe. It assumes that no one is + // modifying any cells when the matrix is being destroyed. + virtual ~BlockRandomAccessDiagonalMatrix(); + + // BlockRandomAccessMatrix Interface. + virtual CellInfo* GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride); + + // This is not a thread safe method, it assumes that no cell is + // locked. + virtual void SetZero(); + + // Invert the matrix assuming that each block is positive definite. + void Invert(); + + // y += S * x + void RightMultiply(const double* x, double* y) const; + + // Since the matrix is square, num_rows() == num_cols(). + virtual int num_rows() const { return tsm_->num_rows(); } + virtual int num_cols() const { return tsm_->num_cols(); } + + const TripletSparseMatrix* matrix() const { return tsm_.get(); } + TripletSparseMatrix* mutable_matrix() { return tsm_.get(); } + + private: + // row/column block sizes. + const std::vector blocks_; + std::vector layout_; + + // The underlying matrix object which actually stores the cells. + scoped_ptr tsm_; + + friend class BlockRandomAccessDiagonalMatrixTest; + CERES_DISALLOW_COPY_AND_ASSIGN(BlockRandomAccessDiagonalMatrix); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_RANDOM_ACCESS_DIAGONAL_MATRIX_H_ diff --git a/internal/ceres/block_random_access_diagonal_matrix_test.cc b/internal/ceres/block_random_access_diagonal_matrix_test.cc new file mode 100644 index 0000000..8fa3798 --- /dev/null +++ b/internal/ceres/block_random_access_diagonal_matrix_test.cc @@ -0,0 +1,160 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include +#include + +#include "ceres/block_random_access_diagonal_matrix.h" +#include "ceres/internal/eigen.h" +#include "glog/logging.h" +#include "gtest/gtest.h" +#include "Eigen/Cholesky" + +namespace ceres { +namespace internal { + +class BlockRandomAccessDiagonalMatrixTest : public ::testing::Test { + public: + void SetUp() { + std::vector blocks; + blocks.push_back(3); + blocks.push_back(4); + blocks.push_back(5); + const int num_rows = 3 + 4 + 5; + num_nonzeros_ = 3 * 3 + 4 * 4 + 5 * 5; + + m_.reset(new BlockRandomAccessDiagonalMatrix(blocks)); + + EXPECT_EQ(m_->num_rows(), num_rows); + EXPECT_EQ(m_->num_cols(), num_rows); + + for (int i = 0; i < blocks.size(); ++i) { + const int row_block_id = i; + int col_block_id; + int row; + int col; + int row_stride; + int col_stride; + + for (int j = 0; j < blocks.size(); ++j) { + col_block_id = j; + CellInfo* cell = m_->GetCell(row_block_id, col_block_id, + &row, &col, + &row_stride, &col_stride); + // Off diagonal entries are not present. + if (i != j) { + EXPECT_TRUE(cell == NULL); + continue; + } + + EXPECT_TRUE(cell != NULL); + EXPECT_EQ(row, 0); + EXPECT_EQ(col, 0); + EXPECT_EQ(row_stride, blocks[row_block_id]); + EXPECT_EQ(col_stride, blocks[col_block_id]); + + // Write into the block + MatrixRef(cell->values, row_stride, col_stride).block( + row, col, blocks[row_block_id], blocks[col_block_id]) = + (row_block_id + 1) * (col_block_id +1) * + Matrix::Ones(blocks[row_block_id], blocks[col_block_id]) + + Matrix::Identity(blocks[row_block_id], blocks[row_block_id]); + } + } + } + + protected: + int num_nonzeros_; + scoped_ptr m_; +}; + +TEST_F(BlockRandomAccessDiagonalMatrixTest, MatrixContents) { + const TripletSparseMatrix* tsm = m_->matrix(); + EXPECT_EQ(tsm->num_nonzeros(), num_nonzeros_); + EXPECT_EQ(tsm->max_num_nonzeros(), num_nonzeros_); + + Matrix dense; + tsm->ToDenseMatrix(&dense); + + double kTolerance = 1e-14; + + // (0,0) + EXPECT_NEAR((dense.block(0, 0, 3, 3) - + (Matrix::Ones(3, 3) + Matrix::Identity(3, 3))).norm(), + 0.0, + kTolerance); + + // (1,1) + EXPECT_NEAR((dense.block(3, 3, 4, 4) - + (2 * 2 * Matrix::Ones(4, 4) + Matrix::Identity(4, 4))).norm(), + 0.0, + kTolerance); + + // (1,1) + EXPECT_NEAR((dense.block(7, 7, 5, 5) - + (3 * 3 * Matrix::Ones(5, 5) + Matrix::Identity(5, 5))).norm(), + 0.0, + kTolerance); + + // There is nothing else in the matrix besides these four blocks. + EXPECT_NEAR(dense.norm(), + sqrt(6 * 1.0 + 3 * 4.0 + + 12 * 16.0 + 4 * 25.0 + + 20 * 81.0 + 5 * 100.0), kTolerance); +} + +TEST_F(BlockRandomAccessDiagonalMatrixTest, RightMultiply) { + double kTolerance = 1e-14; + const TripletSparseMatrix* tsm = m_->matrix(); + Matrix dense; + tsm->ToDenseMatrix(&dense); + Vector x = Vector::Random(dense.rows()); + Vector expected_y = dense * x; + Vector actual_y = Vector::Zero(dense.rows()); + m_->RightMultiply(x.data(), actual_y.data()); + EXPECT_NEAR((expected_y - actual_y).norm(), 0, kTolerance); +} + +TEST_F(BlockRandomAccessDiagonalMatrixTest, Invert) { + double kTolerance = 1e-14; + const TripletSparseMatrix* tsm = m_->matrix(); + Matrix dense; + tsm->ToDenseMatrix(&dense); + Matrix expected_inverse = + dense.llt().solve(Matrix::Identity(dense.rows(), dense.rows())); + + m_->Invert(); + tsm->ToDenseMatrix(&dense); + + EXPECT_NEAR((expected_inverse - dense).norm(), 0.0, kTolerance); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_matrix.cc b/internal/ceres/block_random_access_matrix.cc new file mode 100644 index 0000000..347d765 --- /dev/null +++ b/internal/ceres/block_random_access_matrix.cc @@ -0,0 +1,40 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_random_access_matrix.h" + +namespace ceres { +namespace internal { + +BlockRandomAccessMatrix::~BlockRandomAccessMatrix() { +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_matrix.h b/internal/ceres/block_random_access_matrix.h new file mode 100644 index 0000000..34c8bf5 --- /dev/null +++ b/internal/ceres/block_random_access_matrix.h @@ -0,0 +1,132 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Interface for matrices that allow block based random access. + +#ifndef CERES_INTERNAL_BLOCK_RANDOM_ACCESS_MATRIX_H_ +#define CERES_INTERNAL_BLOCK_RANDOM_ACCESS_MATRIX_H_ + +#include "ceres/mutex.h" + +namespace ceres { +namespace internal { + +// A matrix implementing the BlockRandomAccessMatrix interface is a +// matrix whose rows and columns are divided into blocks. For example +// the matrix A: +// +// 3 4 5 +// A = 5 [c_11 c_12 c_13] +// 4 [c_21 c_22 c_23] +// +// has row blocks of size 5 and 4, and column blocks of size 3, 4 and +// 5. It has six cells corresponding to the six row-column block +// combinations. +// +// BlockRandomAccessMatrix objects provide access to cells c_ij using +// the GetCell method. when a cell is present, GetCell will return a +// CellInfo object containing a pointer to an array which contains the +// cell as a submatrix and a mutex that guards this submatrix. If the +// user is accessing the matrix concurrently, it is his responsibility +// to use the mutex to exclude other writers from writing to the cell +// concurrently. +// +// There is no requirement that all cells be present, i.e. the matrix +// itself can be block sparse. When a cell is not present, the GetCell +// method will return a NULL pointer. +// +// There is no requirement about how the cells are stored beyond that +// form a dense submatrix of a larger dense matrix. Like everywhere +// else in Ceres, RowMajor storage assumed. +// +// Example usage: +// +// BlockRandomAccessMatrix* A = new BlockRandomAccessMatrixSubClass(...) +// +// int row, col, row_stride, col_stride; +// CellInfo* cell = A->GetCell(row_block_id, col_block_id, +// &row, &col, +// &row_stride, &col_stride); +// +// if (cell != NULL) { +// MatrixRef m(cell->values, row_stride, col_stride); +// CeresMutexLock l(&cell->m); +// m.block(row, col, row_block_size, col_block_size) = ... +// } + +// Structure to carry a pointer to the array containing a cell and the +// Mutex guarding it. +struct CellInfo { + CellInfo() + : values(NULL) { + } + + explicit CellInfo(double* ptr) + : values(ptr) { + } + + double* values; + Mutex m; +}; + +class BlockRandomAccessMatrix { + public: + virtual ~BlockRandomAccessMatrix(); + + // If the cell (row_block_id, col_block_id) is present, then return + // a CellInfo with a pointer to the dense matrix containing it, + // otherwise return NULL. The dense matrix containing this cell has + // size row_stride, col_stride and the cell is located at position + // (row, col) within this matrix. + // + // The size of the cell is row_block_size x col_block_size is + // assumed known to the caller. row_block_size less than or equal to + // row_stride and col_block_size is upper bounded by col_stride. + virtual CellInfo* GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride) = 0; + + // Zero out the values of the array. The structure of the matrix + // (size and sparsity) is preserved. + virtual void SetZero() = 0; + + // Number of scalar rows and columns in the matrix, i.e the sum of + // all row blocks and column block sizes respectively. + virtual int num_rows() const = 0; + virtual int num_cols() const = 0; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_RANDOM_ACCESS_MATRIX_H_ diff --git a/internal/ceres/block_random_access_sparse_matrix.cc b/internal/ceres/block_random_access_sparse_matrix.cc new file mode 100644 index 0000000..5432ec1 --- /dev/null +++ b/internal/ceres/block_random_access_sparse_matrix.cc @@ -0,0 +1,196 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_random_access_sparse_matrix.h" + +#include +#include +#include +#include +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/mutex.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::make_pair; +using std::pair; +using std::set; +using std::vector; + +BlockRandomAccessSparseMatrix::BlockRandomAccessSparseMatrix( + const vector& blocks, + const set >& block_pairs) + : kMaxRowBlocks(10 * 1000 * 1000), + blocks_(blocks) { + CHECK_LT(blocks.size(), kMaxRowBlocks); + + // Build the row/column layout vector and count the number of scalar + // rows/columns. + int num_cols = 0; + block_positions_.reserve(blocks_.size()); + for (int i = 0; i < blocks_.size(); ++i) { + block_positions_.push_back(num_cols); + num_cols += blocks_[i]; + } + + // Count the number of scalar non-zero entries and build the layout + // object for looking into the values array of the + // TripletSparseMatrix. + int num_nonzeros = 0; + for (set >::const_iterator it = block_pairs.begin(); + it != block_pairs.end(); + ++it) { + const int row_block_size = blocks_[it->first]; + const int col_block_size = blocks_[it->second]; + num_nonzeros += row_block_size * col_block_size; + } + + VLOG(1) << "Matrix Size [" << num_cols + << "," << num_cols + << "] " << num_nonzeros; + + tsm_.reset(new TripletSparseMatrix(num_cols, num_cols, num_nonzeros)); + tsm_->set_num_nonzeros(num_nonzeros); + int* rows = tsm_->mutable_rows(); + int* cols = tsm_->mutable_cols(); + double* values = tsm_->mutable_values(); + + int pos = 0; + for (set >::const_iterator it = block_pairs.begin(); + it != block_pairs.end(); + ++it) { + const int row_block_size = blocks_[it->first]; + const int col_block_size = blocks_[it->second]; + cell_values_.push_back(make_pair(make_pair(it->first, it->second), + values + pos)); + layout_[IntPairToLong(it->first, it->second)] = + new CellInfo(values + pos); + pos += row_block_size * col_block_size; + } + + // Fill the sparsity pattern of the underlying matrix. + for (set >::const_iterator it = block_pairs.begin(); + it != block_pairs.end(); + ++it) { + const int row_block_id = it->first; + const int col_block_id = it->second; + const int row_block_size = blocks_[row_block_id]; + const int col_block_size = blocks_[col_block_id]; + int pos = + layout_[IntPairToLong(row_block_id, col_block_id)]->values - values; + for (int r = 0; r < row_block_size; ++r) { + for (int c = 0; c < col_block_size; ++c, ++pos) { + rows[pos] = block_positions_[row_block_id] + r; + cols[pos] = block_positions_[col_block_id] + c; + values[pos] = 1.0; + DCHECK_LT(rows[pos], tsm_->num_rows()); + DCHECK_LT(cols[pos], tsm_->num_rows()); + } + } + } +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +BlockRandomAccessSparseMatrix::~BlockRandomAccessSparseMatrix() { + for (LayoutType::iterator it = layout_.begin(); + it != layout_.end(); + ++it) { + delete it->second; + } +} + +CellInfo* BlockRandomAccessSparseMatrix::GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride) { + const LayoutType::iterator it = + layout_.find(IntPairToLong(row_block_id, col_block_id)); + if (it == layout_.end()) { + return NULL; + } + + // Each cell is stored contiguously as its own little dense matrix. + *row = 0; + *col = 0; + *row_stride = blocks_[row_block_id]; + *col_stride = blocks_[col_block_id]; + return it->second; +} + +// Assume that the user does not hold any locks on any cell blocks +// when they are calling SetZero. +void BlockRandomAccessSparseMatrix::SetZero() { + if (tsm_->num_nonzeros()) { + VectorRef(tsm_->mutable_values(), + tsm_->num_nonzeros()).setZero(); + } +} + +void BlockRandomAccessSparseMatrix::SymmetricRightMultiply(const double* x, + double* y) const { + vector< pair, double*> >::const_iterator it = + cell_values_.begin(); + for (; it != cell_values_.end(); ++it) { + const int row = it->first.first; + const int row_block_size = blocks_[row]; + const int row_block_pos = block_positions_[row]; + + const int col = it->first.second; + const int col_block_size = blocks_[col]; + const int col_block_pos = block_positions_[col]; + + MatrixVectorMultiply( + it->second, row_block_size, col_block_size, + x + col_block_pos, + y + row_block_pos); + + // Since the matrix is symmetric, but only the upper triangular + // part is stored, if the block being accessed is not a diagonal + // block, then use the same block to do the corresponding lower + // triangular multiply also. + if (row != col) { + MatrixTransposeVectorMultiply( + it->second, row_block_size, col_block_size, + x + row_block_pos, + y + col_block_pos); + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_random_access_sparse_matrix.h b/internal/ceres/block_random_access_sparse_matrix.h new file mode 100644 index 0000000..2b3c7fd --- /dev/null +++ b/internal/ceres/block_random_access_sparse_matrix.h @@ -0,0 +1,129 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_BLOCK_RANDOM_ACCESS_SPARSE_MATRIX_H_ +#define CERES_INTERNAL_BLOCK_RANDOM_ACCESS_SPARSE_MATRIX_H_ + +#include +#include +#include +#include "ceres/mutex.h" +#include "ceres/block_random_access_matrix.h" +#include "ceres/collections_port.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/integral_types.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" +#include "ceres/small_blas.h" + +namespace ceres { +namespace internal { + +// A thread safe square block sparse implementation of +// BlockRandomAccessMatrix. Internally a TripletSparseMatrix is used +// for doing the actual storage. This class augments this matrix with +// an unordered_map that allows random read/write access. +class BlockRandomAccessSparseMatrix : public BlockRandomAccessMatrix { + public: + // blocks is an array of block sizes. block_pairs is a set of + // pairs to identify the non-zero cells + // of this matrix. + BlockRandomAccessSparseMatrix( + const std::vector& blocks, + const std::set >& block_pairs); + + // The destructor is not thread safe. It assumes that no one is + // modifying any cells when the matrix is being destroyed. + virtual ~BlockRandomAccessSparseMatrix(); + + // BlockRandomAccessMatrix Interface. + virtual CellInfo* GetCell(int row_block_id, + int col_block_id, + int* row, + int* col, + int* row_stride, + int* col_stride); + + // This is not a thread safe method, it assumes that no cell is + // locked. + virtual void SetZero(); + + // Assume that the matrix is symmetric and only one half of the + // matrix is stored. + // + // y += S * x + void SymmetricRightMultiply(const double* x, double* y) const; + + // Since the matrix is square, num_rows() == num_cols(). + virtual int num_rows() const { return tsm_->num_rows(); } + virtual int num_cols() const { return tsm_->num_cols(); } + + // Access to the underlying matrix object. + const TripletSparseMatrix* matrix() const { return tsm_.get(); } + TripletSparseMatrix* mutable_matrix() { return tsm_.get(); } + + private: + int64 IntPairToLong(int row, int col) const { + return row * kMaxRowBlocks + col; + } + + void LongToIntPair(int64 index, int* row, int* col) const { + *row = index / kMaxRowBlocks; + *col = index % kMaxRowBlocks; + } + + const int64 kMaxRowBlocks; + + // row/column block sizes. + const std::vector blocks_; + std::vector block_positions_; + + // A mapping from to the position in + // the values array of tsm_ where the block is stored. + typedef HashMap LayoutType; + LayoutType layout_; + + // In order traversal of contents of the matrix. This allows us to + // implement a matrix-vector which is 20% faster than using the + // iterator in the Layout object instead. + std::vector, double*> > cell_values_; + // The underlying matrix object which actually stores the cells. + scoped_ptr tsm_; + + friend class BlockRandomAccessSparseMatrixTest; + CERES_DISALLOW_COPY_AND_ASSIGN(BlockRandomAccessSparseMatrix); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_RANDOM_ACCESS_SPARSE_MATRIX_H_ diff --git a/internal/ceres/block_random_access_sparse_matrix_test.cc b/internal/ceres/block_random_access_sparse_matrix_test.cc new file mode 100644 index 0000000..e4d82d0 --- /dev/null +++ b/internal/ceres/block_random_access_sparse_matrix_test.cc @@ -0,0 +1,186 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include +#include +#include "ceres/block_random_access_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::make_pair; +using std::pair; +using std::set; +using std::vector; + +TEST(BlockRandomAccessSparseMatrix, GetCell) { + vector blocks; + blocks.push_back(3); + blocks.push_back(4); + blocks.push_back(5); + const int num_rows = 3 + 4 + 5; + + set< pair > block_pairs; + int num_nonzeros = 0; + block_pairs.insert(make_pair(0, 0)); + num_nonzeros += blocks[0] * blocks[0]; + + block_pairs.insert(make_pair(1, 1)); + num_nonzeros += blocks[1] * blocks[1]; + + block_pairs.insert(make_pair(1, 2)); + num_nonzeros += blocks[1] * blocks[2]; + + block_pairs.insert(make_pair(0, 2)); + num_nonzeros += blocks[2] * blocks[0]; + + BlockRandomAccessSparseMatrix m(blocks, block_pairs); + EXPECT_EQ(m.num_rows(), num_rows); + EXPECT_EQ(m.num_cols(), num_rows); + + for (set >::const_iterator it = block_pairs.begin(); + it != block_pairs.end(); + ++it) { + const int row_block_id = it->first; + const int col_block_id = it->second; + int row; + int col; + int row_stride; + int col_stride; + CellInfo* cell = m.GetCell(row_block_id, col_block_id, + &row, &col, + &row_stride, &col_stride); + EXPECT_TRUE(cell != NULL); + EXPECT_EQ(row, 0); + EXPECT_EQ(col, 0); + EXPECT_EQ(row_stride, blocks[row_block_id]); + EXPECT_EQ(col_stride, blocks[col_block_id]); + + // Write into the block + MatrixRef(cell->values, row_stride, col_stride).block( + row, col, blocks[row_block_id], blocks[col_block_id]) = + (row_block_id + 1) * (col_block_id +1) * + Matrix::Ones(blocks[row_block_id], blocks[col_block_id]); + } + + const TripletSparseMatrix* tsm = m.matrix(); + EXPECT_EQ(tsm->num_nonzeros(), num_nonzeros); + EXPECT_EQ(tsm->max_num_nonzeros(), num_nonzeros); + + Matrix dense; + tsm->ToDenseMatrix(&dense); + + double kTolerance = 1e-14; + + // (0, 0) + EXPECT_NEAR((dense.block(0, 0, 3, 3) - Matrix::Ones(3, 3)).norm(), + 0.0, + kTolerance); + // (1, 1) + EXPECT_NEAR((dense.block(3, 3, 4, 4) - 2 * 2 * Matrix::Ones(4, 4)).norm(), + 0.0, + kTolerance); + // (1, 2) + EXPECT_NEAR((dense.block(3, 3 + 4, 4, 5) - 2 * 3 * Matrix::Ones(4, 5)).norm(), + 0.0, + kTolerance); + // (0, 2) + EXPECT_NEAR((dense.block(0, 3 + 4, 3, 5) - 3 * 1 * Matrix::Ones(3, 5)).norm(), + 0.0, + kTolerance); + + // There is nothing else in the matrix besides these four blocks. + EXPECT_NEAR(dense.norm(), sqrt(9. + 16. * 16. + 36. * 20. + 9. * 15.), + kTolerance); + + Vector x = Vector::Ones(dense.rows()); + Vector actual_y = Vector::Zero(dense.rows()); + Vector expected_y = Vector::Zero(dense.rows()); + + expected_y += dense.selfadjointView() * x; + m.SymmetricRightMultiply(x.data(), actual_y.data()); + EXPECT_NEAR((expected_y - actual_y).norm(), 0.0, kTolerance) + << "actual: " << actual_y.transpose() << "\n" + << "expected: " << expected_y.transpose() + << "matrix: \n " << dense; +} + +// IntPairToLong is private, thus this fixture is needed to access and +// test it. +class BlockRandomAccessSparseMatrixTest : public ::testing::Test { + public: + virtual void SetUp() { + vector blocks; + blocks.push_back(1); + set< pair > block_pairs; + block_pairs.insert(make_pair(0, 0)); + m_.reset(new BlockRandomAccessSparseMatrix(blocks, block_pairs)); + } + + void CheckIntPairToLong(int a, int b) { + int64 value = m_->IntPairToLong(a, b); + EXPECT_GT(value, 0) << "Overflow a = " << a << " b = " << b; + EXPECT_GT(value, a) << "Overflow a = " << a << " b = " << b; + EXPECT_GT(value, b) << "Overflow a = " << a << " b = " << b; + } + + void CheckLongToIntPair() { + uint64 max_rows = m_->kMaxRowBlocks; + for (int row = max_rows - 10; row < max_rows; ++row) { + for (int col = 0; col < 10; ++col) { + int row_computed; + int col_computed; + m_->LongToIntPair(m_->IntPairToLong(row, col), + &row_computed, + &col_computed); + EXPECT_EQ(row, row_computed); + EXPECT_EQ(col, col_computed); + } + } + } + + private: + scoped_ptr m_; +}; + +TEST_F(BlockRandomAccessSparseMatrixTest, IntPairToLongOverflow) { + CheckIntPairToLong(std::numeric_limits::max(), + std::numeric_limits::max()); +} + +TEST_F(BlockRandomAccessSparseMatrixTest, LongToIntPair) { + CheckLongToIntPair(); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_sparse_matrix.cc b/internal/ceres/block_sparse_matrix.cc new file mode 100644 index 0000000..214daef --- /dev/null +++ b/internal/ceres/block_sparse_matrix.cc @@ -0,0 +1,398 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_sparse_matrix.h" + +#include +#include +#include +#include "ceres/block_structure.h" +#include "ceres/internal/eigen.h" +#include "ceres/random.h" +#include "ceres/small_blas.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +BlockSparseMatrix::~BlockSparseMatrix() {} + +BlockSparseMatrix::BlockSparseMatrix( + CompressedRowBlockStructure* block_structure) + : num_rows_(0), + num_cols_(0), + num_nonzeros_(0), + values_(NULL), + block_structure_(block_structure) { + CHECK_NOTNULL(block_structure_.get()); + + // Count the number of columns in the matrix. + for (int i = 0; i < block_structure_->cols.size(); ++i) { + num_cols_ += block_structure_->cols[i].size; + } + + // Count the number of non-zero entries and the number of rows in + // the matrix. + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_size = block_structure_->rows[i].block.size; + num_rows_ += row_block_size; + + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + num_nonzeros_ += col_block_size * row_block_size; + } + } + + CHECK_GE(num_rows_, 0); + CHECK_GE(num_cols_, 0); + CHECK_GE(num_nonzeros_, 0); + VLOG(2) << "Allocating values array with " + << num_nonzeros_ * sizeof(double) << " bytes."; // NOLINT + values_.reset(new double[num_nonzeros_]); + max_num_nonzeros_ = num_nonzeros_; + CHECK_NOTNULL(values_.get()); +} + +void BlockSparseMatrix::SetZero() { + std::fill(values_.get(), values_.get() + num_nonzeros_, 0.0); +} + +void BlockSparseMatrix::RightMultiply(const double* x, double* y) const { + CHECK_NOTNULL(x); + CHECK_NOTNULL(y); + + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_pos = block_structure_->rows[i].block.position; + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + MatrixVectorMultiply( + values_.get() + cells[j].position, row_block_size, col_block_size, + x + col_block_pos, + y + row_block_pos); + } + } +} + +void BlockSparseMatrix::LeftMultiply(const double* x, double* y) const { + CHECK_NOTNULL(x); + CHECK_NOTNULL(y); + + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_pos = block_structure_->rows[i].block.position; + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + MatrixTransposeVectorMultiply( + values_.get() + cells[j].position, row_block_size, col_block_size, + x + row_block_pos, + y + col_block_pos); + } + } +} + +void BlockSparseMatrix::SquaredColumnNorm(double* x) const { + CHECK_NOTNULL(x); + VectorRef(x, num_cols_).setZero(); + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + const MatrixRef m(values_.get() + cells[j].position, + row_block_size, col_block_size); + VectorRef(x + col_block_pos, col_block_size) += m.colwise().squaredNorm(); + } + } +} + +void BlockSparseMatrix::ScaleColumns(const double* scale) { + CHECK_NOTNULL(scale); + + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + MatrixRef m(values_.get() + cells[j].position, + row_block_size, col_block_size); + m *= ConstVectorRef(scale + col_block_pos, col_block_size).asDiagonal(); + } + } +} + +void BlockSparseMatrix::ToDenseMatrix(Matrix* dense_matrix) const { + CHECK_NOTNULL(dense_matrix); + + dense_matrix->resize(num_rows_, num_cols_); + dense_matrix->setZero(); + Matrix& m = *dense_matrix; + + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_pos = block_structure_->rows[i].block.position; + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + int jac_pos = cells[j].position; + m.block(row_block_pos, col_block_pos, row_block_size, col_block_size) + += MatrixRef(values_.get() + jac_pos, row_block_size, col_block_size); + } + } +} + +void BlockSparseMatrix::ToTripletSparseMatrix( + TripletSparseMatrix* matrix) const { + CHECK_NOTNULL(matrix); + + matrix->Reserve(num_nonzeros_); + matrix->Resize(num_rows_, num_cols_); + matrix->SetZero(); + + for (int i = 0; i < block_structure_->rows.size(); ++i) { + int row_block_pos = block_structure_->rows[i].block.position; + int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + int col_block_id = cells[j].block_id; + int col_block_size = block_structure_->cols[col_block_id].size; + int col_block_pos = block_structure_->cols[col_block_id].position; + int jac_pos = cells[j].position; + for (int r = 0; r < row_block_size; ++r) { + for (int c = 0; c < col_block_size; ++c, ++jac_pos) { + matrix->mutable_rows()[jac_pos] = row_block_pos + r; + matrix->mutable_cols()[jac_pos] = col_block_pos + c; + matrix->mutable_values()[jac_pos] = values_[jac_pos]; + } + } + } + } + matrix->set_num_nonzeros(num_nonzeros_); +} + +// Return a pointer to the block structure. We continue to hold +// ownership of the object though. +const CompressedRowBlockStructure* BlockSparseMatrix::block_structure() + const { + return block_structure_.get(); +} + +void BlockSparseMatrix::ToTextFile(FILE* file) const { + CHECK_NOTNULL(file); + for (int i = 0; i < block_structure_->rows.size(); ++i) { + const int row_block_pos = block_structure_->rows[i].block.position; + const int row_block_size = block_structure_->rows[i].block.size; + const vector& cells = block_structure_->rows[i].cells; + for (int j = 0; j < cells.size(); ++j) { + const int col_block_id = cells[j].block_id; + const int col_block_size = block_structure_->cols[col_block_id].size; + const int col_block_pos = block_structure_->cols[col_block_id].position; + int jac_pos = cells[j].position; + for (int r = 0; r < row_block_size; ++r) { + for (int c = 0; c < col_block_size; ++c) { + fprintf(file, "% 10d % 10d %17f\n", + row_block_pos + r, + col_block_pos + c, + values_[jac_pos++]); + } + } + } + } +} + +BlockSparseMatrix* BlockSparseMatrix::CreateDiagonalMatrix( + const double* diagonal, const std::vector& column_blocks) { + // Create the block structure for the diagonal matrix. + CompressedRowBlockStructure* bs = new CompressedRowBlockStructure(); + bs->cols = column_blocks; + int position = 0; + bs->rows.resize(column_blocks.size(), CompressedRow(1)); + for (int i = 0; i < column_blocks.size(); ++i) { + CompressedRow& row = bs->rows[i]; + row.block = column_blocks[i]; + Cell& cell = row.cells[0]; + cell.block_id = i; + cell.position = position; + position += row.block.size * row.block.size; + } + + // Create the BlockSparseMatrix with the given block structure. + BlockSparseMatrix* matrix = new BlockSparseMatrix(bs); + matrix->SetZero(); + + // Fill the values array of the block sparse matrix. + double* values = matrix->mutable_values(); + for (int i = 0; i < column_blocks.size(); ++i) { + const int size = column_blocks[i].size; + for (int j = 0; j < size; ++j) { + // (j + 1) * size is compact way of accessing the (j,j) entry. + values[j * (size + 1)] = diagonal[j]; + } + diagonal += size; + values += size * size; + } + + return matrix; +} + +void BlockSparseMatrix::AppendRows(const BlockSparseMatrix& m) { + const int old_num_nonzeros = num_nonzeros_; + const int old_num_row_blocks = block_structure_->rows.size(); + const CompressedRowBlockStructure* m_bs = m.block_structure(); + block_structure_->rows.resize(old_num_row_blocks + m_bs->rows.size()); + + for (int i = 0; i < m_bs->rows.size(); ++i) { + const CompressedRow& m_row = m_bs->rows[i]; + CompressedRow& row = block_structure_->rows[old_num_row_blocks + i]; + row.block.size = m_row.block.size; + row.block.position = num_rows_; + num_rows_ += m_row.block.size; + row.cells.resize(m_row.cells.size()); + for (int c = 0; c < m_row.cells.size(); ++c) { + const int block_id = m_row.cells[c].block_id; + row.cells[c].block_id = block_id; + row.cells[c].position = num_nonzeros_; + num_nonzeros_ += m_row.block.size * m_bs->cols[block_id].size; + } + } + + if (num_nonzeros_ > max_num_nonzeros_) { + double* new_values = new double[num_nonzeros_]; + std::copy(values_.get(), values_.get() + old_num_nonzeros, new_values); + values_.reset(new_values); + max_num_nonzeros_ = num_nonzeros_; + } + + std::copy(m.values(), + m.values() + m.num_nonzeros(), + values_.get() + old_num_nonzeros); +} + +void BlockSparseMatrix::DeleteRowBlocks(const int delta_row_blocks) { + const int num_row_blocks = block_structure_->rows.size(); + int delta_num_nonzeros = 0; + int delta_num_rows = 0; + const std::vector& column_blocks = block_structure_->cols; + for (int i = 0; i < delta_row_blocks; ++i) { + const CompressedRow& row = block_structure_->rows[num_row_blocks - i - 1]; + delta_num_rows += row.block.size; + for (int c = 0; c < row.cells.size(); ++c) { + const Cell& cell = row.cells[c]; + delta_num_nonzeros += row.block.size * column_blocks[cell.block_id].size; + } + } + num_nonzeros_ -= delta_num_nonzeros; + num_rows_ -= delta_num_rows; + block_structure_->rows.resize(num_row_blocks - delta_row_blocks); +} + +BlockSparseMatrix* BlockSparseMatrix::CreateRandomMatrix( + const BlockSparseMatrix::RandomMatrixOptions& options) { + CHECK_GT(options.num_row_blocks, 0); + CHECK_GT(options.min_row_block_size, 0); + CHECK_GT(options.max_row_block_size, 0); + CHECK_LE(options.min_row_block_size, options.max_row_block_size); + CHECK_GT(options.num_col_blocks, 0); + CHECK_GT(options.min_col_block_size, 0); + CHECK_GT(options.max_col_block_size, 0); + CHECK_LE(options.min_col_block_size, options.max_col_block_size); + CHECK_GT(options.block_density, 0.0); + CHECK_LE(options.block_density, 1.0); + + CompressedRowBlockStructure* bs = new CompressedRowBlockStructure(); + // Generate the col block structure. + int col_block_position = 0; + for (int i = 0; i < options.num_col_blocks; ++i) { + // Generate a random integer in [min_col_block_size, max_col_block_size] + const int delta_block_size = + Uniform(options.max_col_block_size - options.min_col_block_size); + const int col_block_size = options.min_col_block_size + delta_block_size; + bs->cols.push_back(Block(col_block_size, col_block_position)); + col_block_position += col_block_size; + } + + + bool matrix_has_blocks = false; + while (!matrix_has_blocks) { + LOG(INFO) << "clearing"; + bs->rows.clear(); + int row_block_position = 0; + int value_position = 0; + for (int r = 0; r < options.num_row_blocks; ++r) { + + const int delta_block_size = + Uniform(options.max_row_block_size - options.min_row_block_size); + const int row_block_size = options.min_row_block_size + delta_block_size; + bs->rows.push_back(CompressedRow()); + CompressedRow& row = bs->rows.back(); + row.block.size = row_block_size; + row.block.position = row_block_position; + row_block_position += row_block_size; + for (int c = 0; c < options.num_col_blocks; ++c) { + if (RandDouble() > options.block_density) continue; + + row.cells.push_back(Cell()); + Cell& cell = row.cells.back(); + cell.block_id = c; + cell.position = value_position; + value_position += row_block_size * bs->cols[c].size; + matrix_has_blocks = true; + } + } + } + + BlockSparseMatrix* matrix = new BlockSparseMatrix(bs); + double* values = matrix->mutable_values(); + for (int i = 0; i < matrix->num_nonzeros(); ++i) { + values[i] = RandNormal(); + } + + return matrix; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_sparse_matrix.h b/internal/ceres/block_sparse_matrix.h new file mode 100644 index 0000000..17491bf --- /dev/null +++ b/internal/ceres/block_sparse_matrix.h @@ -0,0 +1,143 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Implementation of the SparseMatrix interface for block sparse +// matrices. + +#ifndef CERES_INTERNAL_BLOCK_SPARSE_MATRIX_H_ +#define CERES_INTERNAL_BLOCK_SPARSE_MATRIX_H_ + +#include "ceres/block_structure.h" +#include "ceres/sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/scoped_ptr.h" + +namespace ceres { +namespace internal { + +class TripletSparseMatrix; + +// This class implements the SparseMatrix interface for storing and +// manipulating block sparse matrices. The block structure is stored +// in the CompressedRowBlockStructure object and one is needed to +// initialize the matrix. For details on how the blocks structure of +// the matrix is stored please see the documentation +// +// internal/ceres/block_structure.h +// +class BlockSparseMatrix : public SparseMatrix { + public: + // Construct a block sparse matrix with a fully initialized + // CompressedRowBlockStructure objected. The matrix takes over + // ownership of this object and destroys it upon destruction. + // + // TODO(sameeragarwal): Add a function which will validate legal + // CompressedRowBlockStructure objects. + explicit BlockSparseMatrix(CompressedRowBlockStructure* block_structure); + + BlockSparseMatrix(); + virtual ~BlockSparseMatrix(); + + // Implementation of SparseMatrix interface. + virtual void SetZero(); + virtual void RightMultiply(const double* x, double* y) const; + virtual void LeftMultiply(const double* x, double* y) const; + virtual void SquaredColumnNorm(double* x) const; + virtual void ScaleColumns(const double* scale); + virtual void ToDenseMatrix(Matrix* dense_matrix) const; + virtual void ToTextFile(FILE* file) const; + + virtual int num_rows() const { return num_rows_; } + virtual int num_cols() const { return num_cols_; } + virtual int num_nonzeros() const { return num_nonzeros_; } + virtual const double* values() const { return values_.get(); } + virtual double* mutable_values() { return values_.get(); } + + void ToTripletSparseMatrix(TripletSparseMatrix* matrix) const; + const CompressedRowBlockStructure* block_structure() const; + + // Append the contents of m to the bottom of this matrix. m must + // have the same column blocks structure as this matrix. + void AppendRows(const BlockSparseMatrix& m); + + // Delete the bottom delta_rows_blocks. + void DeleteRowBlocks(int delta_row_blocks); + + static BlockSparseMatrix* CreateDiagonalMatrix( + const double* diagonal, + const std::vector& column_blocks); + + struct RandomMatrixOptions { + RandomMatrixOptions() + : num_row_blocks(0), + min_row_block_size(0), + max_row_block_size(0), + num_col_blocks(0), + min_col_block_size(0), + max_col_block_size(0), + block_density(0.0) { + } + + int num_row_blocks; + int min_row_block_size; + int max_row_block_size; + int num_col_blocks; + int min_col_block_size; + int max_col_block_size; + + // 0 < block_density <= 1 is the probability of a block being + // present in the matrix. A given random matrix will not have + // precisely this density. + double block_density; + }; + + // Create a random BlockSparseMatrix whose entries are normally + // distributed and whose structure is determined by + // RandomMatrixOptions. + // + // Caller owns the result. + static BlockSparseMatrix* CreateRandomMatrix( + const RandomMatrixOptions& options); + + private: + int num_rows_; + int num_cols_; + int num_nonzeros_; + int max_num_nonzeros_; + scoped_array values_; + scoped_ptr block_structure_; + CERES_DISALLOW_COPY_AND_ASSIGN(BlockSparseMatrix); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_SPARSE_MATRIX_H_ diff --git a/internal/ceres/block_sparse_matrix_test.cc b/internal/ceres/block_sparse_matrix_test.cc new file mode 100644 index 0000000..b3d21d0 --- /dev/null +++ b/internal/ceres/block_sparse_matrix_test.cc @@ -0,0 +1,218 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_sparse_matrix.h" + +#include +#include "ceres/casts.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +class BlockSparseMatrixTest : public ::testing::Test { + protected : + virtual void SetUp() { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(2)); + CHECK_NOTNULL(problem.get()); + A_.reset(down_cast(problem->A.release())); + + problem.reset(CreateLinearLeastSquaresProblemFromId(1)); + CHECK_NOTNULL(problem.get()); + B_.reset(down_cast(problem->A.release())); + + CHECK_EQ(A_->num_rows(), B_->num_rows()); + CHECK_EQ(A_->num_cols(), B_->num_cols()); + CHECK_EQ(A_->num_nonzeros(), B_->num_nonzeros()); + } + + scoped_ptr A_; + scoped_ptr B_; +}; + +TEST_F(BlockSparseMatrixTest, SetZeroTest) { + A_->SetZero(); + EXPECT_EQ(13, A_->num_nonzeros()); +} + +TEST_F(BlockSparseMatrixTest, RightMultiplyTest) { + Vector y_a = Vector::Zero(A_->num_rows()); + Vector y_b = Vector::Zero(A_->num_rows()); + for (int i = 0; i < A_->num_cols(); ++i) { + Vector x = Vector::Zero(A_->num_cols()); + x[i] = 1.0; + A_->RightMultiply(x.data(), y_a.data()); + B_->RightMultiply(x.data(), y_b.data()); + EXPECT_LT((y_a - y_b).norm(), 1e-12); + } +} + +TEST_F(BlockSparseMatrixTest, LeftMultiplyTest) { + Vector y_a = Vector::Zero(A_->num_cols()); + Vector y_b = Vector::Zero(A_->num_cols()); + for (int i = 0; i < A_->num_rows(); ++i) { + Vector x = Vector::Zero(A_->num_rows()); + x[i] = 1.0; + A_->LeftMultiply(x.data(), y_a.data()); + B_->LeftMultiply(x.data(), y_b.data()); + EXPECT_LT((y_a - y_b).norm(), 1e-12); + } +} + +TEST_F(BlockSparseMatrixTest, SquaredColumnNormTest) { + Vector y_a = Vector::Zero(A_->num_cols()); + Vector y_b = Vector::Zero(A_->num_cols()); + A_->SquaredColumnNorm(y_a.data()); + B_->SquaredColumnNorm(y_b.data()); + EXPECT_LT((y_a - y_b).norm(), 1e-12); +} + +TEST_F(BlockSparseMatrixTest, ToDenseMatrixTest) { + Matrix m_a; + Matrix m_b; + A_->ToDenseMatrix(&m_a); + B_->ToDenseMatrix(&m_b); + EXPECT_LT((m_a - m_b).norm(), 1e-12); +} + +TEST_F(BlockSparseMatrixTest, AppendRows) { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(2)); + scoped_ptr m( + down_cast(problem->A.release())); + A_->AppendRows(*m); + EXPECT_EQ(A_->num_rows(), 2 * m->num_rows()); + EXPECT_EQ(A_->num_cols(), m->num_cols()); + + problem.reset(CreateLinearLeastSquaresProblemFromId(1)); + scoped_ptr m2( + down_cast(problem->A.release())); + B_->AppendRows(*m2); + + Vector y_a = Vector::Zero(A_->num_rows()); + Vector y_b = Vector::Zero(A_->num_rows()); + for (int i = 0; i < A_->num_cols(); ++i) { + Vector x = Vector::Zero(A_->num_cols()); + x[i] = 1.0; + y_a.setZero(); + y_b.setZero(); + + A_->RightMultiply(x.data(), y_a.data()); + B_->RightMultiply(x.data(), y_b.data()); + EXPECT_LT((y_a - y_b).norm(), 1e-12); + } +} + +TEST_F(BlockSparseMatrixTest, AppendAndDeleteBlockDiagonalMatrix) { + const std::vector& column_blocks = A_->block_structure()->cols; + const int num_cols = + column_blocks.back().size + column_blocks.back().position; + Vector diagonal(num_cols); + for (int i = 0; i < num_cols; ++i) { + diagonal(i) = 2 * i * i + 1; + } + scoped_ptr appendage( + BlockSparseMatrix::CreateDiagonalMatrix(diagonal.data(), column_blocks)); + + A_->AppendRows(*appendage); + Vector y_a, y_b; + y_a.resize(A_->num_rows()); + y_b.resize(A_->num_rows()); + for (int i = 0; i < A_->num_cols(); ++i) { + Vector x = Vector::Zero(A_->num_cols()); + x[i] = 1.0; + y_a.setZero(); + y_b.setZero(); + + A_->RightMultiply(x.data(), y_a.data()); + B_->RightMultiply(x.data(), y_b.data()); + EXPECT_LT((y_a.head(B_->num_rows()) - y_b.head(B_->num_rows())).norm(), 1e-12); + Vector expected_tail = Vector::Zero(A_->num_cols()); + expected_tail(i) = diagonal(i); + EXPECT_LT((y_a.tail(A_->num_cols()) - expected_tail).norm(), 1e-12); + } + + + A_->DeleteRowBlocks(column_blocks.size()); + EXPECT_EQ(A_->num_rows(), B_->num_rows()); + EXPECT_EQ(A_->num_cols(), B_->num_cols()); + + y_a.resize(A_->num_rows()); + y_b.resize(A_->num_rows()); + for (int i = 0; i < A_->num_cols(); ++i) { + Vector x = Vector::Zero(A_->num_cols()); + x[i] = 1.0; + y_a.setZero(); + y_b.setZero(); + + A_->RightMultiply(x.data(), y_a.data()); + B_->RightMultiply(x.data(), y_b.data()); + EXPECT_LT((y_a - y_b).norm(), 1e-12); + } +} + +TEST(BlockSparseMatrix, CreateDiagonalMatrix) { + std::vector column_blocks; + column_blocks.push_back(Block(2, 0)); + column_blocks.push_back(Block(1, 2)); + column_blocks.push_back(Block(3, 3)); + const int num_cols = + column_blocks.back().size + column_blocks.back().position; + Vector diagonal(num_cols); + for (int i = 0; i < num_cols; ++i) { + diagonal(i) = 2 * i * i + 1; + } + + scoped_ptr m( + BlockSparseMatrix::CreateDiagonalMatrix(diagonal.data(), column_blocks)); + const CompressedRowBlockStructure* bs = m->block_structure(); + EXPECT_EQ(bs->cols.size(), column_blocks.size()); + for (int i = 0; i < column_blocks.size(); ++i) { + EXPECT_EQ(bs->cols[i].size, column_blocks[i].size); + EXPECT_EQ(bs->cols[i].position, column_blocks[i].position); + } + EXPECT_EQ(m->num_rows(), m->num_cols()); + Vector x = Vector::Ones(num_cols); + Vector y = Vector::Zero(num_cols); + m->RightMultiply(x.data(), y.data()); + for (int i = 0; i < num_cols; ++i) { + EXPECT_NEAR(y[i], diagonal[i], std::numeric_limits::epsilon()); + } +} + + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_structure.cc b/internal/ceres/block_structure.cc new file mode 100644 index 0000000..6479b60 --- /dev/null +++ b/internal/ceres/block_structure.cc @@ -0,0 +1,44 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/block_structure.h" + +namespace ceres { +namespace internal { + +bool CellLessThan(const Cell& lhs, const Cell& rhs) { + if (lhs.block_id == rhs.block_id) { + return (lhs.position < rhs.position); + } + return (lhs.block_id < rhs.block_id); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/block_structure.h b/internal/ceres/block_structure.h new file mode 100644 index 0000000..9d1b5e9 --- /dev/null +++ b/internal/ceres/block_structure.h @@ -0,0 +1,98 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Block structure objects are used to carry information about the +// dense block structure of sparse matrices. The BlockSparseMatrix +// object uses the BlockStructure objects to keep track of the matrix +// structure and operate upon it. This allows us to use more cache +// friendly block oriented linear algebra operations on the matrix +// instead of accessing it one scalar entry at a time. + +#ifndef CERES_INTERNAL_BLOCK_STRUCTURE_H_ +#define CERES_INTERNAL_BLOCK_STRUCTURE_H_ + +#include +#include "ceres/internal/port.h" +#include "ceres/types.h" + +namespace ceres { +namespace internal { + +typedef int32 BlockSize; + +struct Block { + Block() : size(-1), position(-1) {} + Block(int size_, int position_) : size(size_), position(position_) {} + + BlockSize size; + int position; // Position along the row/column. +}; + +struct Cell { + Cell() : block_id(-1), position(-1) {} + Cell(int block_id_, int position_) + : block_id(block_id_), position(position_) {} + + // Column or row block id as the case maybe. + int block_id; + // Where in the values array of the jacobian is this cell located. + int position; +}; + +// Order cell by their block_id; +bool CellLessThan(const Cell& lhs, const Cell& rhs); + +struct CompressedList { + CompressedList() {} + + // Construct a CompressedList with the cells containing num_cells + // entries. + CompressedList(int num_cells) : cells(num_cells) {} + Block block; + std::vector cells; +}; + +typedef CompressedList CompressedRow; +typedef CompressedList CompressedColumn; + +struct CompressedRowBlockStructure { + std::vector cols; + std::vector rows; +}; + +struct CompressedColumnBlockStructure { + std::vector rows; + std::vector cols; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_BLOCK_STRUCTURE_H_ diff --git a/internal/ceres/bundle_adjustment_test.cc b/internal/ceres/bundle_adjustment_test.cc new file mode 100644 index 0000000..7cbf3f3 --- /dev/null +++ b/internal/ceres/bundle_adjustment_test.cc @@ -0,0 +1,561 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) +// +// End-to-end bundle adjustment tests for Ceres. It uses a bundle +// adjustment problem with 16 cameras and two thousand points. + +#include +#include +#include +#include + +#include "ceres/internal/port.h" + +#include "ceres/autodiff_cost_function.h" +#include "ceres/ordered_groups.h" +#include "ceres/problem.h" +#include "ceres/rotation.h" +#include "ceres/solver.h" +#include "ceres/stringprintf.h" +#include "ceres/test_util.h" +#include "ceres/types.h" +#include "gflags/gflags.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::string; +using std::vector; + +const bool kAutomaticOrdering = true; +const bool kUserOrdering = false; + +// This class implements the SystemTestProblem interface and provides +// access to a bundle adjustment problem. It is based on +// examples/bundle_adjustment_example.cc. Currently a small 16 camera +// problem is hard coded in the constructor. +class BundleAdjustmentProblem { + public: + BundleAdjustmentProblem() { + const string input_file = TestFileAbsolutePath("problem-16-22106-pre.txt"); + ReadData(input_file); + BuildProblem(); + } + + ~BundleAdjustmentProblem() { + delete []point_index_; + delete []camera_index_; + delete []observations_; + delete []parameters_; + } + + Problem* mutable_problem() { return &problem_; } + Solver::Options* mutable_solver_options() { return &options_; } + + int num_cameras() const { return num_cameras_; } + int num_points() const { return num_points_; } + int num_observations() const { return num_observations_; } + const int* point_index() const { return point_index_; } + const int* camera_index() const { return camera_index_; } + const double* observations() const { return observations_; } + double* mutable_cameras() { return parameters_; } + double* mutable_points() { return parameters_ + 9 * num_cameras_; } + + static double kResidualTolerance; + + private: + void ReadData(const string& filename) { + FILE * fptr = fopen(filename.c_str(), "r"); + + if (!fptr) { + LOG(FATAL) << "File Error: unable to open file " << filename; + } + + // This will die horribly on invalid files. Them's the breaks. + FscanfOrDie(fptr, "%d", &num_cameras_); + FscanfOrDie(fptr, "%d", &num_points_); + FscanfOrDie(fptr, "%d", &num_observations_); + + VLOG(1) << "Header: " << num_cameras_ + << " " << num_points_ + << " " << num_observations_; + + point_index_ = new int[num_observations_]; + camera_index_ = new int[num_observations_]; + observations_ = new double[2 * num_observations_]; + + num_parameters_ = 9 * num_cameras_ + 3 * num_points_; + parameters_ = new double[num_parameters_]; + + for (int i = 0; i < num_observations_; ++i) { + FscanfOrDie(fptr, "%d", camera_index_ + i); + FscanfOrDie(fptr, "%d", point_index_ + i); + for (int j = 0; j < 2; ++j) { + FscanfOrDie(fptr, "%lf", observations_ + 2*i + j); + } + } + + for (int i = 0; i < num_parameters_; ++i) { + FscanfOrDie(fptr, "%lf", parameters_ + i); + } + } + + void BuildProblem() { + double* points = mutable_points(); + double* cameras = mutable_cameras(); + + for (int i = 0; i < num_observations(); ++i) { + // Each Residual block takes a point and a camera as input and + // outputs a 2 dimensional residual. + CostFunction* cost_function = + new AutoDiffCostFunction( + new BundlerResidual(observations_[2*i + 0], + observations_[2*i + 1])); + + // Each observation correponds to a pair of a camera and a point + // which are identified by camera_index()[i] and + // point_index()[i] respectively. + double* camera = cameras + 9 * camera_index_[i]; + double* point = points + 3 * point_index()[i]; + problem_.AddResidualBlock(cost_function, NULL, camera, point); + } + + options_.linear_solver_ordering.reset(new ParameterBlockOrdering); + + // The points come before the cameras. + for (int i = 0; i < num_points_; ++i) { + options_.linear_solver_ordering->AddElementToGroup(points + 3 * i, 0); + } + + for (int i = 0; i < num_cameras_; ++i) { + options_.linear_solver_ordering->AddElementToGroup(cameras + 9 * i, 1); + } + + options_.linear_solver_type = DENSE_SCHUR; + options_.max_num_iterations = 25; + options_.function_tolerance = 1e-10; + options_.gradient_tolerance = 1e-10; + options_.parameter_tolerance = 1e-10; + } + + template + void FscanfOrDie(FILE *fptr, const char *format, T *value) { + int num_scanned = fscanf(fptr, format, value); + if (num_scanned != 1) { + LOG(FATAL) << "Invalid UW data file."; + } + } + + // Templated pinhole camera model. The camera is parameterized + // using 9 parameters. 3 for rotation, 3 for translation, 1 for + // focal length and 2 for radial distortion. The principal point is + // not modeled (i.e. it is assumed to be located at the image + // center). + struct BundlerResidual { + // (u, v): the position of the observation with respect to the image + // center point. + BundlerResidual(double u, double v): u(u), v(v) {} + + template + bool operator()(const T* const camera, + const T* const point, + T* residuals) const { + T p[3]; + AngleAxisRotatePoint(camera, point, p); + + // Add the translation vector + p[0] += camera[3]; + p[1] += camera[4]; + p[2] += camera[5]; + + const T& focal = camera[6]; + const T& l1 = camera[7]; + const T& l2 = camera[8]; + + // Compute the center of distortion. The sign change comes from + // the camera model that Noah Snavely's Bundler assumes, whereby + // the camera coordinate system has a negative z axis. + T xp = - focal * p[0] / p[2]; + T yp = - focal * p[1] / p[2]; + + // Apply second and fourth order radial distortion. + T r2 = xp*xp + yp*yp; + T distortion = T(1.0) + r2 * (l1 + l2 * r2); + + residuals[0] = distortion * xp - u; + residuals[1] = distortion * yp - v; + + return true; + } + + double u; + double v; + }; + + Problem problem_; + Solver::Options options_; + + int num_cameras_; + int num_points_; + int num_observations_; + int num_parameters_; + + int* point_index_; + int* camera_index_; + double* observations_; + // The parameter vector is laid out as follows + // [camera_1, ..., camera_n, point_1, ..., point_m] + double* parameters_; +}; + +double BundleAdjustmentProblem::kResidualTolerance = 1e-4; +typedef SystemTest BundleAdjustmentTest; + +TEST_F(BundleAdjustmentTest, DenseSchurWithAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(DENSE_SCHUR, NO_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, DenseSchurWithUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(DENSE_SCHUR, NO_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, IterativeSchurWithJacobiAndAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, NO_SPARSE, kAutomaticOrdering, JACOBI)); +} + +TEST_F(BundleAdjustmentTest, IterativeSchurWithJacobiAndUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, NO_SPARSE, kUserOrdering, JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + IterativeSchurWithSchurJacobiAndAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, + NO_SPARSE, + kAutomaticOrdering, + SCHUR_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, IterativeSchurWithSchurJacobiAndUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, NO_SPARSE, kUserOrdering, SCHUR_JACOBI)); +} + +#ifndef CERES_NO_SUITESPARSE +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, SUITE_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, SUITE_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + SparseSchurWithAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, SUITE_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, SparseSchurWithUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, SUITE_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + IterativeSchurWithClusterJacobiAndAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kAutomaticOrdering, + CLUSTER_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + IterativeSchurWithClusterJacobiAndUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kUserOrdering, + CLUSTER_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + IterativeSchurWithClusterTridiagonalAndAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kAutomaticOrdering, + CLUSTER_TRIDIAGONAL)); +} + +TEST_F(BundleAdjustmentTest, + IterativeSchurWithClusterTridiagonalAndUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kUserOrdering, + CLUSTER_TRIDIAGONAL)); +} +#endif // CERES_NO_SUITESPARSE + +#ifndef CERES_NO_CXSPARSE +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithAutomaticOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, CX_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithUserOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, CX_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, SparseSchurWithAutomaticOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, CX_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, SparseSchurWithUserOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, CX_SPARSE, kUserOrdering)); +} +#endif // CERES_NO_CXSPARSE + +#ifdef CERES_USE_EIGEN_SPARSE +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithAutomaticOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, EIGEN_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + SparseNormalCholeskyWithUserOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_NORMAL_CHOLESKY, EIGEN_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + SparseSchurWithAutomaticOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, EIGEN_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, SparseSchurWithUserOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + SolverConfig(SPARSE_SCHUR, EIGEN_SPARSE, kUserOrdering)); +} +#endif // CERES_USE_EIGEN_SPARSE + +#ifdef CERES_USE_OPENMP + +TEST_F(BundleAdjustmentTest, MultiThreadedDenseSchurWithAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(DENSE_SCHUR, NO_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, MultiThreadedDenseSchurWithUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(DENSE_SCHUR, NO_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithJacobiAndAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + NO_SPARSE, + kAutomaticOrdering, + JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithJacobiAndUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, NO_SPARSE, kUserOrdering, JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithSchurJacobiAndAutomaticOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + NO_SPARSE, + kAutomaticOrdering, + SCHUR_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithSchurJacobiAndUserOrdering) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + NO_SPARSE, + kUserOrdering, + SCHUR_JACOBI)); +} + +#ifndef CERES_NO_SUITESPARSE +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, + SUITE_SPARSE, + kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, + SUITE_SPARSE, + kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithAutomaticOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, + SUITE_SPARSE, + kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithUserOrderingUsingSuiteSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, SUITE_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithClusterJacobiAndAutomaticOrderingUsingSuiteSparse) { // NOLINT + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kAutomaticOrdering, + CLUSTER_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithClusterJacobiAndUserOrderingUsingSuiteSparse) { // NOLINT + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kUserOrdering, + CLUSTER_JACOBI)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithClusterTridiagonalAndAutomaticOrderingUsingSuiteSparse) { // NOLINT + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kAutomaticOrdering, + CLUSTER_TRIDIAGONAL)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedIterativeSchurWithClusterTridiagonalAndUserOrderingUsingSuiteSparse) { // NOTLINT + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(ITERATIVE_SCHUR, + SUITE_SPARSE, + kUserOrdering, + CLUSTER_TRIDIAGONAL)); +} +#endif // CERES_NO_SUITESPARSE + +#ifndef CERES_NO_CXSPARSE +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithAutomaticOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, + CX_SPARSE, + kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithUserOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, CX_SPARSE, kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithAutomaticOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, CX_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithUserOrderingUsingCXSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, CX_SPARSE, kUserOrdering)); +} +#endif // CERES_NO_CXSPARSE + +#ifdef CERES_USE_EIGEN_SPARSE +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithAutomaticOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, + EIGEN_SPARSE, + kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseNormalCholeskyWithUserOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_NORMAL_CHOLESKY, + EIGEN_SPARSE, + kUserOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithAutomaticOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, EIGEN_SPARSE, kAutomaticOrdering)); +} + +TEST_F(BundleAdjustmentTest, + MultiThreadedSparseSchurWithUserOrderingUsingEigenSparse) { + RunSolverForConfigAndExpectResidualsMatch( + ThreadedSolverConfig(SPARSE_SCHUR, EIGEN_SPARSE, kUserOrdering)); +} +#endif // CERES_USE_EIGEN_SPARSE +#endif // CERES_USE_OPENMP + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/c_api.cc b/internal/ceres/c_api.cc new file mode 100644 index 0000000..ada8f3e --- /dev/null +++ b/internal/ceres/c_api.cc @@ -0,0 +1,188 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: mierle@gmail.com (Keir Mierle) +// +// An incomplete C API for Ceres. +// +// TODO(keir): Figure out why logging does not seem to work. + +#include "ceres/c_api.h" + +#include +#include +#include +#include "ceres/cost_function.h" +#include "ceres/loss_function.h" +#include "ceres/problem.h" +#include "ceres/solver.h" +#include "ceres/types.h" // for std +#include "glog/logging.h" + +using ceres::Problem; + +void ceres_init() { + // This is not ideal, but it's not clear what to do if there is no gflags and + // no access to command line arguments. + char message[] = ""; + google::InitGoogleLogging(message); +} + +ceres_problem_t* ceres_create_problem() { + return reinterpret_cast(new Problem); +} + +void ceres_free_problem(ceres_problem_t* problem) { + delete reinterpret_cast(problem); +} + +// This cost function wraps a C-level function pointer from the user, to bridge +// between C and C++. +class CallbackCostFunction : public ceres::CostFunction { + public: + CallbackCostFunction(ceres_cost_function_t cost_function, + void* user_data, + int num_residuals, + int num_parameter_blocks, + int* parameter_block_sizes) + : cost_function_(cost_function), + user_data_(user_data) { + set_num_residuals(num_residuals); + for (int i = 0; i < num_parameter_blocks; ++i) { + mutable_parameter_block_sizes()->push_back(parameter_block_sizes[i]); + } + } + + virtual ~CallbackCostFunction() {} + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + return (*cost_function_)(user_data_, + const_cast(parameters), + residuals, + jacobians); + } + + private: + ceres_cost_function_t cost_function_; + void* user_data_; +}; + +// This loss function wraps a C-level function pointer from the user, to bridge +// between C and C++. +class CallbackLossFunction : public ceres::LossFunction { + public: + explicit CallbackLossFunction(ceres_loss_function_t loss_function, + void* user_data) + : loss_function_(loss_function), user_data_(user_data) {} + virtual void Evaluate(double sq_norm, double* rho) const { + (*loss_function_)(user_data_, sq_norm, rho); + } + + private: + ceres_loss_function_t loss_function_; + void* user_data_; +}; + +// Wrappers for the stock loss functions. +void* ceres_create_huber_loss_function_data(double a) { + return new ceres::HuberLoss(a); +} +void* ceres_create_softl1_loss_function_data(double a) { + return new ceres::SoftLOneLoss(a); +} +void* ceres_create_cauchy_loss_function_data(double a) { + return new ceres::CauchyLoss(a); +} +void* ceres_create_arctan_loss_function_data(double a) { + return new ceres::ArctanLoss(a); +} +void* ceres_create_tolerant_loss_function_data(double a, double b) { + return new ceres::TolerantLoss(a, b); +} + +void ceres_free_stock_loss_function_data(void* loss_function_data) { + delete reinterpret_cast(loss_function_data); +} + +void ceres_stock_loss_function(void* user_data, + double squared_norm, + double out[3]) { + reinterpret_cast(user_data) + ->Evaluate(squared_norm, out); +} + +ceres_residual_block_id_t* ceres_problem_add_residual_block( + ceres_problem_t* problem, + ceres_cost_function_t cost_function, + void* cost_function_data, + ceres_loss_function_t loss_function, + void* loss_function_data, + int num_residuals, + int num_parameter_blocks, + int* parameter_block_sizes, + double** parameters) { + Problem* ceres_problem = reinterpret_cast(problem); + + ceres::CostFunction* callback_cost_function = + new CallbackCostFunction(cost_function, + cost_function_data, + num_residuals, + num_parameter_blocks, + parameter_block_sizes); + + ceres::LossFunction* callback_loss_function = NULL; + if (loss_function != NULL) { + callback_loss_function = new CallbackLossFunction(loss_function, + loss_function_data); + } + + std::vector parameter_blocks(parameters, + parameters + num_parameter_blocks); + return reinterpret_cast( + ceres_problem->AddResidualBlock(callback_cost_function, + callback_loss_function, + parameter_blocks)); +} + +void ceres_solve(ceres_problem_t* c_problem) { + Problem* problem = reinterpret_cast(c_problem); + + // TODO(keir): Obviously, this way of setting options won't scale or last. + // Instead, figure out a way to specify some of the options without + // duplicating everything. + ceres::Solver::Options options; + options.max_num_iterations = 100; + options.linear_solver_type = ceres::DENSE_QR; + options.minimizer_progress_to_stdout = true; + + ceres::Solver::Summary summary; + ceres::Solve(options, problem, &summary); + std::cout << summary.FullReport() << "\n"; +} diff --git a/internal/ceres/c_api_test.cc b/internal/ceres/c_api_test.cc new file mode 100644 index 0000000..95b727a --- /dev/null +++ b/internal/ceres/c_api_test.cc @@ -0,0 +1,221 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: mierle@gmail.com (Keir Mierle) + +#include "ceres/c_api.h" + +#include + +#include "glog/logging.h" +#include "gtest/gtest.h" + +// Duplicated from curve_fitting.cc. +int num_observations = 67; +double data[] = { + 0.000000e+00, 1.133898e+00, + 7.500000e-02, 1.334902e+00, + 1.500000e-01, 1.213546e+00, + 2.250000e-01, 1.252016e+00, + 3.000000e-01, 1.392265e+00, + 3.750000e-01, 1.314458e+00, + 4.500000e-01, 1.472541e+00, + 5.250000e-01, 1.536218e+00, + 6.000000e-01, 1.355679e+00, + 6.750000e-01, 1.463566e+00, + 7.500000e-01, 1.490201e+00, + 8.250000e-01, 1.658699e+00, + 9.000000e-01, 1.067574e+00, + 9.750000e-01, 1.464629e+00, + 1.050000e+00, 1.402653e+00, + 1.125000e+00, 1.713141e+00, + 1.200000e+00, 1.527021e+00, + 1.275000e+00, 1.702632e+00, + 1.350000e+00, 1.423899e+00, + 1.425000e+00, 1.543078e+00, + 1.500000e+00, 1.664015e+00, + 1.575000e+00, 1.732484e+00, + 1.650000e+00, 1.543296e+00, + 1.725000e+00, 1.959523e+00, + 1.800000e+00, 1.685132e+00, + 1.875000e+00, 1.951791e+00, + 1.950000e+00, 2.095346e+00, + 2.025000e+00, 2.361460e+00, + 2.100000e+00, 2.169119e+00, + 2.175000e+00, 2.061745e+00, + 2.250000e+00, 2.178641e+00, + 2.325000e+00, 2.104346e+00, + 2.400000e+00, 2.584470e+00, + 2.475000e+00, 1.914158e+00, + 2.550000e+00, 2.368375e+00, + 2.625000e+00, 2.686125e+00, + 2.700000e+00, 2.712395e+00, + 2.775000e+00, 2.499511e+00, + 2.850000e+00, 2.558897e+00, + 2.925000e+00, 2.309154e+00, + 3.000000e+00, 2.869503e+00, + 3.075000e+00, 3.116645e+00, + 3.150000e+00, 3.094907e+00, + 3.225000e+00, 2.471759e+00, + 3.300000e+00, 3.017131e+00, + 3.375000e+00, 3.232381e+00, + 3.450000e+00, 2.944596e+00, + 3.525000e+00, 3.385343e+00, + 3.600000e+00, 3.199826e+00, + 3.675000e+00, 3.423039e+00, + 3.750000e+00, 3.621552e+00, + 3.825000e+00, 3.559255e+00, + 3.900000e+00, 3.530713e+00, + 3.975000e+00, 3.561766e+00, + 4.050000e+00, 3.544574e+00, + 4.125000e+00, 3.867945e+00, + 4.200000e+00, 4.049776e+00, + 4.275000e+00, 3.885601e+00, + 4.350000e+00, 4.110505e+00, + 4.425000e+00, 4.345320e+00, + 4.500000e+00, 4.161241e+00, + 4.575000e+00, 4.363407e+00, + 4.650000e+00, 4.161576e+00, + 4.725000e+00, 4.619728e+00, + 4.800000e+00, 4.737410e+00, + 4.875000e+00, 4.727863e+00, + 4.950000e+00, 4.669206e+00, +}; + +// A test cost function, similar to the one in curve_fitting.c. +int exponential_residual(void* user_data, + double** parameters, + double* residuals, + double** jacobians) { + double* measurement = (double*) user_data; + double x = measurement[0]; + double y = measurement[1]; + double m = parameters[0][0]; + double c = parameters[1][0]; + + residuals[0] = y - exp(m * x + c); + if (jacobians == NULL) { + return 1; + } + if (jacobians[0] != NULL) { + jacobians[0][0] = - x * exp(m * x + c); // dr/dm + } + if (jacobians[1] != NULL) { + jacobians[1][0] = - exp(m * x + c); // dr/dc + } + return 1; +} + +namespace ceres { +namespace internal { + +TEST(C_API, SimpleEndToEndTest) { + double m = 0.0; + double c = 0.0; + double *parameter_pointers[] = { &m, &c }; + int parameter_sizes[] = { 1, 1 }; + + ceres_problem_t* problem = ceres_create_problem(); + for (int i = 0; i < num_observations; ++i) { + ceres_problem_add_residual_block( + problem, + exponential_residual, // Cost function + &data[2 * i], // Points to the (x,y) measurement + NULL, // Loss function + NULL, // Loss function user data + 1, // Number of residuals + 2, // Number of parameter blocks + parameter_sizes, + parameter_pointers); + } + + ceres_solve(problem); + + EXPECT_NEAR(0.3, m, 0.02); + EXPECT_NEAR(0.1, c, 0.04); + + ceres_free_problem(problem); +} + +template +class ScopedSetValue { + public: + ScopedSetValue(T* variable, T new_value) + : variable_(variable), old_value_(*variable) { + *variable = new_value; + } + ~ScopedSetValue() { + *variable_ = old_value_; + } + + private: + T* variable_; + T old_value_; +}; + +TEST(C_API, LossFunctions) { + double m = 0.2; + double c = 0.03; + double *parameter_pointers[] = { &m, &c }; + int parameter_sizes[] = { 1, 1 }; + + // Create two outliers, but be careful to leave the data intact. + ScopedSetValue outlier1x(&data[12], 2.5); + ScopedSetValue outlier1y(&data[13], 1.0e3); + ScopedSetValue outlier2x(&data[14], 3.2); + ScopedSetValue outlier2y(&data[15], 30e3); + + // Create a cauchy cost function, and reuse it many times. + void* cauchy_loss_data = + ceres_create_cauchy_loss_function_data(5.0); + + ceres_problem_t* problem = ceres_create_problem(); + for (int i = 0; i < num_observations; ++i) { + ceres_problem_add_residual_block( + problem, + exponential_residual, // Cost function + &data[2 * i], // Points to the (x,y) measurement + ceres_stock_loss_function, + cauchy_loss_data, // Loss function user data + 1, // Number of residuals + 2, // Number of parameter blocks + parameter_sizes, + parameter_pointers); + } + + ceres_solve(problem); + + EXPECT_NEAR(0.3, m, 0.02); + EXPECT_NEAR(0.1, c, 0.04); + + ceres_free_stock_loss_function_data(cauchy_loss_data); + ceres_free_problem(problem); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/callbacks.cc b/internal/ceres/callbacks.cc new file mode 100644 index 0000000..50a0ec1 --- /dev/null +++ b/internal/ceres/callbacks.cc @@ -0,0 +1,111 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include // NO LINT +#include "ceres/callbacks.h" +#include "ceres/program.h" +#include "ceres/stringprintf.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::string; + +StateUpdatingCallback::StateUpdatingCallback(Program* program, + double* parameters) + : program_(program), parameters_(parameters) {} + +StateUpdatingCallback::~StateUpdatingCallback() {} + +CallbackReturnType StateUpdatingCallback::operator()( + const IterationSummary& summary) { + if (summary.step_is_successful) { + program_->StateVectorToParameterBlocks(parameters_); + program_->CopyParameterBlockStateToUserState(); + } + return SOLVER_CONTINUE; +} + +LoggingCallback::LoggingCallback(const MinimizerType minimizer_type, + const bool log_to_stdout) + : minimizer_type(minimizer_type), + log_to_stdout_(log_to_stdout) {} + +LoggingCallback::~LoggingCallback() {} + +CallbackReturnType LoggingCallback::operator()( + const IterationSummary& summary) { + string output; + if (minimizer_type == LINE_SEARCH) { + const char* kReportRowFormat = + "% 4d: f:% 8e d:% 3.2e g:% 3.2e h:% 3.2e " + "s:% 3.2e e:% 3d it:% 3.2e tt:% 3.2e"; + output = StringPrintf(kReportRowFormat, + summary.iteration, + summary.cost, + summary.cost_change, + summary.gradient_max_norm, + summary.step_norm, + summary.step_size, + summary.line_search_function_evaluations, + summary.iteration_time_in_seconds, + summary.cumulative_time_in_seconds); + } else if (minimizer_type == TRUST_REGION) { + if (summary.iteration == 0) { + output = "iter cost cost_change |gradient| |step| tr_ratio tr_radius ls_iter iter_time total_time\n"; // NOLINT + } + const char* kReportRowFormat = + "% 4d % 8e % 3.2e % 3.2e % 3.2e % 3.2e % 3.2e % 4d % 3.2e % 3.2e"; // NOLINT + output += StringPrintf(kReportRowFormat, + summary.iteration, + summary.cost, + summary.cost_change, + summary.gradient_max_norm, + summary.step_norm, + summary.relative_decrease, + summary.trust_region_radius, + summary.linear_solver_iterations, + summary.iteration_time_in_seconds, + summary.cumulative_time_in_seconds); + } else { + LOG(FATAL) << "Unknown minimizer type."; + } + + if (log_to_stdout_) { + std::cout << output << std::endl; + } else { + VLOG(1) << output; + } + return SOLVER_CONTINUE; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/callbacks.h b/internal/ceres/callbacks.h new file mode 100644 index 0000000..33c66df --- /dev/null +++ b/internal/ceres/callbacks.h @@ -0,0 +1,71 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_CALLBACKS_H_ +#define CERES_INTERNAL_CALLBACKS_H_ + +#include +#include "ceres/iteration_callback.h" +#include "ceres/internal/port.h" + +namespace ceres { +namespace internal { + +class Program; + +// Callback for updating the externally visible state of parameter +// blocks. +class StateUpdatingCallback : public IterationCallback { + public: + StateUpdatingCallback(Program* program, double* parameters); + virtual ~StateUpdatingCallback(); + virtual CallbackReturnType operator()(const IterationSummary& summary); + private: + Program* program_; + double* parameters_; +}; + +// Callback for logging the state of the minimizer to STDERR or +// STDOUT depending on the user's preferences and logging level. +class LoggingCallback : public IterationCallback { + public: + LoggingCallback(MinimizerType minimizer_type, bool log_to_stdout); + virtual ~LoggingCallback(); + virtual CallbackReturnType operator()(const IterationSummary& summary); + + private: + const MinimizerType minimizer_type; + const bool log_to_stdout_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CALLBACKS_H_ diff --git a/internal/ceres/canonical_views_clustering.cc b/internal/ceres/canonical_views_clustering.cc new file mode 100644 index 0000000..b3e9c22 --- /dev/null +++ b/internal/ceres/canonical_views_clustering.cc @@ -0,0 +1,240 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: David Gallup (dgallup@google.com) +// Sameer Agarwal (sameeragarwal@google.com) + +#include "ceres/canonical_views_clustering.h" + +#include "ceres/collections_port.h" +#include "ceres/graph.h" +#include "ceres/internal/macros.h" +#include "ceres/map_util.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +typedef HashMap IntMap; +typedef HashSet IntSet; + +class CanonicalViewsClustering { + public: + CanonicalViewsClustering() {} + + // Compute the canonical views clustering of the vertices of the + // graph. centers will contain the vertices that are the identified + // as the canonical views/cluster centers, and membership is a map + // from vertices to cluster_ids. The i^th cluster center corresponds + // to the i^th cluster. It is possible depending on the + // configuration of the clustering algorithm that some of the + // vertices may not be assigned to any cluster. In this case they + // are assigned to a cluster with id = kInvalidClusterId. + void ComputeClustering(const CanonicalViewsClusteringOptions& options, + const WeightedGraph& graph, + vector* centers, + IntMap* membership); + + private: + void FindValidViews(IntSet* valid_views) const; + double ComputeClusteringQualityDifference(const int candidate, + const vector& centers) const; + void UpdateCanonicalViewAssignments(const int canonical_view); + void ComputeClusterMembership(const vector& centers, + IntMap* membership) const; + + CanonicalViewsClusteringOptions options_; + const WeightedGraph* graph_; + // Maps a view to its representative canonical view (its cluster + // center). + IntMap view_to_canonical_view_; + // Maps a view to its similarity to its current cluster center. + HashMap view_to_canonical_view_similarity_; + CERES_DISALLOW_COPY_AND_ASSIGN(CanonicalViewsClustering); +}; + +void ComputeCanonicalViewsClustering( + const CanonicalViewsClusteringOptions& options, + const WeightedGraph& graph, + vector* centers, + IntMap* membership) { + time_t start_time = time(NULL); + CanonicalViewsClustering cv; + cv.ComputeClustering(options, graph, centers, membership); + VLOG(2) << "Canonical views clustering time (secs): " + << time(NULL) - start_time; +} + +// Implementation of CanonicalViewsClustering +void CanonicalViewsClustering::ComputeClustering( + const CanonicalViewsClusteringOptions& options, + const WeightedGraph& graph, + vector* centers, + IntMap* membership) { + options_ = options; + CHECK_NOTNULL(centers)->clear(); + CHECK_NOTNULL(membership)->clear(); + graph_ = &graph; + + IntSet valid_views; + FindValidViews(&valid_views); + while (valid_views.size() > 0) { + // Find the next best canonical view. + double best_difference = -std::numeric_limits::max(); + int best_view = 0; + + // TODO(sameeragarwal): Make this loop multi-threaded. + for (IntSet::const_iterator view = valid_views.begin(); + view != valid_views.end(); + ++view) { + const double difference = + ComputeClusteringQualityDifference(*view, *centers); + if (difference > best_difference) { + best_difference = difference; + best_view = *view; + } + } + + CHECK_GT(best_difference, -std::numeric_limits::max()); + + // Add canonical view if quality improves, or if minimum is not + // yet met, otherwise break. + if ((best_difference <= 0) && + (centers->size() >= options_.min_views)) { + break; + } + + centers->push_back(best_view); + valid_views.erase(best_view); + UpdateCanonicalViewAssignments(best_view); + } + + ComputeClusterMembership(*centers, membership); +} + +// Return the set of vertices of the graph which have valid vertex +// weights. +void CanonicalViewsClustering::FindValidViews( + IntSet* valid_views) const { + const IntSet& views = graph_->vertices(); + for (IntSet::const_iterator view = views.begin(); + view != views.end(); + ++view) { + if (graph_->VertexWeight(*view) != WeightedGraph::InvalidWeight()) { + valid_views->insert(*view); + } + } +} + +// Computes the difference in the quality score if 'candidate' were +// added to the set of canonical views. +double CanonicalViewsClustering::ComputeClusteringQualityDifference( + const int candidate, + const vector& centers) const { + // View score. + double difference = + options_.view_score_weight * graph_->VertexWeight(candidate); + + // Compute how much the quality score changes if the candidate view + // was added to the list of canonical views and its nearest + // neighbors became members of its cluster. + const IntSet& neighbors = graph_->Neighbors(candidate); + for (IntSet::const_iterator neighbor = neighbors.begin(); + neighbor != neighbors.end(); + ++neighbor) { + const double old_similarity = + FindWithDefault(view_to_canonical_view_similarity_, *neighbor, 0.0); + const double new_similarity = graph_->EdgeWeight(*neighbor, candidate); + if (new_similarity > old_similarity) { + difference += new_similarity - old_similarity; + } + } + + // Number of views penalty. + difference -= options_.size_penalty_weight; + + // Orthogonality. + for (int i = 0; i < centers.size(); ++i) { + difference -= options_.similarity_penalty_weight * + graph_->EdgeWeight(centers[i], candidate); + } + + return difference; +} + +// Reassign views if they're more similar to the new canonical view. +void CanonicalViewsClustering::UpdateCanonicalViewAssignments( + const int canonical_view) { + const IntSet& neighbors = graph_->Neighbors(canonical_view); + for (IntSet::const_iterator neighbor = neighbors.begin(); + neighbor != neighbors.end(); + ++neighbor) { + const double old_similarity = + FindWithDefault(view_to_canonical_view_similarity_, *neighbor, 0.0); + const double new_similarity = + graph_->EdgeWeight(*neighbor, canonical_view); + if (new_similarity > old_similarity) { + view_to_canonical_view_[*neighbor] = canonical_view; + view_to_canonical_view_similarity_[*neighbor] = new_similarity; + } + } +} + +// Assign a cluster id to each view. +void CanonicalViewsClustering::ComputeClusterMembership( + const vector& centers, + IntMap* membership) const { + CHECK_NOTNULL(membership)->clear(); + + // The i^th cluster has cluster id i. + IntMap center_to_cluster_id; + for (int i = 0; i < centers.size(); ++i) { + center_to_cluster_id[centers[i]] = i; + } + + static const int kInvalidClusterId = -1; + + const IntSet& views = graph_->vertices(); + for (IntSet::const_iterator view = views.begin(); + view != views.end(); + ++view) { + IntMap::const_iterator it = + view_to_canonical_view_.find(*view); + int cluster_id = kInvalidClusterId; + if (it != view_to_canonical_view_.end()) { + cluster_id = FindOrDie(center_to_cluster_id, it->second); + } + + InsertOrDie(membership, *view, cluster_id); + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/canonical_views_clustering.h b/internal/ceres/canonical_views_clustering.h new file mode 100644 index 0000000..0847f48 --- /dev/null +++ b/internal/ceres/canonical_views_clustering.h @@ -0,0 +1,130 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// An implementation of the Canonical Views clustering algorithm from +// "Scene Summarization for Online Image Collections", Ian Simon, Noah +// Snavely, Steven M. Seitz, ICCV 2007. +// +// More details can be found at +// http://grail.cs.washington.edu/projects/canonview/ +// +// Ceres uses this algorithm to perform view clustering for +// constructing visibility based preconditioners. + +#ifndef CERES_INTERNAL_CANONICAL_VIEWS_CLUSTERING_H_ +#define CERES_INTERNAL_CANONICAL_VIEWS_CLUSTERING_H_ + +#include + +#include "ceres/collections_port.h" +#include "ceres/graph.h" + +namespace ceres { +namespace internal { + +struct CanonicalViewsClusteringOptions; + +// Compute a partitioning of the vertices of the graph using the +// canonical views clustering algorithm. +// +// In the following we will use the terms vertices and views +// interchangably. Given a weighted Graph G(V,E), the canonical views +// of G are the the set of vertices that best "summarize" the content +// of the graph. If w_ij i s the weight connecting the vertex i to +// vertex j, and C is the set of canonical views. Then the objective +// of the canonical views algorithm is +// +// E[C] = sum_[i in V] max_[j in C] w_ij +// - size_penalty_weight * |C| +// - similarity_penalty_weight * sum_[i in C, j in C, j > i] w_ij +// +// alpha is the size penalty that penalizes large number of canonical +// views. +// +// beta is the similarity penalty that penalizes canonical views that +// are too similar to other canonical views. +// +// Thus the canonical views algorithm tries to find a canonical view +// for each vertex in the graph which best explains it, while trying +// to minimize the number of canonical views and the overlap between +// them. +// +// We further augment the above objective function by allowing for per +// vertex weights, higher weights indicating a higher preference for +// being chosen as a canonical view. Thus if w_i is the vertex weight +// for vertex i, the objective function is then +// +// E[C] = sum_[i in V] max_[j in C] w_ij +// - size_penalty_weight * |C| +// - similarity_penalty_weight * sum_[i in C, j in C, j > i] w_ij +// + view_score_weight * sum_[i in C] w_i +// +// centers will contain the vertices that are the identified +// as the canonical views/cluster centers, and membership is a map +// from vertices to cluster_ids. The i^th cluster center corresponds +// to the i^th cluster. +// +// It is possible depending on the configuration of the clustering +// algorithm that some of the vertices may not be assigned to any +// cluster. In this case they are assigned to a cluster with id = -1; +void ComputeCanonicalViewsClustering( + const CanonicalViewsClusteringOptions& options, + const WeightedGraph& graph, + std::vector* centers, + HashMap* membership); + +struct CanonicalViewsClusteringOptions { + CanonicalViewsClusteringOptions() + : min_views(3), + size_penalty_weight(5.75), + similarity_penalty_weight(100.0), + view_score_weight(0.0) { + } + // The minimum number of canonical views to compute. + int min_views; + + // Penalty weight for the number of canonical views. A higher + // number will result in fewer canonical views. + double size_penalty_weight; + + // Penalty weight for the diversity (orthogonality) of the + // canonical views. A higher number will encourage less similar + // canonical views. + double similarity_penalty_weight; + + // Weight for per-view scores. Lower weight places less + // confidence in the view scores. + double view_score_weight; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CANONICAL_VIEWS_CLUSTERING_H_ diff --git a/internal/ceres/canonical_views_clustering_test.cc b/internal/ceres/canonical_views_clustering_test.cc new file mode 100644 index 0000000..0c15fc7 --- /dev/null +++ b/internal/ceres/canonical_views_clustering_test.cc @@ -0,0 +1,143 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: Sameer Agarwal (sameeragarwal@google.com) +// David Gallup (dgallup@google.com) + +#include "ceres/canonical_views_clustering.h" + +#include "ceres/collections_port.h" +#include "ceres/graph.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +const int kVertexIds[] = {0, 1, 2, 3}; +class CanonicalViewsTest : public ::testing::Test { + protected: + virtual void SetUp() { + // The graph structure is as follows. + // + // Vertex weights: 0 2 2 0 + // V0-----V1-----V2-----V3 + // Edge weights: 0.8 0.9 0.3 + const double kVertexWeights[] = {0.0, 2.0, 2.0, -1.0}; + for (int i = 0; i < 4; ++i) { + graph_.AddVertex(i, kVertexWeights[i]); + } + // Create self edges. + // CanonicalViews requires that every view "sees" itself. + for (int i = 0; i < 4; ++i) { + graph_.AddEdge(i, i, 1.0); + } + + // Create three edges. + const double kEdgeWeights[] = {0.8, 0.9, 0.3}; + for (int i = 0; i < 3; ++i) { + // The graph interface is directed, so remember to create both + // edges. + graph_.AddEdge(kVertexIds[i], kVertexIds[i + 1], kEdgeWeights[i]); + } + } + + void ComputeClustering() { + ComputeCanonicalViewsClustering(options_, graph_, ¢ers_, &membership_); + } + + WeightedGraph graph_; + + CanonicalViewsClusteringOptions options_; + std::vector centers_; + HashMap membership_; +}; + +TEST_F(CanonicalViewsTest, ComputeCanonicalViewsTest) { + options_.min_views = 0; + options_.size_penalty_weight = 0.5; + options_.similarity_penalty_weight = 0.0; + options_.view_score_weight = 0.0; + ComputeClustering(); + + // 2 canonical views. + EXPECT_EQ(centers_.size(), 2); + EXPECT_EQ(centers_[0], kVertexIds[1]); + EXPECT_EQ(centers_[1], kVertexIds[3]); + + // Check cluster membership. + EXPECT_EQ(FindOrDie(membership_, kVertexIds[0]), 0); + EXPECT_EQ(FindOrDie(membership_, kVertexIds[1]), 0); + EXPECT_EQ(FindOrDie(membership_, kVertexIds[2]), 0); + EXPECT_EQ(FindOrDie(membership_, kVertexIds[3]), 1); +} + +// Increases size penalty so the second canonical view won't be +// chosen. +TEST_F(CanonicalViewsTest, SizePenaltyTest) { + options_.min_views = 0; + options_.size_penalty_weight = 2.0; + options_.similarity_penalty_weight = 0.0; + options_.view_score_weight = 0.0; + ComputeClustering(); + + // 1 canonical view. + EXPECT_EQ(centers_.size(), 1); + EXPECT_EQ(centers_[0], kVertexIds[1]); +} + + +// Increases view score weight so vertex 2 will be chosen. +TEST_F(CanonicalViewsTest, ViewScoreTest) { + options_.min_views = 0; + options_.size_penalty_weight = 0.5; + options_.similarity_penalty_weight = 0.0; + options_.view_score_weight = 1.0; + ComputeClustering(); + + // 2 canonical views. + EXPECT_EQ(centers_.size(), 2); + EXPECT_EQ(centers_[0], kVertexIds[1]); + EXPECT_EQ(centers_[1], kVertexIds[2]); +} + +// Increases similarity penalty so vertex 2 won't be chosen despite +// it's view score. +TEST_F(CanonicalViewsTest, SimilarityPenaltyTest) { + options_.min_views = 0; + options_.size_penalty_weight = 0.5; + options_.similarity_penalty_weight = 3.0; + options_.view_score_weight = 1.0; + ComputeClustering(); + + // 2 canonical views. + EXPECT_EQ(centers_.size(), 1); + EXPECT_EQ(centers_[0], kVertexIds[1]); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/casts.h b/internal/ceres/casts.h new file mode 100644 index 0000000..f18fdea --- /dev/null +++ b/internal/ceres/casts.h @@ -0,0 +1,108 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#ifndef CERES_INTERNAL_CASTS_H_ +#define CERES_INTERNAL_CASTS_H_ + +#include +#include // For NULL. + +namespace ceres { + +// Identity metafunction. +template +struct identity_ { + typedef T type; +}; + +// Use implicit_cast as a safe version of static_cast or const_cast +// for implicit conversions. For example: +// - Upcasting in a type hierarchy. +// - Performing arithmetic conversions (int32 to int64, int to double, etc.). +// - Adding const or volatile qualifiers. +// +// In general, implicit_cast can be used to convert this code +// To to = from; +// DoSomething(to); +// to this +// DoSomething(implicit_cast(from)); +// +// base::identity_ is used to make a non-deduced context, which +// forces all callers to explicitly specify the template argument. +template +inline To implicit_cast(typename identity_::type to) { + return to; +} + +// This version of implicit_cast is used when two template arguments +// are specified. It's obsolete and should not be used. +template +inline To implicit_cast(typename identity_::type const &f) { + return f; +} + +// When you upcast (that is, cast a pointer from type Foo to type +// SuperclassOfFoo), it's fine to use implicit_cast<>, since upcasts +// always succeed. When you downcast (that is, cast a pointer from +// type Foo to type SubclassOfFoo), static_cast<> isn't safe, because +// how do you know the pointer is really of type SubclassOfFoo? It +// could be a bare Foo, or of type DifferentSubclassOfFoo. Thus, +// when you downcast, you should use this macro. In debug mode, we +// use dynamic_cast<> to double-check the downcast is legal (we die +// if it's not). In normal mode, we do the efficient static_cast<> +// instead. Thus, it's important to test in debug mode to make sure +// the cast is legal! +// This is the only place in the code we should use dynamic_cast<>. +// In particular, you SHOULDN'T be using dynamic_cast<> in order to +// do RTTI (eg code like this: +// if (dynamic_cast(foo)) HandleASubclass1Object(foo); +// if (dynamic_cast(foo)) HandleASubclass2Object(foo); +// You should design the code some other way not to need this. + +template // use like this: down_cast(foo); +inline To down_cast(From* f) { // so we only accept pointers + // Ensures that To is a sub-type of From *. This test is here only + // for compile-time type checking, and has no overhead in an + // optimized build at run-time, as it will be optimized away + // completely. + + // TODO(csilvers): This should use COMPILE_ASSERT. + if (false) { + implicit_cast(NULL); + } + + // uses RTTI in dbg and fastbuild. asserts are disabled in opt builds. + assert(f == NULL || dynamic_cast(f) != NULL); // NOLINT + return static_cast(f); +} + +} // namespace ceres + +#endif // CERES_INTERNAL_CASTS_H_ diff --git a/internal/ceres/cgnr_linear_operator.h b/internal/ceres/cgnr_linear_operator.h new file mode 100644 index 0000000..44c07ca --- /dev/null +++ b/internal/ceres/cgnr_linear_operator.h @@ -0,0 +1,120 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#ifndef CERES_INTERNAL_CGNR_LINEAR_OPERATOR_H_ +#define CERES_INTERNAL_CGNR_LINEAR_OPERATOR_H_ + +#include +#include "ceres/linear_operator.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +class SparseMatrix; + +// A linear operator which takes a matrix A and a diagonal vector D and +// performs products of the form +// +// (A^T A + D^T D)x +// +// This is used to implement iterative general sparse linear solving with +// conjugate gradients, where A is the Jacobian and D is a regularizing +// parameter. A brief proof that D^T D is the correct regularizer: +// +// Given a regularized least squares problem: +// +// min ||Ax - b||^2 + ||Dx||^2 +// x +// +// First expand into matrix notation: +// +// (Ax - b)^T (Ax - b) + xD^TDx +// +// Then multiply out to get: +// +// = xA^TAx - 2b^T Ax + b^Tb + xD^TDx +// +// Take the derivative: +// +// 0 = 2A^TAx - 2A^T b + 2 D^TDx +// 0 = A^TAx - A^T b + D^TDx +// 0 = (A^TA + D^TD)x - A^T b +// +// Thus, the symmetric system we need to solve for CGNR is +// +// Sx = z +// +// with S = A^TA + D^TD +// and z = A^T b +// +// Note: This class is not thread safe, since it uses some temporary storage. +class CgnrLinearOperator : public LinearOperator { + public: + CgnrLinearOperator(const LinearOperator& A, const double *D) + : A_(A), D_(D), z_(new double[A.num_rows()]) { + } + virtual ~CgnrLinearOperator() {} + + virtual void RightMultiply(const double* x, double* y) const { + std::fill(z_.get(), z_.get() + A_.num_rows(), 0.0); + + // z = Ax + A_.RightMultiply(x, z_.get()); + + // y = y + Atz + A_.LeftMultiply(z_.get(), y); + + // y = y + DtDx + if (D_ != NULL) { + int n = A_.num_cols(); + VectorRef(y, n).array() += ConstVectorRef(D_, n).array().square() * + ConstVectorRef(x, n).array(); + } + } + + virtual void LeftMultiply(const double* x, double* y) const { + RightMultiply(x, y); + } + + virtual int num_rows() const { return A_.num_cols(); } + virtual int num_cols() const { return A_.num_cols(); } + + private: + const LinearOperator& A_; + const double* D_; + scoped_array z_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CGNR_LINEAR_OPERATOR_H_ diff --git a/internal/ceres/cgnr_solver.cc b/internal/ceres/cgnr_solver.cc new file mode 100644 index 0000000..61fae75 --- /dev/null +++ b/internal/ceres/cgnr_solver.cc @@ -0,0 +1,88 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/cgnr_solver.h" + +#include "ceres/block_jacobi_preconditioner.h" +#include "ceres/cgnr_linear_operator.h" +#include "ceres/conjugate_gradients_solver.h" +#include "ceres/internal/eigen.h" +#include "ceres/linear_solver.h" +#include "ceres/wall_time.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +CgnrSolver::CgnrSolver(const LinearSolver::Options& options) + : options_(options), + preconditioner_(NULL) { + if (options_.preconditioner_type != JACOBI && + options_.preconditioner_type != IDENTITY) { + LOG(FATAL) << "CGNR only supports IDENTITY and JACOBI preconditioners."; + } +} + +LinearSolver::Summary CgnrSolver::SolveImpl( + BlockSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + EventLogger event_logger("CgnrSolver::Solve"); + + // Form z = Atb. + Vector z(A->num_cols()); + z.setZero(); + A->LeftMultiply(b, z.data()); + + // Precondition if necessary. + LinearSolver::PerSolveOptions cg_per_solve_options = per_solve_options; + if (options_.preconditioner_type == JACOBI) { + if (preconditioner_.get() == NULL) { + preconditioner_.reset(new BlockJacobiPreconditioner(*A)); + } + preconditioner_->Update(*A, per_solve_options.D); + cg_per_solve_options.preconditioner = preconditioner_.get(); + } + + // Solve (AtA + DtD)x = z (= Atb). + VectorRef(x, A->num_cols()).setZero(); + CgnrLinearOperator lhs(*A, per_solve_options.D); + event_logger.AddEvent("Setup"); + + ConjugateGradientsSolver conjugate_gradient_solver(options_); + LinearSolver::Summary summary = + conjugate_gradient_solver.Solve(&lhs, z.data(), cg_per_solve_options, x); + event_logger.AddEvent("Solve"); + return summary; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/cgnr_solver.h b/internal/ceres/cgnr_solver.h new file mode 100644 index 0000000..f7a1573 --- /dev/null +++ b/internal/ceres/cgnr_solver.h @@ -0,0 +1,69 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#ifndef CERES_INTERNAL_CGNR_SOLVER_H_ +#define CERES_INTERNAL_CGNR_SOLVER_H_ + +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_solver.h" + +namespace ceres { +namespace internal { + +class Preconditioner; + +class BlockJacobiPreconditioner; + +// A conjugate gradients on the normal equations solver. This directly solves +// for the solution to +// +// (A^T A + D^T D)x = A^T b +// +// as required for solving for x in the least squares sense. Currently only +// block diagonal preconditioning is supported. +class CgnrSolver : public BlockSparseMatrixSolver { + public: + explicit CgnrSolver(const LinearSolver::Options& options); + virtual Summary SolveImpl( + BlockSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + private: + const LinearSolver::Options options_; + scoped_ptr preconditioner_; + CERES_DISALLOW_COPY_AND_ASSIGN(CgnrSolver); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CGNR_SOLVER_H_ diff --git a/internal/ceres/collections_port.h b/internal/ceres/collections_port.h new file mode 100644 index 0000000..e699a66 --- /dev/null +++ b/internal/ceres/collections_port.h @@ -0,0 +1,196 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Portable HashMap and HashSet, and a specialized overload for hashing pairs. + +#ifndef CERES_INTERNAL_COLLECTIONS_PORT_H_ +#define CERES_INTERNAL_COLLECTIONS_PORT_H_ + +#include "ceres/internal/port.h" + +#if defined(CERES_NO_UNORDERED_MAP) +# include +# include +#endif + +#if defined(CERES_TR1_UNORDERED_MAP) +# include +# include +# define CERES_HASH_NAMESPACE_START namespace std { namespace tr1 { +# define CERES_HASH_NAMESPACE_END } } +#endif + +#if defined(CERES_STD_UNORDERED_MAP) +# include +# include +# define CERES_HASH_NAMESPACE_START namespace std { +# define CERES_HASH_NAMESPACE_END } +#endif + +#if defined(CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE) +# include +# include +# define CERES_HASH_NAMESPACE_START namespace std { namespace tr1 { +# define CERES_HASH_NAMESPACE_END } } +#endif + +#if !defined(CERES_NO_UNORDERED_MAP) && !defined(CERES_TR1_UNORDERED_MAP) && \ + !defined(CERES_STD_UNORDERED_MAP) && !defined(CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE) // NOLINT +# error One of: CERES_NO_UNORDERED_MAP, CERES_TR1_UNORDERED_MAP,\ + CERES_STD_UNORDERED_MAP, CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE must be defined! // NOLINT +#endif + +#include +#include "ceres/integral_types.h" + +// Some systems don't have access to unordered_map/unordered_set. In +// that case, substitute the hash map/set with normal map/set. The +// price to pay is slower speed for some operations. +#if defined(CERES_NO_UNORDERED_MAP) + +namespace ceres { +namespace internal { + +template +struct HashMap : map {}; + +template +struct HashSet : set {}; + +} // namespace internal +} // namespace ceres + +#else + +namespace ceres { +namespace internal { + +#if defined(CERES_TR1_UNORDERED_MAP) || \ + defined(CERES_STD_UNORDERED_MAP_IN_TR1_NAMESPACE) +template +struct HashMap : std::tr1::unordered_map {}; +template +struct HashSet : std::tr1::unordered_set {}; +#endif + +#if defined(CERES_STD_UNORDERED_MAP) +template +struct HashMap : std::unordered_map {}; +template +struct HashSet : std::unordered_set {}; +#endif + +#if defined(_WIN32) && !defined(__MINGW64__) && !defined(__MINGW32__) +#define GG_LONGLONG(x) x##I64 +#define GG_ULONGLONG(x) x##UI64 +#else +#define GG_LONGLONG(x) x##LL +#define GG_ULONGLONG(x) x##ULL +#endif + +// The hash function is due to Bob Jenkins (see +// http://burtleburtle.net/bob/hash/index.html). Each mix takes 36 instructions, +// in 18 cycles if you're lucky. On x86 architectures, this requires 45 +// instructions in 27 cycles, if you're lucky. +// +// 32bit version +inline void hash_mix(uint32& a, uint32& b, uint32& c) { + a -= b; a -= c; a ^= (c>>13); + b -= c; b -= a; b ^= (a<<8); + c -= a; c -= b; c ^= (b>>13); + a -= b; a -= c; a ^= (c>>12); + b -= c; b -= a; b ^= (a<<16); + c -= a; c -= b; c ^= (b>>5); + a -= b; a -= c; a ^= (c>>3); + b -= c; b -= a; b ^= (a<<10); + c -= a; c -= b; c ^= (b>>15); +} + +// 64bit version +inline void hash_mix(uint64& a, uint64& b, uint64& c) { + a -= b; a -= c; a ^= (c>>43); + b -= c; b -= a; b ^= (a<<9); + c -= a; c -= b; c ^= (b>>8); + a -= b; a -= c; a ^= (c>>38); + b -= c; b -= a; b ^= (a<<23); + c -= a; c -= b; c ^= (b>>5); + a -= b; a -= c; a ^= (c>>35); + b -= c; b -= a; b ^= (a<<49); + c -= a; c -= b; c ^= (b>>11); +} + +inline uint32 Hash32NumWithSeed(uint32 num, uint32 c) { + // The golden ratio; an arbitrary value. + uint32 b = 0x9e3779b9UL; + hash_mix(num, b, c); + return c; +} + +inline uint64 Hash64NumWithSeed(uint64 num, uint64 c) { + // More of the golden ratio. + uint64 b = GG_ULONGLONG(0xe08c1d668b756f82); + hash_mix(num, b, c); + return c; +} + +} // namespace internal +} // namespace ceres + +// Since on some platforms this is a doubly-nested namespace (std::tr1) and +// others it is not, the entire namespace line must be in a macro. +CERES_HASH_NAMESPACE_START + +// The outrageously annoying specializations below are for portability reasons. +// In short, it's not possible to have two overloads of hash + +// Hasher for STL pairs. Requires hashers for both members to be defined. +template +struct hash > { + size_t operator()(const pair& p) const { + size_t h1 = hash()(p.first); + size_t h2 = hash()(p.second); + // The decision below is at compile time + return (sizeof(h1) <= sizeof(ceres::internal::uint32)) ? + ceres::internal::Hash32NumWithSeed(h1, h2) : + ceres::internal::Hash64NumWithSeed(h1, h2); + } + // Less than operator for MSVC. + bool operator()(const pair& a, + const pair& b) const { + return a < b; + } + static const size_t bucket_size = 4; // These are required by MSVC + static const size_t min_buckets = 8; // 4 and 8 are defaults. +}; + +CERES_HASH_NAMESPACE_END + +#endif // CERES_NO_UNORDERED_MAP +#endif // CERES_INTERNAL_COLLECTIONS_PORT_H_ diff --git a/internal/ceres/compressed_col_sparse_matrix_utils.cc b/internal/ceres/compressed_col_sparse_matrix_utils.cc new file mode 100644 index 0000000..ebb2a62 --- /dev/null +++ b/internal/ceres/compressed_col_sparse_matrix_utils.cc @@ -0,0 +1,122 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/compressed_col_sparse_matrix_utils.h" + +#include +#include +#include "ceres/internal/port.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +void CompressedColumnScalarMatrixToBlockMatrix( + const int* scalar_rows, + const int* scalar_cols, + const vector& row_blocks, + const vector& col_blocks, + vector* block_rows, + vector* block_cols) { + CHECK_NOTNULL(block_rows)->clear(); + CHECK_NOTNULL(block_cols)->clear(); + const int num_row_blocks = row_blocks.size(); + const int num_col_blocks = col_blocks.size(); + + vector row_block_starts(num_row_blocks); + for (int i = 0, cursor = 0; i < num_row_blocks; ++i) { + row_block_starts[i] = cursor; + cursor += row_blocks[i]; + } + + // This loop extracts the block sparsity of the scalar sparse matrix + // It does so by iterating over the columns, but only considering + // the columns corresponding to the first element of each column + // block. Within each column, the inner loop iterates over the rows, + // and detects the presence of a row block by checking for the + // presence of a non-zero entry corresponding to its first element. + block_cols->push_back(0); + int c = 0; + for (int col_block = 0; col_block < num_col_blocks; ++col_block) { + int column_size = 0; + for (int idx = scalar_cols[c]; idx < scalar_cols[c + 1]; ++idx) { + vector::const_iterator it = + std::lower_bound(row_block_starts.begin(), + row_block_starts.end(), + scalar_rows[idx]); + // Since we are using lower_bound, it will return the row id + // where the row block starts. For everything but the first row + // of the block, where these values will be the same, we can + // skip, as we only need the first row to detect the presence of + // the block. + // + // For rows all but the first row in the last row block, + // lower_bound will return row_block_starts.end(), but those can + // be skipped like the rows in other row blocks too. + if (it == row_block_starts.end() || *it != scalar_rows[idx]) { + continue; + } + + block_rows->push_back(it - row_block_starts.begin()); + ++column_size; + } + block_cols->push_back(block_cols->back() + column_size); + c += col_blocks[col_block]; + } +} + +void BlockOrderingToScalarOrdering(const vector& blocks, + const vector& block_ordering, + vector* scalar_ordering) { + CHECK_EQ(blocks.size(), block_ordering.size()); + const int num_blocks = blocks.size(); + + // block_starts = [0, block1, block1 + block2 ..] + vector block_starts(num_blocks); + for (int i = 0, cursor = 0; i < num_blocks ; ++i) { + block_starts[i] = cursor; + cursor += blocks[i]; + } + + scalar_ordering->resize(block_starts.back() + blocks.back()); + int cursor = 0; + for (int i = 0; i < num_blocks; ++i) { + const int block_id = block_ordering[i]; + const int block_size = blocks[block_id]; + int block_position = block_starts[block_id]; + for (int j = 0; j < block_size; ++j) { + (*scalar_ordering)[cursor++] = block_position++; + } + } +} +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/compressed_col_sparse_matrix_utils.h b/internal/ceres/compressed_col_sparse_matrix_utils.h new file mode 100644 index 0000000..da2109f --- /dev/null +++ b/internal/ceres/compressed_col_sparse_matrix_utils.h @@ -0,0 +1,144 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_COMPRESSED_COL_SPARSE_MATRIX_UTILS_H_ +#define CERES_INTERNAL_COMPRESSED_COL_SPARSE_MATRIX_UTILS_H_ + +#include +#include "ceres/internal/port.h" + +namespace ceres { +namespace internal { + +// Extract the block sparsity pattern of the scalar compressed columns +// matrix and return it in compressed column form. The compressed +// column form is stored in two vectors block_rows, and block_cols, +// which correspond to the row and column arrays in a compressed +// column sparse matrix. +// +// If c_ij is the block in the matrix A corresponding to row block i +// and column block j, then it is expected that A contains at least +// one non-zero entry corresponding to the top left entry of c_ij, +// as that entry is used to detect the presence of a non-zero c_ij. +void CompressedColumnScalarMatrixToBlockMatrix( + const int* scalar_rows, + const int* scalar_cols, + const std::vector& row_blocks, + const std::vector& col_blocks, + std::vector* block_rows, + std::vector* block_cols); + +// Given a set of blocks and a permutation of these blocks, compute +// the corresponding "scalar" ordering, where the scalar ordering of +// size sum(blocks). +void BlockOrderingToScalarOrdering( + const std::vector& blocks, + const std::vector& block_ordering, + std::vector* scalar_ordering); + +// Solve the linear system +// +// R * solution = rhs +// +// Where R is an upper triangular compressed column sparse matrix. +template +void SolveUpperTriangularInPlace(IntegerType num_cols, + const IntegerType* rows, + const IntegerType* cols, + const double* values, + double* rhs_and_solution) { + for (IntegerType c = num_cols - 1; c >= 0; --c) { + rhs_and_solution[c] /= values[cols[c + 1] - 1]; + for (IntegerType idx = cols[c]; idx < cols[c + 1] - 1; ++idx) { + const IntegerType r = rows[idx]; + const double v = values[idx]; + rhs_and_solution[r] -= v * rhs_and_solution[c]; + } + } +} + +// Solve the linear system +// +// R' * solution = rhs +// +// Where R is an upper triangular compressed column sparse matrix. +template +void SolveUpperTriangularTransposeInPlace(IntegerType num_cols, + const IntegerType* rows, + const IntegerType* cols, + const double* values, + double* rhs_and_solution) { + for (IntegerType c = 0; c < num_cols; ++c) { + for (IntegerType idx = cols[c]; idx < cols[c + 1] - 1; ++idx) { + const IntegerType r = rows[idx]; + const double v = values[idx]; + rhs_and_solution[c] -= v * rhs_and_solution[r]; + } + rhs_and_solution[c] = rhs_and_solution[c] / values[cols[c + 1] - 1]; + } +} + +// Given a upper triangular matrix R in compressed column form, solve +// the linear system, +// +// R'R x = b +// +// Where b is all zeros except for rhs_nonzero_index, where it is +// equal to one. +// +// The function exploits this knowledge to reduce the number of +// floating point operations. +template +void SolveRTRWithSparseRHS(IntegerType num_cols, + const IntegerType* rows, + const IntegerType* cols, + const double* values, + const int rhs_nonzero_index, + double* solution) { + std::fill(solution, solution + num_cols, 0.0); + solution[rhs_nonzero_index] = 1.0 / values[cols[rhs_nonzero_index + 1] - 1]; + + for (IntegerType c = rhs_nonzero_index + 1; c < num_cols; ++c) { + for (IntegerType idx = cols[c]; idx < cols[c + 1] - 1; ++idx) { + const IntegerType r = rows[idx]; + if (r < rhs_nonzero_index) continue; + const double v = values[idx]; + solution[c] -= v * solution[r]; + } + solution[c] = solution[c] / values[cols[c + 1] - 1]; + } + + SolveUpperTriangularInPlace(num_cols, rows, cols, values, solution); +} + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_COMPRESSED_COL_SPARSE_MATRIX_UTILS_H_ diff --git a/internal/ceres/compressed_col_sparse_matrix_utils_test.cc b/internal/ceres/compressed_col_sparse_matrix_utils_test.cc new file mode 100644 index 0000000..47a98c2 --- /dev/null +++ b/internal/ceres/compressed_col_sparse_matrix_utils_test.cc @@ -0,0 +1,255 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + + +#include +#include +#include "ceres/compressed_col_sparse_matrix_utils.h" +#include "ceres/internal/port.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" +#include "gtest/gtest.h" +#include "Eigen/SparseCore" + +namespace ceres { +namespace internal { + +using std::vector; + +TEST(_, BlockPermutationToScalarPermutation) { + vector blocks; + // Block structure + // 0 --1- ---2--- ---3--- 4 + // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + blocks.push_back(1); + blocks.push_back(2); + blocks.push_back(3); + blocks.push_back(3); + blocks.push_back(1); + + // Block ordering + // [1, 0, 2, 4, 5] + vector block_ordering; + block_ordering.push_back(1); + block_ordering.push_back(0); + block_ordering.push_back(2); + block_ordering.push_back(4); + block_ordering.push_back(3); + + // Expected ordering + // [1, 2, 0, 3, 4, 5, 9, 6, 7, 8] + vector expected_scalar_ordering; + expected_scalar_ordering.push_back(1); + expected_scalar_ordering.push_back(2); + expected_scalar_ordering.push_back(0); + expected_scalar_ordering.push_back(3); + expected_scalar_ordering.push_back(4); + expected_scalar_ordering.push_back(5); + expected_scalar_ordering.push_back(9); + expected_scalar_ordering.push_back(6); + expected_scalar_ordering.push_back(7); + expected_scalar_ordering.push_back(8); + + vector scalar_ordering; + BlockOrderingToScalarOrdering(blocks, + block_ordering, + &scalar_ordering); + EXPECT_EQ(scalar_ordering.size(), expected_scalar_ordering.size()); + for (int i = 0; i < expected_scalar_ordering.size(); ++i) { + EXPECT_EQ(scalar_ordering[i], expected_scalar_ordering[i]); + } +} + +void FillBlock(const vector& row_blocks, + const vector& col_blocks, + const int row_block_id, + const int col_block_id, + vector >* triplets) { + const int row_offset = std::accumulate(&row_blocks[0], &row_blocks[row_block_id], 0); + const int col_offset = std::accumulate(&col_blocks[0], &col_blocks[col_block_id], 0); + for (int r = 0; r < row_blocks[row_block_id]; ++r) { + for (int c = 0; c < col_blocks[col_block_id]; ++c) { + triplets->push_back(Eigen::Triplet(row_offset + r, col_offset + c, 1.0)); + } + } +} + +TEST(_, ScalarMatrixToBlockMatrix) { + // Block sparsity. + // + // [1 2 3 2] + // [1] x x + // [2] x x + // [2] x x + // num_nonzeros = 1 + 3 + 4 + 4 + 1 + 2 = 15 + + + vector col_blocks; + col_blocks.push_back(1); + col_blocks.push_back(2); + col_blocks.push_back(3); + col_blocks.push_back(2); + + vector row_blocks; + row_blocks.push_back(1); + row_blocks.push_back(2); + row_blocks.push_back(2); + + const int num_rows = std::accumulate(row_blocks.begin(), row_blocks.end(), 0.0); + const int num_cols = std::accumulate(col_blocks.begin(), col_blocks.end(), 0.0); + + vector > triplets; + FillBlock(row_blocks, col_blocks, 0, 0, &triplets); + FillBlock(row_blocks, col_blocks, 2, 0, &triplets); + FillBlock(row_blocks, col_blocks, 1, 1, &triplets); + FillBlock(row_blocks, col_blocks, 2, 1, &triplets); + FillBlock(row_blocks, col_blocks, 0, 2, &triplets); + FillBlock(row_blocks, col_blocks, 1, 3, &triplets); + Eigen::SparseMatrix sparse_matrix(num_rows, num_cols); + sparse_matrix.setFromTriplets(triplets.begin(), triplets.end()); + + vector expected_compressed_block_rows; + expected_compressed_block_rows.push_back(0); + expected_compressed_block_rows.push_back(2); + expected_compressed_block_rows.push_back(1); + expected_compressed_block_rows.push_back(2); + expected_compressed_block_rows.push_back(0); + expected_compressed_block_rows.push_back(1); + + vector expected_compressed_block_cols; + expected_compressed_block_cols.push_back(0); + expected_compressed_block_cols.push_back(2); + expected_compressed_block_cols.push_back(4); + expected_compressed_block_cols.push_back(5); + expected_compressed_block_cols.push_back(6); + + vector compressed_block_rows; + vector compressed_block_cols; + CompressedColumnScalarMatrixToBlockMatrix( + sparse_matrix.innerIndexPtr(), + sparse_matrix.outerIndexPtr(), + row_blocks, + col_blocks, + &compressed_block_rows, + &compressed_block_cols); + + EXPECT_EQ(compressed_block_rows, expected_compressed_block_rows); + EXPECT_EQ(compressed_block_cols, expected_compressed_block_cols); +} + +class SolveUpperTriangularTest : public ::testing::Test { + protected: + void SetUp() { + cols.resize(5); + rows.resize(7); + values.resize(7); + + cols[0] = 0; + rows[0] = 0; + values[0] = 0.50754; + + cols[1] = 1; + rows[1] = 1; + values[1] = 0.80483; + + cols[2] = 2; + rows[2] = 1; + values[2] = 0.14120; + rows[3] = 2; + values[3] = 0.3; + + cols[3] = 4; + rows[4] = 0; + values[4] = 0.77696; + rows[5] = 1; + values[5] = 0.41860; + rows[6] = 3; + values[6] = 0.88979; + + cols[4] = 7; + } + + vector cols; + vector rows; + vector values; +}; + +TEST_F(SolveUpperTriangularTest, SolveInPlace) { + double rhs_and_solution[] = {1.0, 1.0, 2.0, 2.0}; + const double expected[] = { -1.4706, -1.0962, 6.6667, 2.2477}; + + SolveUpperTriangularInPlace(cols.size() - 1, + &rows[0], + &cols[0], + &values[0], + rhs_and_solution); + + for (int i = 0; i < 4; ++i) { + EXPECT_NEAR(rhs_and_solution[i], expected[i], 1e-4) << i; + } +} + +TEST_F(SolveUpperTriangularTest, TransposeSolveInPlace) { + double rhs_and_solution[] = {1.0, 1.0, 2.0, 2.0}; + double expected[] = {1.970288, 1.242498, 6.081864, -0.057255}; + + SolveUpperTriangularTransposeInPlace(cols.size() - 1, + &rows[0], + &cols[0], + &values[0], + rhs_and_solution); + + for (int i = 0; i < 4; ++i) { + EXPECT_NEAR(rhs_and_solution[i], expected[i], 1e-4) << i; + } +} + +TEST_F(SolveUpperTriangularTest, RTRSolveWithSparseRHS) { + double solution[4]; + double expected[] = { 6.8420e+00, 1.0057e+00, -1.4907e-16, -1.9335e+00, + 1.0057e+00, 2.2275e+00, -1.9493e+00, -6.5693e-01, + -1.4907e-16, -1.9493e+00, 1.1111e+01, 9.7381e-17, + -1.9335e+00, -6.5693e-01, 9.7381e-17, 1.2631e+00 }; + + for (int i = 0; i < 4; ++i) { + SolveRTRWithSparseRHS(cols.size() - 1, + &rows[0], + &cols[0], + &values[0], + i, + solution); + for (int j = 0; j < 4; ++j) { + EXPECT_NEAR(solution[j], expected[4 * i + j], 1e-3) << i; + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/compressed_row_jacobian_writer.cc b/internal/ceres/compressed_row_jacobian_writer.cc new file mode 100644 index 0000000..0444d45 --- /dev/null +++ b/internal/ceres/compressed_row_jacobian_writer.cc @@ -0,0 +1,245 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/compressed_row_jacobian_writer.h" + +#include +#include +#include + +#include "ceres/casts.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/parameter_block.h" +#include "ceres/program.h" +#include "ceres/residual_block.h" +#include "ceres/scratch_evaluate_preparer.h" + +namespace ceres { +namespace internal { + +using std::make_pair; +using std::pair; +using std::vector; +using std::adjacent_find; + +void CompressedRowJacobianWriter::PopulateJacobianRowAndColumnBlockVectors( + const Program* program, CompressedRowSparseMatrix* jacobian) { + const vector& parameter_blocks = + program->parameter_blocks(); + vector& col_blocks = *(jacobian->mutable_col_blocks()); + col_blocks.resize(parameter_blocks.size()); + for (int i = 0; i < parameter_blocks.size(); ++i) { + col_blocks[i] = parameter_blocks[i]->LocalSize(); + } + + const vector& residual_blocks = + program->residual_blocks(); + vector& row_blocks = *(jacobian->mutable_row_blocks()); + row_blocks.resize(residual_blocks.size()); + for (int i = 0; i < residual_blocks.size(); ++i) { + row_blocks[i] = residual_blocks[i]->NumResiduals(); + } +} + +void CompressedRowJacobianWriter::GetOrderedParameterBlocks( + const Program* program, + int residual_id, + vector >* evaluated_jacobian_blocks) { + const ResidualBlock* residual_block = + program->residual_blocks()[residual_id]; + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + + for (int j = 0; j < num_parameter_blocks; ++j) { + const ParameterBlock* parameter_block = + residual_block->parameter_blocks()[j]; + if (!parameter_block->IsConstant()) { + evaluated_jacobian_blocks->push_back( + make_pair(parameter_block->index(), j)); + } + } + sort(evaluated_jacobian_blocks->begin(), evaluated_jacobian_blocks->end()); +} + +SparseMatrix* CompressedRowJacobianWriter::CreateJacobian() const { + const vector& residual_blocks = + program_->residual_blocks(); + + int total_num_residuals = program_->NumResiduals(); + int total_num_effective_parameters = program_->NumEffectiveParameters(); + + // Count the number of jacobian nonzeros. + int num_jacobian_nonzeros = 0; + for (int i = 0; i < residual_blocks.size(); ++i) { + ResidualBlock* residual_block = residual_blocks[i]; + const int num_residuals = residual_block->NumResiduals(); + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + if (!parameter_block->IsConstant()) { + num_jacobian_nonzeros += num_residuals * parameter_block->LocalSize(); + } + } + } + + // Allocate storage for the jacobian with some extra space at the end. + // Allocate more space than needed to store the jacobian so that when the LM + // algorithm adds the diagonal, no reallocation is necessary. This reduces + // peak memory usage significantly. + CompressedRowSparseMatrix* jacobian = + new CompressedRowSparseMatrix( + total_num_residuals, + total_num_effective_parameters, + num_jacobian_nonzeros + total_num_effective_parameters); + + // At this stage, the CompressedRowSparseMatrix is an invalid state. But this + // seems to be the only way to construct it without doing a memory copy. + int* rows = jacobian->mutable_rows(); + int* cols = jacobian->mutable_cols(); + + int row_pos = 0; + rows[0] = 0; + for (int i = 0; i < residual_blocks.size(); ++i) { + const ResidualBlock* residual_block = residual_blocks[i]; + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + + // Count the number of derivatives for a row of this residual block and + // build a list of active parameter block indices. + int num_derivatives = 0; + vector parameter_indices; + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + if (!parameter_block->IsConstant()) { + parameter_indices.push_back(parameter_block->index()); + num_derivatives += parameter_block->LocalSize(); + } + } + + // Sort the parameters by their position in the state vector. + sort(parameter_indices.begin(), parameter_indices.end()); + if (adjacent_find(parameter_indices.begin(), parameter_indices.end()) != + parameter_indices.end()) { + std::string parameter_block_description; + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + parameter_block_description += + parameter_block->ToString() + "\n"; + } + LOG(FATAL) << "Ceres internal error: " + << "Duplicate parameter blocks detected in a cost function. " + << "This should never happen. Please report this to " + << "the Ceres developers.\n" + << "Residual Block: " << residual_block->ToString() << "\n" + << "Parameter Blocks: " << parameter_block_description; + } + + // Update the row indices. + const int num_residuals = residual_block->NumResiduals(); + for (int j = 0; j < num_residuals; ++j) { + rows[row_pos + j + 1] = rows[row_pos + j] + num_derivatives; + } + + // Iterate over parameter blocks in the order which they occur in the + // parameter vector. This code mirrors that in Write(), where jacobian + // values are updated. + int col_pos = 0; + for (int j = 0; j < parameter_indices.size(); ++j) { + ParameterBlock* parameter_block = + program_->parameter_blocks()[parameter_indices[j]]; + const int parameter_block_size = parameter_block->LocalSize(); + + for (int r = 0; r < num_residuals; ++r) { + // This is the position in the values array of the jacobian where this + // row of the jacobian block should go. + const int column_block_begin = rows[row_pos + r] + col_pos; + + for (int c = 0; c < parameter_block_size; ++c) { + cols[column_block_begin + c] = parameter_block->delta_offset() + c; + } + } + col_pos += parameter_block_size; + } + row_pos += num_residuals; + } + CHECK_EQ(num_jacobian_nonzeros, rows[total_num_residuals]); + + PopulateJacobianRowAndColumnBlockVectors(program_, jacobian); + + return jacobian; +} + +void CompressedRowJacobianWriter::Write(int residual_id, + int residual_offset, + double **jacobians, + SparseMatrix* base_jacobian) { + CompressedRowSparseMatrix* jacobian = + down_cast(base_jacobian); + + double* jacobian_values = jacobian->mutable_values(); + const int* jacobian_rows = jacobian->rows(); + + const ResidualBlock* residual_block = + program_->residual_blocks()[residual_id]; + const int num_residuals = residual_block->NumResiduals(); + + vector > evaluated_jacobian_blocks; + GetOrderedParameterBlocks(program_, residual_id, &evaluated_jacobian_blocks); + + // Where in the current row does the jacobian for a parameter block begin. + int col_pos = 0; + + // Iterate over the jacobian blocks in increasing order of their + // positions in the reduced parameter vector. + for (int i = 0; i < evaluated_jacobian_blocks.size(); ++i) { + const ParameterBlock* parameter_block = + program_->parameter_blocks()[evaluated_jacobian_blocks[i].first]; + const int argument = evaluated_jacobian_blocks[i].second; + const int parameter_block_size = parameter_block->LocalSize(); + + // Copy one row of the jacobian block at a time. + for (int r = 0; r < num_residuals; ++r) { + // Position of the r^th row of the current jacobian block. + const double* block_row_begin = + jacobians[argument] + r * parameter_block_size; + + // Position in the values array of the jacobian where this + // row of the jacobian block should go. + double* column_block_begin = + jacobian_values + jacobian_rows[residual_offset + r] + col_pos; + + std::copy(block_row_begin, + block_row_begin + parameter_block_size, + column_block_begin); + } + col_pos += parameter_block_size; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/compressed_row_jacobian_writer.h b/internal/ceres/compressed_row_jacobian_writer.h new file mode 100644 index 0000000..1cd0123 --- /dev/null +++ b/internal/ceres/compressed_row_jacobian_writer.h @@ -0,0 +1,112 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A jacobian writer that directly writes to compressed row sparse matrices. + +#ifndef CERES_INTERNAL_COMPRESSED_ROW_JACOBIAN_WRITER_H_ +#define CERES_INTERNAL_COMPRESSED_ROW_JACOBIAN_WRITER_H_ + +#include +#include + +#include "ceres/evaluator.h" +#include "ceres/scratch_evaluate_preparer.h" + +namespace ceres { +namespace internal { + +class CompressedRowSparseMatrix; +class Program; +class SparseMatrix; + +class CompressedRowJacobianWriter { + public: + CompressedRowJacobianWriter(Evaluator::Options /* ignored */, + Program* program) + : program_(program) { + } + + // PopulateJacobianRowAndColumnBlockVectors sets col_blocks and + // row_blocks for a CompressedRowSparseMatrix, based on the + // parameter block sizes and residual sizes respectively from the + // program. This is useful when Solver::Options::use_block_amd = + // true; + // + // This function is static so that it is available to other jacobian + // writers which use CompressedRowSparseMatrix (or derived types). + // (Jacobian writers do not fall under any type hierarchy; they only + // have to provide an interface as specified in program_evaluator.h). + static void PopulateJacobianRowAndColumnBlockVectors( + const Program* program, + CompressedRowSparseMatrix* jacobian); + + // It is necessary to determine the order of the jacobian blocks + // before copying them into a CompressedRowSparseMatrix (or derived + // type). Just because a cost function uses parameter blocks 1 + // after 2 in its arguments does not mean that the block 1 occurs + // before block 2 in the column layout of the jacobian. Thus, + // GetOrderedParameterBlocks determines the order by sorting the + // jacobian blocks by their position in the state vector. + // + // This function is static so that it is available to other jacobian + // writers which use CompressedRowSparseMatrix (or derived types). + // (Jacobian writers do not fall under any type hierarchy; they only + // have to provide an interface as specified in + // program_evaluator.h). + static void GetOrderedParameterBlocks( + const Program* program, + int residual_id, + std::vector >* evaluated_jacobian_blocks); + + // JacobianWriter interface. + + // Since the compressed row matrix has different layout than that + // assumed by the cost functions, use scratch space to store the + // jacobians temporarily then copy them over to the larger jacobian + // in the Write() function. + ScratchEvaluatePreparer* CreateEvaluatePreparers(int num_threads) { + return ScratchEvaluatePreparer::Create(*program_, num_threads); + } + + SparseMatrix* CreateJacobian() const; + + void Write(int residual_id, + int residual_offset, + double **jacobians, + SparseMatrix* base_jacobian); + + private: + Program* program_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_COMPRESSED_ROW_JACOBIAN_WRITER_H_ diff --git a/internal/ceres/compressed_row_sparse_matrix.cc b/internal/ceres/compressed_row_sparse_matrix.cc new file mode 100644 index 0000000..ee59eae --- /dev/null +++ b/internal/ceres/compressed_row_sparse_matrix.cc @@ -0,0 +1,567 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/compressed_row_sparse_matrix.h" + +#include +#include +#include +#include "ceres/crs_matrix.h" +#include "ceres/internal/port.h" +#include "ceres/random.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +namespace { + +// Helper functor used by the constructor for reordering the contents +// of a TripletSparseMatrix. This comparator assumes thay there are no +// duplicates in the pair of arrays rows and cols, i.e., there is no +// indices i and j (not equal to each other) s.t. +// +// rows[i] == rows[j] && cols[i] == cols[j] +// +// If this is the case, this functor will not be a StrictWeakOrdering. +struct RowColLessThan { + RowColLessThan(const int* rows, const int* cols) : rows(rows), cols(cols) {} + + bool operator()(const int x, const int y) const { + if (rows[x] == rows[y]) { + return (cols[x] < cols[y]); + } + return (rows[x] < rows[y]); + } + + const int* rows; + const int* cols; +}; + +void TransposeForCompressedRowSparseStructure(const int num_rows, + const int num_cols, + const int num_nonzeros, + const int* rows, + const int* cols, + const double* values, + int* transpose_rows, + int* transpose_cols, + double* transpose_values) { + // Explicitly zero out transpose_rows. + std::fill(transpose_rows, transpose_rows + num_cols + 1, 0); + + // Count the number of entries in each column of the original matrix + // and assign to transpose_rows[col + 1]. + for (int idx = 0; idx < num_nonzeros; ++idx) { + ++transpose_rows[cols[idx] + 1]; + } + + // Compute the starting position for each row in the transpose by + // computing the cumulative sum of the entries of transpose_rows. + for (int i = 1; i < num_cols + 1; ++i) { + transpose_rows[i] += transpose_rows[i - 1]; + } + + // Populate transpose_cols and (optionally) transpose_values by + // walking the entries of the source matrices. For each entry that + // is added, the value of transpose_row is incremented allowing us + // to keep track of where the next entry for that row should go. + // + // As a result transpose_row is shifted to the left by one entry. + for (int r = 0; r < num_rows; ++r) { + for (int idx = rows[r]; idx < rows[r + 1]; ++idx) { + const int c = cols[idx]; + const int transpose_idx = transpose_rows[c]++; + transpose_cols[transpose_idx] = r; + if (values != NULL && transpose_values != NULL) { + transpose_values[transpose_idx] = values[idx]; + } + } + } + + // This loop undoes the left shift to transpose_rows introduced by + // the previous loop. + for (int i = num_cols - 1; i > 0; --i) { + transpose_rows[i] = transpose_rows[i - 1]; + } + transpose_rows[0] = 0; +} + +void AddRandomBlock(const int num_rows, + const int num_cols, + const int row_block_begin, + const int col_block_begin, + std::vector* rows, + std::vector* cols, + std::vector* values) { + for (int r = 0; r < num_rows; ++r) { + for (int c = 0; c < num_cols; ++c) { + rows->push_back(row_block_begin + r); + cols->push_back(col_block_begin + c); + values->push_back(RandNormal()); + } + } +} + +} // namespace + +// This constructor gives you a semi-initialized CompressedRowSparseMatrix. +CompressedRowSparseMatrix::CompressedRowSparseMatrix(int num_rows, + int num_cols, + int max_num_nonzeros) { + num_rows_ = num_rows; + num_cols_ = num_cols; + storage_type_ = UNSYMMETRIC; + rows_.resize(num_rows + 1, 0); + cols_.resize(max_num_nonzeros, 0); + values_.resize(max_num_nonzeros, 0.0); + + VLOG(1) << "# of rows: " << num_rows_ << " # of columns: " << num_cols_ + << " max_num_nonzeros: " << cols_.size() << ". Allocating " + << (num_rows_ + 1) * sizeof(int) + // NOLINT + cols_.size() * sizeof(int) + // NOLINT + cols_.size() * sizeof(double); // NOLINT +} + +CompressedRowSparseMatrix* CompressedRowSparseMatrix::FromTripletSparseMatrix( + const TripletSparseMatrix& input) { + return CompressedRowSparseMatrix::FromTripletSparseMatrix(input, false); +} + +CompressedRowSparseMatrix* +CompressedRowSparseMatrix::FromTripletSparseMatrixTransposed( + const TripletSparseMatrix& input) { + return CompressedRowSparseMatrix::FromTripletSparseMatrix(input, true); +} + +CompressedRowSparseMatrix* CompressedRowSparseMatrix::FromTripletSparseMatrix( + const TripletSparseMatrix& input, bool transpose) { + int num_rows = input.num_rows(); + int num_cols = input.num_cols(); + const int* rows = input.rows(); + const int* cols = input.cols(); + const double* values = input.values(); + + if (transpose) { + std::swap(num_rows, num_cols); + std::swap(rows, cols); + } + + // index is the list of indices into the TripletSparseMatrix input. + vector index(input.num_nonzeros(), 0); + for (int i = 0; i < input.num_nonzeros(); ++i) { + index[i] = i; + } + + // Sort index such that the entries of m are ordered by row and ties + // are broken by column. + std::sort(index.begin(), index.end(), RowColLessThan(rows, cols)); + + VLOG(1) << "# of rows: " << num_rows << " # of columns: " << num_cols + << " num_nonzeros: " << input.num_nonzeros() << ". Allocating " + << ((num_rows + 1) * sizeof(int) + // NOLINT + input.num_nonzeros() * sizeof(int) + // NOLINT + input.num_nonzeros() * sizeof(double)); // NOLINT + + CompressedRowSparseMatrix* output = + new CompressedRowSparseMatrix(num_rows, num_cols, input.num_nonzeros()); + + // Copy the contents of the cols and values array in the order given + // by index and count the number of entries in each row. + int* output_rows = output->mutable_rows(); + int* output_cols = output->mutable_cols(); + double* output_values = output->mutable_values(); + + output_rows[0] = 0; + for (int i = 0; i < index.size(); ++i) { + const int idx = index[i]; + ++output_rows[rows[idx] + 1]; + output_cols[i] = cols[idx]; + output_values[i] = values[idx]; + } + + // Find the cumulative sum of the row counts. + for (int i = 1; i < num_rows + 1; ++i) { + output_rows[i] += output_rows[i - 1]; + } + + CHECK_EQ(output->num_nonzeros(), input.num_nonzeros()); + return output; +} + +CompressedRowSparseMatrix::CompressedRowSparseMatrix(const double* diagonal, + int num_rows) { + CHECK_NOTNULL(diagonal); + + num_rows_ = num_rows; + num_cols_ = num_rows; + storage_type_ = UNSYMMETRIC; + rows_.resize(num_rows + 1); + cols_.resize(num_rows); + values_.resize(num_rows); + + rows_[0] = 0; + for (int i = 0; i < num_rows_; ++i) { + cols_[i] = i; + values_[i] = diagonal[i]; + rows_[i + 1] = i + 1; + } + + CHECK_EQ(num_nonzeros(), num_rows); +} + +CompressedRowSparseMatrix::~CompressedRowSparseMatrix() {} + +void CompressedRowSparseMatrix::SetZero() { + std::fill(values_.begin(), values_.end(), 0); +} + +void CompressedRowSparseMatrix::RightMultiply(const double* x, + double* y) const { + CHECK_NOTNULL(x); + CHECK_NOTNULL(y); + + for (int r = 0; r < num_rows_; ++r) { + for (int idx = rows_[r]; idx < rows_[r + 1]; ++idx) { + y[r] += values_[idx] * x[cols_[idx]]; + } + } +} + +void CompressedRowSparseMatrix::LeftMultiply(const double* x, double* y) const { + CHECK_NOTNULL(x); + CHECK_NOTNULL(y); + + for (int r = 0; r < num_rows_; ++r) { + for (int idx = rows_[r]; idx < rows_[r + 1]; ++idx) { + y[cols_[idx]] += values_[idx] * x[r]; + } + } +} + +void CompressedRowSparseMatrix::SquaredColumnNorm(double* x) const { + CHECK_NOTNULL(x); + + std::fill(x, x + num_cols_, 0.0); + for (int idx = 0; idx < rows_[num_rows_]; ++idx) { + x[cols_[idx]] += values_[idx] * values_[idx]; + } +} + +void CompressedRowSparseMatrix::ScaleColumns(const double* scale) { + CHECK_NOTNULL(scale); + + for (int idx = 0; idx < rows_[num_rows_]; ++idx) { + values_[idx] *= scale[cols_[idx]]; + } +} + +void CompressedRowSparseMatrix::ToDenseMatrix(Matrix* dense_matrix) const { + CHECK_NOTNULL(dense_matrix); + dense_matrix->resize(num_rows_, num_cols_); + dense_matrix->setZero(); + + for (int r = 0; r < num_rows_; ++r) { + for (int idx = rows_[r]; idx < rows_[r + 1]; ++idx) { + (*dense_matrix)(r, cols_[idx]) = values_[idx]; + } + } +} + +void CompressedRowSparseMatrix::DeleteRows(int delta_rows) { + CHECK_GE(delta_rows, 0); + CHECK_LE(delta_rows, num_rows_); + + num_rows_ -= delta_rows; + rows_.resize(num_rows_ + 1); + + // The rest of the code updates the block information. Immediately + // return in case of no block information. + if (row_blocks_.empty()) { + return; + } + + // Walk the list of row blocks until we reach the new number of rows + // and the drop the rest of the row blocks. + int num_row_blocks = 0; + int num_rows = 0; + while (num_row_blocks < row_blocks_.size() && num_rows < num_rows_) { + num_rows += row_blocks_[num_row_blocks]; + ++num_row_blocks; + } + + row_blocks_.resize(num_row_blocks); +} + +void CompressedRowSparseMatrix::AppendRows(const CompressedRowSparseMatrix& m) { + CHECK_EQ(m.num_cols(), num_cols_); + + CHECK((row_blocks_.empty() && m.row_blocks().empty()) || + (!row_blocks_.empty() && !m.row_blocks().empty())) + << "Cannot append a matrix with row blocks to one without and vice versa." + << "This matrix has : " << row_blocks_.size() << " row blocks." + << "The matrix being appended has: " << m.row_blocks().size() + << " row blocks."; + + if (m.num_rows() == 0) { + return; + } + + if (cols_.size() < num_nonzeros() + m.num_nonzeros()) { + cols_.resize(num_nonzeros() + m.num_nonzeros()); + values_.resize(num_nonzeros() + m.num_nonzeros()); + } + + // Copy the contents of m into this matrix. + DCHECK_LT(num_nonzeros(), cols_.size()); + if (m.num_nonzeros() > 0) { + std::copy(m.cols(), m.cols() + m.num_nonzeros(), &cols_[num_nonzeros()]); + std::copy( + m.values(), m.values() + m.num_nonzeros(), &values_[num_nonzeros()]); + } + + rows_.resize(num_rows_ + m.num_rows() + 1); + // new_rows = [rows_, m.row() + rows_[num_rows_]] + std::fill(rows_.begin() + num_rows_, + rows_.begin() + num_rows_ + m.num_rows() + 1, + rows_[num_rows_]); + + for (int r = 0; r < m.num_rows() + 1; ++r) { + rows_[num_rows_ + r] += m.rows()[r]; + } + + num_rows_ += m.num_rows(); + + // The rest of the code updates the block information. Immediately + // return in case of no block information. + if (row_blocks_.empty()) { + return; + } + + row_blocks_.insert( + row_blocks_.end(), m.row_blocks().begin(), m.row_blocks().end()); +} + +void CompressedRowSparseMatrix::ToTextFile(FILE* file) const { + CHECK_NOTNULL(file); + for (int r = 0; r < num_rows_; ++r) { + for (int idx = rows_[r]; idx < rows_[r + 1]; ++idx) { + fprintf(file, "% 10d % 10d %17f\n", r, cols_[idx], values_[idx]); + } + } +} + +void CompressedRowSparseMatrix::ToCRSMatrix(CRSMatrix* matrix) const { + matrix->num_rows = num_rows_; + matrix->num_cols = num_cols_; + matrix->rows = rows_; + matrix->cols = cols_; + matrix->values = values_; + + // Trim. + matrix->rows.resize(matrix->num_rows + 1); + matrix->cols.resize(matrix->rows[matrix->num_rows]); + matrix->values.resize(matrix->rows[matrix->num_rows]); +} + +void CompressedRowSparseMatrix::SetMaxNumNonZeros(int num_nonzeros) { + CHECK_GE(num_nonzeros, 0); + + cols_.resize(num_nonzeros); + values_.resize(num_nonzeros); +} + +CompressedRowSparseMatrix* CompressedRowSparseMatrix::CreateBlockDiagonalMatrix( + const double* diagonal, const vector& blocks) { + int num_rows = 0; + int num_nonzeros = 0; + for (int i = 0; i < blocks.size(); ++i) { + num_rows += blocks[i]; + num_nonzeros += blocks[i] * blocks[i]; + } + + CompressedRowSparseMatrix* matrix = + new CompressedRowSparseMatrix(num_rows, num_rows, num_nonzeros); + + int* rows = matrix->mutable_rows(); + int* cols = matrix->mutable_cols(); + double* values = matrix->mutable_values(); + std::fill(values, values + num_nonzeros, 0.0); + + int idx_cursor = 0; + int col_cursor = 0; + for (int i = 0; i < blocks.size(); ++i) { + const int block_size = blocks[i]; + for (int r = 0; r < block_size; ++r) { + *(rows++) = idx_cursor; + values[idx_cursor + r] = diagonal[col_cursor + r]; + for (int c = 0; c < block_size; ++c, ++idx_cursor) { + *(cols++) = col_cursor + c; + } + } + col_cursor += block_size; + } + *rows = idx_cursor; + + *matrix->mutable_row_blocks() = blocks; + *matrix->mutable_col_blocks() = blocks; + + CHECK_EQ(idx_cursor, num_nonzeros); + CHECK_EQ(col_cursor, num_rows); + return matrix; +} + +CompressedRowSparseMatrix* CompressedRowSparseMatrix::Transpose() const { + CompressedRowSparseMatrix* transpose = + new CompressedRowSparseMatrix(num_cols_, num_rows_, num_nonzeros()); + + switch (storage_type_) { + case UNSYMMETRIC: + transpose->set_storage_type(UNSYMMETRIC); + break; + case LOWER_TRIANGULAR: + transpose->set_storage_type(UPPER_TRIANGULAR); + break; + case UPPER_TRIANGULAR: + transpose->set_storage_type(LOWER_TRIANGULAR); + break; + default: + LOG(FATAL) << "Unknown storage type: " << storage_type_; + }; + + TransposeForCompressedRowSparseStructure(num_rows(), + num_cols(), + num_nonzeros(), + rows(), + cols(), + values(), + transpose->mutable_rows(), + transpose->mutable_cols(), + transpose->mutable_values()); + + // The rest of the code updates the block information. Immediately + // return in case of no block information. + if (row_blocks_.empty()) { + return transpose; + } + + *(transpose->mutable_row_blocks()) = col_blocks_; + *(transpose->mutable_col_blocks()) = row_blocks_; + return transpose; +} + +CompressedRowSparseMatrix* CompressedRowSparseMatrix::CreateRandomMatrix( + const CompressedRowSparseMatrix::RandomMatrixOptions& options) { + CHECK_GT(options.num_row_blocks, 0); + CHECK_GT(options.min_row_block_size, 0); + CHECK_GT(options.max_row_block_size, 0); + CHECK_LE(options.min_row_block_size, options.max_row_block_size); + CHECK_GT(options.num_col_blocks, 0); + CHECK_GT(options.min_col_block_size, 0); + CHECK_GT(options.max_col_block_size, 0); + CHECK_LE(options.min_col_block_size, options.max_col_block_size); + CHECK_GT(options.block_density, 0.0); + CHECK_LE(options.block_density, 1.0); + + vector row_blocks; + vector col_blocks; + + // Generate the row block structure. + for (int i = 0; i < options.num_row_blocks; ++i) { + // Generate a random integer in [min_row_block_size, max_row_block_size] + const int delta_block_size = + Uniform(options.max_row_block_size - options.min_row_block_size); + row_blocks.push_back(options.min_row_block_size + delta_block_size); + } + + // Generate the col block structure. + for (int i = 0; i < options.num_col_blocks; ++i) { + // Generate a random integer in [min_col_block_size, max_col_block_size] + const int delta_block_size = + Uniform(options.max_col_block_size - options.min_col_block_size); + col_blocks.push_back(options.min_col_block_size + delta_block_size); + } + + vector tsm_rows; + vector tsm_cols; + vector tsm_values; + + // For ease of construction, we are going to generate the + // CompressedRowSparseMatrix by generating it as a + // TripletSparseMatrix and then converting it to a + // CompressedRowSparseMatrix. + + // It is possible that the random matrix is empty which is likely + // not what the user wants, so do the matrix generation till we have + // at least one non-zero entry. + while (tsm_values.empty()) { + tsm_rows.clear(); + tsm_cols.clear(); + tsm_values.clear(); + + int row_block_begin = 0; + for (int r = 0; r < options.num_row_blocks; ++r) { + int col_block_begin = 0; + for (int c = 0; c < options.num_col_blocks; ++c) { + // Randomly determine if this block is present or not. + if (RandDouble() <= options.block_density) { + AddRandomBlock(row_blocks[r], + col_blocks[c], + row_block_begin, + col_block_begin, + &tsm_rows, + &tsm_cols, + &tsm_values); + } + col_block_begin += col_blocks[c]; + } + row_block_begin += row_blocks[r]; + } + } + + const int num_rows = std::accumulate(row_blocks.begin(), row_blocks.end(), 0); + const int num_cols = std::accumulate(col_blocks.begin(), col_blocks.end(), 0); + const bool kDoNotTranspose = false; + CompressedRowSparseMatrix* matrix = + CompressedRowSparseMatrix::FromTripletSparseMatrix( + TripletSparseMatrix( + num_rows, num_cols, tsm_rows, tsm_cols, tsm_values), + kDoNotTranspose); + (*matrix->mutable_row_blocks()) = row_blocks; + (*matrix->mutable_col_blocks()) = col_blocks; + matrix->set_storage_type(CompressedRowSparseMatrix::UNSYMMETRIC); + return matrix; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/compressed_row_sparse_matrix.h b/internal/ceres/compressed_row_sparse_matrix.h new file mode 100644 index 0000000..67b043e --- /dev/null +++ b/internal/ceres/compressed_row_sparse_matrix.h @@ -0,0 +1,234 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_COMPRESSED_ROW_SPARSE_MATRIX_H_ +#define CERES_INTERNAL_COMPRESSED_ROW_SPARSE_MATRIX_H_ + +#include +#include "ceres/internal/macros.h" +#include "ceres/internal/port.h" +#include "ceres/sparse_matrix.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { + +struct CRSMatrix; + +namespace internal { + +class TripletSparseMatrix; + +class CompressedRowSparseMatrix : public SparseMatrix { + public: + enum StorageType { + UNSYMMETRIC, + // Matrix is assumed to be symmetric but only the lower triangular + // part of the matrix is stored. + LOWER_TRIANGULAR, + // Matrix is assumed to be symmetric but only the upper triangular + // part of the matrix is stored. + UPPER_TRIANGULAR + }; + + // Create a matrix with the same content as the TripletSparseMatrix + // input. We assume that input does not have any repeated + // entries. + // + // The storage type of the matrix is set to UNSYMMETRIC. + // + // Caller owns the result. + static CompressedRowSparseMatrix* FromTripletSparseMatrix( + const TripletSparseMatrix& input); + + // Create a matrix with the same content as the TripletSparseMatrix + // input transposed. We assume that input does not have any repeated + // entries. + // + // The storage type of the matrix is set to UNSYMMETRIC. + // + // Caller owns the result. + static CompressedRowSparseMatrix* FromTripletSparseMatrixTransposed( + const TripletSparseMatrix& input); + + // Use this constructor only if you know what you are doing. This + // creates a "blank" matrix with the appropriate amount of memory + // allocated. However, the object itself is in an inconsistent state + // as the rows and cols matrices do not match the values of + // num_rows, num_cols and max_num_nonzeros. + // + // The use case for this constructor is that when the user knows the + // size of the matrix to begin with and wants to update the layout + // manually, instead of going via the indirect route of first + // constructing a TripletSparseMatrix, which leads to more than + // double the peak memory usage. + // + // The storage type is set to UNSYMMETRIC. + CompressedRowSparseMatrix(int num_rows, + int num_cols, + int max_num_nonzeros); + + // Build a square sparse diagonal matrix with num_rows rows and + // columns. The diagonal m(i,i) = diagonal(i); + // + // The storage type is set to UNSYMMETRIC + CompressedRowSparseMatrix(const double* diagonal, int num_rows); + + // SparseMatrix interface. + virtual ~CompressedRowSparseMatrix(); + virtual void SetZero(); + virtual void RightMultiply(const double* x, double* y) const; + virtual void LeftMultiply(const double* x, double* y) const; + virtual void SquaredColumnNorm(double* x) const; + virtual void ScaleColumns(const double* scale); + + virtual void ToDenseMatrix(Matrix* dense_matrix) const; + virtual void ToTextFile(FILE* file) const; + virtual int num_rows() const { return num_rows_; } + virtual int num_cols() const { return num_cols_; } + virtual int num_nonzeros() const { return rows_[num_rows_]; } + virtual const double* values() const { return &values_[0]; } + virtual double* mutable_values() { return &values_[0]; } + + // Delete the bottom delta_rows. + // num_rows -= delta_rows + void DeleteRows(int delta_rows); + + // Append the contents of m to the bottom of this matrix. m must + // have the same number of columns as this matrix. + void AppendRows(const CompressedRowSparseMatrix& m); + + void ToCRSMatrix(CRSMatrix* matrix) const; + + CompressedRowSparseMatrix* Transpose() const; + + // Destructive array resizing method. + void SetMaxNumNonZeros(int num_nonzeros); + + // Non-destructive array resizing method. + void set_num_rows(const int num_rows) { num_rows_ = num_rows; } + void set_num_cols(const int num_cols) { num_cols_ = num_cols; } + + // Low level access methods that expose the structure of the matrix. + const int* cols() const { return &cols_[0]; } + int* mutable_cols() { return &cols_[0]; } + + const int* rows() const { return &rows_[0]; } + int* mutable_rows() { return &rows_[0]; } + + const StorageType storage_type() const { return storage_type_; } + void set_storage_type(const StorageType storage_type) { + storage_type_ = storage_type; + } + + const std::vector& row_blocks() const { return row_blocks_; } + std::vector* mutable_row_blocks() { return &row_blocks_; } + + const std::vector& col_blocks() const { return col_blocks_; } + std::vector* mutable_col_blocks() { return &col_blocks_; } + + // Create a block diagonal CompressedRowSparseMatrix with the given + // block structure. The individual blocks are assumed to be laid out + // contiguously in the diagonal array, one block at a time. + // + // Caller owns the result. + static CompressedRowSparseMatrix* CreateBlockDiagonalMatrix( + const double* diagonal, + const std::vector& blocks); + + // Options struct to control the generation of random block sparse + // matrices in compressed row sparse format. + // + // The random matrix generation proceeds as follows. + // + // First the row and column block structure is determined by + // generating random row and column block sizes that lie within the + // given bounds. + // + // Then we walk the block structure of the resulting matrix, and with + // probability block_density detemine whether they are structurally + // zero or not. If the answer is no, then we generate entries for the + // block which are distributed normally. + struct RandomMatrixOptions { + RandomMatrixOptions() + : num_row_blocks(0), + min_row_block_size(0), + max_row_block_size(0), + num_col_blocks(0), + min_col_block_size(0), + max_col_block_size(0), + block_density(0.0) { + } + + int num_row_blocks; + int min_row_block_size; + int max_row_block_size; + int num_col_blocks; + int min_col_block_size; + int max_col_block_size; + + // 0 < block_density <= 1 is the probability of a block being + // present in the matrix. A given random matrix will not have + // precisely this density. + double block_density; + }; + + // Create a random CompressedRowSparseMatrix whose entries are + // normally distributed and whose structure is determined by + // RandomMatrixOptions. + // + // Caller owns the result. + static CompressedRowSparseMatrix* CreateRandomMatrix( + const RandomMatrixOptions& options); + + private: + static CompressedRowSparseMatrix* FromTripletSparseMatrix( + const TripletSparseMatrix& input, bool transpose); + + int num_rows_; + int num_cols_; + std::vector rows_; + std::vector cols_; + std::vector values_; + StorageType storage_type_; + + // If the matrix has an underlying block structure, then it can also + // carry with it row and column block sizes. This is auxilliary and + // optional information for use by algorithms operating on the + // matrix. The class itself does not make use of this information in + // any way. + std::vector row_blocks_; + std::vector col_blocks_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_COMPRESSED_ROW_SPARSE_MATRIX_H_ diff --git a/internal/ceres/compressed_row_sparse_matrix_test.cc b/internal/ceres/compressed_row_sparse_matrix_test.cc new file mode 100644 index 0000000..ab8f4ad --- /dev/null +++ b/internal/ceres/compressed_row_sparse_matrix_test.cc @@ -0,0 +1,414 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/compressed_row_sparse_matrix.h" + +#include +#include "ceres/casts.h" +#include "ceres/crs_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/random.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +#include "Eigen/SparseCore" + +namespace ceres { +namespace internal { + +using std::vector; + +void CompareMatrices(const SparseMatrix* a, const SparseMatrix* b) { + EXPECT_EQ(a->num_rows(), b->num_rows()); + EXPECT_EQ(a->num_cols(), b->num_cols()); + + int num_rows = a->num_rows(); + int num_cols = a->num_cols(); + + for (int i = 0; i < num_cols; ++i) { + Vector x = Vector::Zero(num_cols); + x(i) = 1.0; + + Vector y_a = Vector::Zero(num_rows); + Vector y_b = Vector::Zero(num_rows); + + a->RightMultiply(x.data(), y_a.data()); + b->RightMultiply(x.data(), y_b.data()); + + EXPECT_EQ((y_a - y_b).norm(), 0); + } +} + +class CompressedRowSparseMatrixTest : public ::testing::Test { + protected: + virtual void SetUp() { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(1)); + + CHECK_NOTNULL(problem.get()); + + tsm.reset(down_cast(problem->A.release())); + crsm.reset(CompressedRowSparseMatrix::FromTripletSparseMatrix(*tsm)); + + num_rows = tsm->num_rows(); + num_cols = tsm->num_cols(); + + vector* row_blocks = crsm->mutable_row_blocks(); + row_blocks->resize(num_rows); + std::fill(row_blocks->begin(), row_blocks->end(), 1); + + vector* col_blocks = crsm->mutable_col_blocks(); + col_blocks->resize(num_cols); + std::fill(col_blocks->begin(), col_blocks->end(), 1); + } + + int num_rows; + int num_cols; + + scoped_ptr tsm; + scoped_ptr crsm; +}; + +TEST_F(CompressedRowSparseMatrixTest, RightMultiply) { + CompareMatrices(tsm.get(), crsm.get()); +} + +TEST_F(CompressedRowSparseMatrixTest, LeftMultiply) { + for (int i = 0; i < num_rows; ++i) { + Vector a = Vector::Zero(num_rows); + a(i) = 1.0; + + Vector b1 = Vector::Zero(num_cols); + Vector b2 = Vector::Zero(num_cols); + + tsm->LeftMultiply(a.data(), b1.data()); + crsm->LeftMultiply(a.data(), b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); + } +} + +TEST_F(CompressedRowSparseMatrixTest, ColumnNorm) { + Vector b1 = Vector::Zero(num_cols); + Vector b2 = Vector::Zero(num_cols); + + tsm->SquaredColumnNorm(b1.data()); + crsm->SquaredColumnNorm(b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); +} + +TEST_F(CompressedRowSparseMatrixTest, Scale) { + Vector scale(num_cols); + for (int i = 0; i < num_cols; ++i) { + scale(i) = i + 1; + } + + tsm->ScaleColumns(scale.data()); + crsm->ScaleColumns(scale.data()); + CompareMatrices(tsm.get(), crsm.get()); +} + +TEST_F(CompressedRowSparseMatrixTest, DeleteRows) { + // Clear the row and column blocks as these are purely scalar tests. + crsm->mutable_row_blocks()->clear(); + crsm->mutable_col_blocks()->clear(); + + for (int i = 0; i < num_rows; ++i) { + tsm->Resize(num_rows - i, num_cols); + crsm->DeleteRows(crsm->num_rows() - tsm->num_rows()); + CompareMatrices(tsm.get(), crsm.get()); + } +} + +TEST_F(CompressedRowSparseMatrixTest, AppendRows) { + // Clear the row and column blocks as these are purely scalar tests. + crsm->mutable_row_blocks()->clear(); + crsm->mutable_col_blocks()->clear(); + + for (int i = 0; i < num_rows; ++i) { + TripletSparseMatrix tsm_appendage(*tsm); + tsm_appendage.Resize(i, num_cols); + + tsm->AppendRows(tsm_appendage); + scoped_ptr crsm_appendage( + CompressedRowSparseMatrix::FromTripletSparseMatrix(tsm_appendage)); + + crsm->AppendRows(*crsm_appendage); + CompareMatrices(tsm.get(), crsm.get()); + } +} + +TEST_F(CompressedRowSparseMatrixTest, AppendAndDeleteBlockDiagonalMatrix) { + int num_diagonal_rows = crsm->num_cols(); + + scoped_array diagonal(new double[num_diagonal_rows]); + for (int i = 0; i < num_diagonal_rows; ++i) { + diagonal[i] = i; + } + + vector row_and_column_blocks; + row_and_column_blocks.push_back(1); + row_and_column_blocks.push_back(2); + row_and_column_blocks.push_back(2); + + const vector pre_row_blocks = crsm->row_blocks(); + const vector pre_col_blocks = crsm->col_blocks(); + + scoped_ptr appendage( + CompressedRowSparseMatrix::CreateBlockDiagonalMatrix( + diagonal.get(), row_and_column_blocks)); + LOG(INFO) << appendage->row_blocks().size(); + + crsm->AppendRows(*appendage); + + const vector post_row_blocks = crsm->row_blocks(); + const vector post_col_blocks = crsm->col_blocks(); + + vector expected_row_blocks = pre_row_blocks; + expected_row_blocks.insert(expected_row_blocks.end(), + row_and_column_blocks.begin(), + row_and_column_blocks.end()); + + vector expected_col_blocks = pre_col_blocks; + + EXPECT_EQ(expected_row_blocks, crsm->row_blocks()); + EXPECT_EQ(expected_col_blocks, crsm->col_blocks()); + + crsm->DeleteRows(num_diagonal_rows); + EXPECT_EQ(crsm->row_blocks(), pre_row_blocks); + EXPECT_EQ(crsm->col_blocks(), pre_col_blocks); +} + +TEST_F(CompressedRowSparseMatrixTest, ToDenseMatrix) { + Matrix tsm_dense; + Matrix crsm_dense; + + tsm->ToDenseMatrix(&tsm_dense); + crsm->ToDenseMatrix(&crsm_dense); + + EXPECT_EQ((tsm_dense - crsm_dense).norm(), 0.0); +} + +TEST_F(CompressedRowSparseMatrixTest, ToCRSMatrix) { + CRSMatrix crs_matrix; + crsm->ToCRSMatrix(&crs_matrix); + EXPECT_EQ(crsm->num_rows(), crs_matrix.num_rows); + EXPECT_EQ(crsm->num_cols(), crs_matrix.num_cols); + EXPECT_EQ(crsm->num_rows() + 1, crs_matrix.rows.size()); + EXPECT_EQ(crsm->num_nonzeros(), crs_matrix.cols.size()); + EXPECT_EQ(crsm->num_nonzeros(), crs_matrix.values.size()); + + for (int i = 0; i < crsm->num_rows() + 1; ++i) { + EXPECT_EQ(crsm->rows()[i], crs_matrix.rows[i]); + } + + for (int i = 0; i < crsm->num_nonzeros(); ++i) { + EXPECT_EQ(crsm->cols()[i], crs_matrix.cols[i]); + EXPECT_EQ(crsm->values()[i], crs_matrix.values[i]); + } +} + +TEST(CompressedRowSparseMatrix, CreateBlockDiagonalMatrix) { + vector blocks; + blocks.push_back(1); + blocks.push_back(2); + blocks.push_back(2); + + Vector diagonal(5); + for (int i = 0; i < 5; ++i) { + diagonal(i) = i + 1; + } + + scoped_ptr matrix( + CompressedRowSparseMatrix::CreateBlockDiagonalMatrix(diagonal.data(), + blocks)); + + EXPECT_EQ(matrix->num_rows(), 5); + EXPECT_EQ(matrix->num_cols(), 5); + EXPECT_EQ(matrix->num_nonzeros(), 9); + EXPECT_EQ(blocks, matrix->row_blocks()); + EXPECT_EQ(blocks, matrix->col_blocks()); + + Vector x(5); + Vector y(5); + + x.setOnes(); + y.setZero(); + matrix->RightMultiply(x.data(), y.data()); + for (int i = 0; i < diagonal.size(); ++i) { + EXPECT_EQ(y[i], diagonal[i]); + } + + y.setZero(); + matrix->LeftMultiply(x.data(), y.data()); + for (int i = 0; i < diagonal.size(); ++i) { + EXPECT_EQ(y[i], diagonal[i]); + } + + Matrix dense; + matrix->ToDenseMatrix(&dense); + EXPECT_EQ((dense.diagonal() - diagonal).norm(), 0.0); +} + +TEST(CompressedRowSparseMatrix, Transpose) { + // 0 1 0 2 3 0 + // 4 6 7 0 0 8 + // 9 10 0 11 12 0 + // 13 0 14 15 9 0 + // 0 16 17 0 0 0 + + // Block structure: + // A A A A B B + // A A A A B B + // A A A A B B + // C C C C D D + // C C C C D D + // C C C C D D + + CompressedRowSparseMatrix matrix(5, 6, 30); + int* rows = matrix.mutable_rows(); + int* cols = matrix.mutable_cols(); + double* values = matrix.mutable_values(); + matrix.mutable_row_blocks()->push_back(3); + matrix.mutable_row_blocks()->push_back(3); + matrix.mutable_col_blocks()->push_back(4); + matrix.mutable_col_blocks()->push_back(2); + + rows[0] = 0; + cols[0] = 1; + cols[1] = 3; + cols[2] = 4; + + rows[1] = 3; + cols[3] = 0; + cols[4] = 1; + cols[5] = 2; + cols[6] = 5; + + rows[2] = 7; + cols[7] = 0; + cols[8] = 1; + cols[9] = 3; + cols[10] = 4; + + rows[3] = 11; + cols[11] = 0; + cols[12] = 2; + cols[13] = 3; + cols[14] = 4; + + rows[4] = 15; + cols[15] = 1; + cols[16] = 2; + rows[5] = 17; + + std::copy(values, values + 17, cols); + + scoped_ptr transpose(matrix.Transpose()); + + ASSERT_EQ(transpose->row_blocks().size(), matrix.col_blocks().size()); + for (int i = 0; i < transpose->row_blocks().size(); ++i) { + EXPECT_EQ(transpose->row_blocks()[i], matrix.col_blocks()[i]); + } + + ASSERT_EQ(transpose->col_blocks().size(), matrix.row_blocks().size()); + for (int i = 0; i < transpose->col_blocks().size(); ++i) { + EXPECT_EQ(transpose->col_blocks()[i], matrix.row_blocks()[i]); + } + + Matrix dense_matrix; + matrix.ToDenseMatrix(&dense_matrix); + + Matrix dense_transpose; + transpose->ToDenseMatrix(&dense_transpose); + EXPECT_NEAR((dense_matrix - dense_transpose.transpose()).norm(), 0.0, 1e-14); +} + +TEST(CompressedRowSparseMatrix, FromTripletSparseMatrix) { + TripletSparseMatrix::RandomMatrixOptions options; + options.num_rows = 5; + options.num_cols = 7; + options.density = 0.5; + + const int kNumTrials = 10; + for (int i = 0; i < kNumTrials; ++i) { + scoped_ptr tsm( + TripletSparseMatrix::CreateRandomMatrix(options)); + scoped_ptr crsm( + CompressedRowSparseMatrix::FromTripletSparseMatrix(*tsm)); + + Matrix expected; + tsm->ToDenseMatrix(&expected); + Matrix actual; + crsm->ToDenseMatrix(&actual); + EXPECT_NEAR((expected - actual).norm() / actual.norm(), + 0.0, + std::numeric_limits::epsilon()) + << "\nexpected: \n" + << expected << "\nactual: \n" + << actual; + } +} + +TEST(CompressedRowSparseMatrix, FromTripletSparseMatrixTransposed) { + TripletSparseMatrix::RandomMatrixOptions options; + options.num_rows = 5; + options.num_cols = 7; + options.density = 0.5; + + const int kNumTrials = 10; + for (int i = 0; i < kNumTrials; ++i) { + scoped_ptr tsm( + TripletSparseMatrix::CreateRandomMatrix(options)); + scoped_ptr crsm( + CompressedRowSparseMatrix::FromTripletSparseMatrixTransposed(*tsm)); + + Matrix tmp; + tsm->ToDenseMatrix(&tmp); + Matrix expected = tmp.transpose(); + Matrix actual; + crsm->ToDenseMatrix(&actual); + EXPECT_NEAR((expected - actual).norm() / actual.norm(), + 0.0, + std::numeric_limits::epsilon()) + << "\nexpected: \n" + << expected << "\nactual: \n" + << actual; + } +} + +// TODO(sameeragarwal) Add tests for the random matrix creation methods. + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/conditioned_cost_function.cc b/internal/ceres/conditioned_cost_function.cc new file mode 100644 index 0000000..08899e3 --- /dev/null +++ b/internal/ceres/conditioned_cost_function.cc @@ -0,0 +1,130 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: wjr@google.com (William Rucklidge) +// +// This file contains the implementation of the conditioned cost function. + +#include "ceres/conditioned_cost_function.h" + +#include + +#include "ceres/internal/eigen.h" +#include "ceres/stl_util.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { + +// This cost function has the same dimensions (parameters, residuals) as +// the one it's wrapping. +ConditionedCostFunction::ConditionedCostFunction( + CostFunction* wrapped_cost_function, + const std::vector& conditioners, + Ownership ownership) + : wrapped_cost_function_(wrapped_cost_function), + conditioners_(conditioners), + ownership_(ownership) { + // Set up our dimensions. + set_num_residuals(wrapped_cost_function_->num_residuals()); + *mutable_parameter_block_sizes() = + wrapped_cost_function_->parameter_block_sizes(); + + // Sanity-check the conditioners' dimensions. + CHECK_EQ(wrapped_cost_function_->num_residuals(), conditioners_.size()); + for (int i = 0; i < wrapped_cost_function_->num_residuals(); i++) { + if (conditioners[i]) { + CHECK_EQ(1, conditioners[i]->num_residuals()); + CHECK_EQ(1, conditioners[i]->parameter_block_sizes().size()); + CHECK_EQ(1, conditioners[i]->parameter_block_sizes()[0]); + } + } +} + +ConditionedCostFunction::~ConditionedCostFunction() { + if (ownership_ == TAKE_OWNERSHIP) { + STLDeleteElements(&conditioners_); + } else { + wrapped_cost_function_.release(); + } +} + +bool ConditionedCostFunction::Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + bool success = wrapped_cost_function_->Evaluate(parameters, residuals, + jacobians); + if (!success) { + return false; + } + + for (int r = 0; r < wrapped_cost_function_->num_residuals(); r++) { + // On output, we want to have + // residuals[r] = conditioners[r](wrapped_residuals[r]) + // For parameter block i, column c, + // jacobians[i][r*parameter_block_size_[i] + c] = + // = d residual[r] / d parameters[i][c] + // = conditioners[r]'(wrapped_residuals[r]) * + // d wrapped_residuals[r] / d parameters[i][c] + if (conditioners_[r]) { + double conditioner_derivative; + double* conditioner_derivative_pointer = &conditioner_derivative; + double** conditioner_derivative_pointer2 = + &conditioner_derivative_pointer; + if (!jacobians) { + conditioner_derivative_pointer2 = NULL; + } + + double unconditioned_residual = residuals[r]; + double* parameter_pointer = &unconditioned_residual; + success = conditioners_[r]->Evaluate(¶meter_pointer, + &residuals[r], + conditioner_derivative_pointer2); + if (!success) { + return false; + } + + if (jacobians) { + for (int i = 0; + i < wrapped_cost_function_->parameter_block_sizes().size(); + i++) { + if (jacobians[i]) { + int parameter_block_size = + wrapped_cost_function_->parameter_block_sizes()[i]; + VectorRef jacobian_row(jacobians[i] + r * parameter_block_size, + parameter_block_size, 1); + jacobian_row *= conditioner_derivative; + } + } + } + } + } + return true; +} + +} // namespace ceres diff --git a/internal/ceres/conditioned_cost_function_test.cc b/internal/ceres/conditioned_cost_function_test.cc new file mode 100644 index 0000000..528e0ee --- /dev/null +++ b/internal/ceres/conditioned_cost_function_test.cc @@ -0,0 +1,126 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: wjr@google.com (William Rucklidge) +// +// Tests for the conditioned cost function. + +#include "ceres/conditioned_cost_function.h" + +#include "ceres/internal/eigen.h" +#include "ceres/normal_prior.h" +#include "ceres/types.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +// The size of the cost functions we build. +static const int kTestCostFunctionSize = 3; + +// A simple cost function: return ax + b. +class LinearCostFunction : public CostFunction { + public: + LinearCostFunction(double a, double b) : a_(a), b_(b) { + set_num_residuals(1); + mutable_parameter_block_sizes()->push_back(1); + } + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + *residuals = **parameters * a_ + b_; + if (jacobians && *jacobians) { + **jacobians = a_; + } + + return true; + } + + private: + const double a_, b_; +}; + +// Tests that ConditionedCostFunction does what it's supposed to. +TEST(CostFunctionTest, ConditionedCostFunction) { + double v1[kTestCostFunctionSize], v2[kTestCostFunctionSize], + jac[kTestCostFunctionSize * kTestCostFunctionSize], + result[kTestCostFunctionSize]; + + for (int i = 0; i < kTestCostFunctionSize; i++) { + v1[i] = i; + v2[i] = i * 10; + // Seed a few garbage values in the Jacobian matrix, to make sure that + // they're overwritten. + jac[i * 2] = i * i; + result[i] = i * i * i; + } + + // Make a cost function that computes x - v2 + VectorRef v2_vector(v2, kTestCostFunctionSize, 1); + Matrix identity(kTestCostFunctionSize, kTestCostFunctionSize); + identity.setIdentity(); + NormalPrior* difference_cost_function = new NormalPrior(identity, v2_vector); + + std::vector conditioners; + for (int i = 0; i < kTestCostFunctionSize; i++) { + conditioners.push_back(new LinearCostFunction(i + 2, i * 7)); + } + + ConditionedCostFunction conditioned_cost_function(difference_cost_function, + conditioners, + TAKE_OWNERSHIP); + EXPECT_EQ(difference_cost_function->num_residuals(), + conditioned_cost_function.num_residuals()); + EXPECT_EQ(difference_cost_function->parameter_block_sizes(), + conditioned_cost_function.parameter_block_sizes()); + + double *parameters[1]; + parameters[0] = v1; + double *jacs[1]; + jacs[0] = jac; + + conditioned_cost_function.Evaluate(parameters, result, jacs); + for (int i = 0; i < kTestCostFunctionSize; i++) { + EXPECT_DOUBLE_EQ((i + 2) * (v1[i] - v2[i]) + i * 7, result[i]); + } + + for (int i = 0; i < kTestCostFunctionSize; i++) { + for (int j = 0; j < kTestCostFunctionSize; j++) { + double actual = jac[i * kTestCostFunctionSize + j]; + if (i != j) { + EXPECT_DOUBLE_EQ(0, actual); + } else { + EXPECT_DOUBLE_EQ(i + 2, actual); + } + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/conjugate_gradients_solver.cc b/internal/ceres/conjugate_gradients_solver.cc new file mode 100644 index 0000000..3702276 --- /dev/null +++ b/internal/ceres/conjugate_gradients_solver.cc @@ -0,0 +1,248 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// A preconditioned conjugate gradients solver +// (ConjugateGradientsSolver) for positive semidefinite linear +// systems. +// +// We have also augmented the termination criterion used by this +// solver to support not just residual based termination but also +// termination based on decrease in the value of the quadratic model +// that CG optimizes. + +#include "ceres/conjugate_gradients_solver.h" + +#include +#include +#include "ceres/fpclassify.h" +#include "ceres/internal/eigen.h" +#include "ceres/linear_operator.h" +#include "ceres/stringprintf.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { +namespace { + +bool IsZeroOrInfinity(double x) { + return ((x == 0.0) || (IsInfinite(x))); +} + +} // namespace + +ConjugateGradientsSolver::ConjugateGradientsSolver( + const LinearSolver::Options& options) + : options_(options) { +} + +LinearSolver::Summary ConjugateGradientsSolver::Solve( + LinearOperator* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + CHECK_NOTNULL(A); + CHECK_NOTNULL(x); + CHECK_NOTNULL(b); + CHECK_EQ(A->num_rows(), A->num_cols()); + + LinearSolver::Summary summary; + summary.termination_type = LINEAR_SOLVER_NO_CONVERGENCE; + summary.message = "Maximum number of iterations reached."; + summary.num_iterations = 0; + + const int num_cols = A->num_cols(); + VectorRef xref(x, num_cols); + ConstVectorRef bref(b, num_cols); + + const double norm_b = bref.norm(); + if (norm_b == 0.0) { + xref.setZero(); + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = "Convergence. |b| = 0."; + return summary; + } + + Vector r(num_cols); + Vector p(num_cols); + Vector z(num_cols); + Vector tmp(num_cols); + + const double tol_r = per_solve_options.r_tolerance * norm_b; + + tmp.setZero(); + A->RightMultiply(x, tmp.data()); + r = bref - tmp; + double norm_r = r.norm(); + if (options_.min_num_iterations == 0 && norm_r <= tol_r) { + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = + StringPrintf("Convergence. |r| = %e <= %e.", norm_r, tol_r); + return summary; + } + + double rho = 1.0; + + // Initial value of the quadratic model Q = x'Ax - 2 * b'x. + double Q0 = -1.0 * xref.dot(bref + r); + + for (summary.num_iterations = 1;; ++summary.num_iterations) { + // Apply preconditioner + if (per_solve_options.preconditioner != NULL) { + z.setZero(); + per_solve_options.preconditioner->RightMultiply(r.data(), z.data()); + } else { + z = r; + } + + double last_rho = rho; + rho = r.dot(z); + if (IsZeroOrInfinity(rho)) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = StringPrintf("Numerical failure. rho = r'z = %e.", rho); + break; + } + + if (summary.num_iterations == 1) { + p = z; + } else { + double beta = rho / last_rho; + if (IsZeroOrInfinity(beta)) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = StringPrintf( + "Numerical failure. beta = rho_n / rho_{n-1} = %e, " + "rho_n = %e, rho_{n-1} = %e", beta, rho, last_rho); + break; + } + p = z + beta * p; + } + + Vector& q = z; + q.setZero(); + A->RightMultiply(p.data(), q.data()); + const double pq = p.dot(q); + if ((pq <= 0) || IsInfinite(pq)) { + summary.termination_type = LINEAR_SOLVER_NO_CONVERGENCE; + summary.message = StringPrintf( + "Matrix is indefinite, no more progress can be made. " + "p'q = %e. |p| = %e, |q| = %e", + pq, p.norm(), q.norm()); + break; + } + + const double alpha = rho / pq; + if (IsInfinite(alpha)) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = + StringPrintf("Numerical failure. alpha = rho / pq = %e, " + "rho = %e, pq = %e.", alpha, rho, pq); + break; + } + + xref = xref + alpha * p; + + // Ideally we would just use the update r = r - alpha*q to keep + // track of the residual vector. However this estimate tends to + // drift over time due to round off errors. Thus every + // residual_reset_period iterations, we calculate the residual as + // r = b - Ax. We do not do this every iteration because this + // requires an additional matrix vector multiply which would + // double the complexity of the CG algorithm. + if (summary.num_iterations % options_.residual_reset_period == 0) { + tmp.setZero(); + A->RightMultiply(x, tmp.data()); + r = bref - tmp; + } else { + r = r - alpha * q; + } + + // Quadratic model based termination. + // Q1 = x'Ax - 2 * b' x. + const double Q1 = -1.0 * xref.dot(bref + r); + + // For PSD matrices A, let + // + // Q(x) = x'Ax - 2b'x + // + // be the cost of the quadratic function defined by A and b. Then, + // the solver terminates at iteration i if + // + // i * (Q(x_i) - Q(x_i-1)) / Q(x_i) < q_tolerance. + // + // This termination criterion is more useful when using CG to + // solve the Newton step. This particular convergence test comes + // from Stephen Nash's work on truncated Newton + // methods. References: + // + // 1. Stephen G. Nash & Ariela Sofer, Assessing A Search + // Direction Within A Truncated Newton Method, Operation + // Research Letters 9(1990) 219-221. + // + // 2. Stephen G. Nash, A Survey of Truncated Newton Methods, + // Journal of Computational and Applied Mathematics, + // 124(1-2), 45-59, 2000. + // + const double zeta = summary.num_iterations * (Q1 - Q0) / Q1; + if (zeta < per_solve_options.q_tolerance && + summary.num_iterations >= options_.min_num_iterations) { + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = + StringPrintf("Iteration: %d Convergence: zeta = %e < %e. |r| = %e", + summary.num_iterations, + zeta, + per_solve_options.q_tolerance, + r.norm()); + break; + } + Q0 = Q1; + + // Residual based termination. + norm_r = r. norm(); + if (norm_r <= tol_r && + summary.num_iterations >= options_.min_num_iterations) { + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = + StringPrintf("Iteration: %d Convergence. |r| = %e <= %e.", + summary.num_iterations, + norm_r, + tol_r); + break; + } + + if (summary.num_iterations >= options_.max_num_iterations) { + break; + } + } + + return summary; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/conjugate_gradients_solver.h b/internal/ceres/conjugate_gradients_solver.h new file mode 100644 index 0000000..a1e1833 --- /dev/null +++ b/internal/ceres/conjugate_gradients_solver.h @@ -0,0 +1,74 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Preconditioned Conjugate Gradients based solver for positive +// semidefinite linear systems. + +#ifndef CERES_INTERNAL_CONJUGATE_GRADIENTS_SOLVER_H_ +#define CERES_INTERNAL_CONJUGATE_GRADIENTS_SOLVER_H_ + +#include "ceres/linear_solver.h" +#include "ceres/internal/macros.h" + +namespace ceres { +namespace internal { + +class LinearOperator; + +// This class implements the now classical Conjugate Gradients +// algorithm of Hestenes & Stiefel for solving postive semidefinite +// linear sytems. Optionally it can use a preconditioner also to +// reduce the condition number of the linear system and improve the +// convergence rate. Modern references for Conjugate Gradients are the +// books by Yousef Saad and Trefethen & Bau. This implementation of CG +// has been augmented with additional termination tests that are +// needed for forcing early termination when used as part of an +// inexact Newton solver. +// +// For more details see the documentation for +// LinearSolver::PerSolveOptions::r_tolerance and +// LinearSolver::PerSolveOptions::q_tolerance in linear_solver.h. +class ConjugateGradientsSolver : public LinearSolver { + public: + explicit ConjugateGradientsSolver(const LinearSolver::Options& options); + virtual Summary Solve(LinearOperator* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + private: + const LinearSolver::Options options_; + CERES_DISALLOW_COPY_AND_ASSIGN(ConjugateGradientsSolver); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CONJUGATE_GRADIENTS_SOLVER_H_ diff --git a/internal/ceres/conjugate_gradients_solver_test.cc b/internal/ceres/conjugate_gradients_solver_test.cc new file mode 100644 index 0000000..1f5c3ae --- /dev/null +++ b/internal/ceres/conjugate_gradients_solver_test.cc @@ -0,0 +1,135 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: fredp@google.com (Fred Pighin) +// +// TODO(sameeragarwal): More comprehensive testing with larger and +// more badly conditioned problem. + +#include "gtest/gtest.h" +#include "ceres/conjugate_gradients_solver.h" +#include "ceres/linear_solver.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" + +namespace ceres { +namespace internal { + +TEST(ConjugateGradientTest, Solves3x3IdentitySystem) { + double diagonal[] = { 1.0, 1.0, 1.0 }; + scoped_ptr + A(TripletSparseMatrix::CreateSparseDiagonalMatrix(diagonal, 3)); + Vector b(3); + Vector x(3); + + b(0) = 1.0; + b(1) = 2.0; + b(2) = 3.0; + + x(0) = 1; + x(1) = 1; + x(2) = 1; + + LinearSolver::Options options; + options.max_num_iterations = 10; + + LinearSolver::PerSolveOptions per_solve_options; + per_solve_options.r_tolerance = 1e-9; + + ConjugateGradientsSolver solver(options); + LinearSolver::Summary summary = + solver.Solve(A.get(), b.data(), per_solve_options, x.data()); + + EXPECT_EQ(summary.termination_type, LINEAR_SOLVER_SUCCESS); + ASSERT_EQ(summary.num_iterations, 1); + + ASSERT_DOUBLE_EQ(1, x(0)); + ASSERT_DOUBLE_EQ(2, x(1)); + ASSERT_DOUBLE_EQ(3, x(2)); +} + + +TEST(ConjuateGradientTest, Solves3x3SymmetricSystem) { + scoped_ptr A(new TripletSparseMatrix(3, 3, 9)); + Vector b(3); + Vector x(3); + + // | 2 -1 0| + // A = |-1 2 -1| is symmetric positive definite. + // | 0 -1 2| + int* Ai = A->mutable_rows(); + int* Aj = A->mutable_cols(); + double* Ax = A->mutable_values(); + int counter = 0; + for (int i = 0; i < 3; ++i) { + for (int j = 0; j < 3; ++j) { + Ai[counter] = i; + Aj[counter] = j; + ++counter; + } + } + Ax[0] = 2.; + Ax[1] = -1.; + Ax[2] = 0; + Ax[3] = -1.; + Ax[4] = 2; + Ax[5] = -1; + Ax[6] = 0; + Ax[7] = -1; + Ax[8] = 2; + A->set_num_nonzeros(9); + + b(0) = -1; + b(1) = 0; + b(2) = 3; + + x(0) = 1; + x(1) = 1; + x(2) = 1; + + LinearSolver::Options options; + options.max_num_iterations = 10; + + LinearSolver::PerSolveOptions per_solve_options; + per_solve_options.r_tolerance = 1e-9; + + ConjugateGradientsSolver solver(options); + LinearSolver::Summary summary = + solver.Solve(A.get(), b.data(), per_solve_options, x.data()); + + EXPECT_EQ(summary.termination_type, LINEAR_SOLVER_SUCCESS); + + ASSERT_DOUBLE_EQ(0, x(0)); + ASSERT_DOUBLE_EQ(1, x(1)); + ASSERT_DOUBLE_EQ(2, x(2)); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/coordinate_descent_minimizer.cc b/internal/ceres/coordinate_descent_minimizer.cc new file mode 100644 index 0000000..c6b42cf --- /dev/null +++ b/internal/ceres/coordinate_descent_minimizer.cc @@ -0,0 +1,278 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/coordinate_descent_minimizer.h" + +#ifdef CERES_USE_OPENMP +#include +#endif + +#include +#include +#include +#include "ceres/evaluator.h" +#include "ceres/linear_solver.h" +#include "ceres/minimizer.h" +#include "ceres/parameter_block.h" +#include "ceres/parameter_block_ordering.h" +#include "ceres/problem_impl.h" +#include "ceres/program.h" +#include "ceres/residual_block.h" +#include "ceres/solver.h" +#include "ceres/trust_region_minimizer.h" +#include "ceres/trust_region_strategy.h" + +namespace ceres { +namespace internal { + +using std::map; +using std::max; +using std::min; +using std::set; +using std::string; +using std::vector; + +CoordinateDescentMinimizer::~CoordinateDescentMinimizer() { +} + +bool CoordinateDescentMinimizer::Init( + const Program& program, + const ProblemImpl::ParameterMap& parameter_map, + const ParameterBlockOrdering& ordering, + string* error) { + parameter_blocks_.clear(); + independent_set_offsets_.clear(); + independent_set_offsets_.push_back(0); + + // Serialize the OrderedGroups into a vector of parameter block + // offsets for parallel access. + map parameter_block_index; + map > group_to_elements = ordering.group_to_elements(); + for (map >::const_iterator it = group_to_elements.begin(); + it != group_to_elements.end(); + ++it) { + for (set::const_iterator ptr_it = it->second.begin(); + ptr_it != it->second.end(); + ++ptr_it) { + parameter_blocks_.push_back(parameter_map.find(*ptr_it)->second); + parameter_block_index[parameter_blocks_.back()] = + parameter_blocks_.size() - 1; + } + independent_set_offsets_.push_back( + independent_set_offsets_.back() + it->second.size()); + } + + // The ordering does not have to contain all parameter blocks, so + // assign zero offsets/empty independent sets to these parameter + // blocks. + const vector& parameter_blocks = program.parameter_blocks(); + for (int i = 0; i < parameter_blocks.size(); ++i) { + if (!ordering.IsMember(parameter_blocks[i]->mutable_user_state())) { + parameter_blocks_.push_back(parameter_blocks[i]); + independent_set_offsets_.push_back(independent_set_offsets_.back()); + } + } + + // Compute the set of residual blocks that depend on each parameter + // block. + residual_blocks_.resize(parameter_block_index.size()); + const vector& residual_blocks = program.residual_blocks(); + for (int i = 0; i < residual_blocks.size(); ++i) { + ResidualBlock* residual_block = residual_blocks[i]; + const int num_parameter_blocks = residual_block->NumParameterBlocks(); + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + const map::const_iterator it = + parameter_block_index.find(parameter_block); + if (it != parameter_block_index.end()) { + residual_blocks_[it->second].push_back(residual_block); + } + } + } + + evaluator_options_.linear_solver_type = DENSE_QR; + evaluator_options_.num_eliminate_blocks = 0; + evaluator_options_.num_threads = 1; + + return true; +} + +void CoordinateDescentMinimizer::Minimize( + const Minimizer::Options& options, + double* parameters, + Solver::Summary* summary) { + // Set the state and mark all parameter blocks constant. + for (int i = 0; i < parameter_blocks_.size(); ++i) { + ParameterBlock* parameter_block = parameter_blocks_[i]; + parameter_block->SetState(parameters + parameter_block->state_offset()); + parameter_block->SetConstant(); + } + + scoped_array linear_solvers( + new LinearSolver*[options.num_threads]); + + LinearSolver::Options linear_solver_options; + linear_solver_options.type = DENSE_QR; + + for (int i = 0; i < options.num_threads; ++i) { + linear_solvers[i] = LinearSolver::Create(linear_solver_options); + } + + for (int i = 0; i < independent_set_offsets_.size() - 1; ++i) { + const int num_problems = + independent_set_offsets_[i + 1] - independent_set_offsets_[i]; + // No point paying the price for an OpemMP call if the set is of + // size zero. + if (num_problems == 0) { + continue; + } + +#ifdef CERES_USE_OPENMP + const int num_inner_iteration_threads = + min(options.num_threads, num_problems); + evaluator_options_.num_threads = + max(1, options.num_threads / num_inner_iteration_threads); + + // The parameter blocks in each independent set can be optimized + // in parallel, since they do not co-occur in any residual block. +#pragma omp parallel for num_threads(num_inner_iteration_threads) +#endif + for (int j = independent_set_offsets_[i]; + j < independent_set_offsets_[i + 1]; + ++j) { +#ifdef CERES_USE_OPENMP + int thread_id = omp_get_thread_num(); +#else + int thread_id = 0; +#endif + + ParameterBlock* parameter_block = parameter_blocks_[j]; + const int old_index = parameter_block->index(); + const int old_delta_offset = parameter_block->delta_offset(); + parameter_block->SetVarying(); + parameter_block->set_index(0); + parameter_block->set_delta_offset(0); + + Program inner_program; + inner_program.mutable_parameter_blocks()->push_back(parameter_block); + *inner_program.mutable_residual_blocks() = residual_blocks_[j]; + + // TODO(sameeragarwal): Better error handling. Right now we + // assume that this is not going to lead to problems of any + // sort. Basically we should be checking for numerical failure + // of some sort. + // + // On the other hand, if the optimization is a failure, that in + // some ways is fine, since it won't change the parameters and + // we are fine. + Solver::Summary inner_summary; + Solve(&inner_program, + linear_solvers[thread_id], + parameters + parameter_block->state_offset(), + &inner_summary); + + parameter_block->set_index(old_index); + parameter_block->set_delta_offset(old_delta_offset); + parameter_block->SetState(parameters + parameter_block->state_offset()); + parameter_block->SetConstant(); + } + } + + for (int i = 0; i < parameter_blocks_.size(); ++i) { + parameter_blocks_[i]->SetVarying(); + } + + for (int i = 0; i < options.num_threads; ++i) { + delete linear_solvers[i]; + } +} + +// Solve the optimization problem for one parameter block. +void CoordinateDescentMinimizer::Solve(Program* program, + LinearSolver* linear_solver, + double* parameter, + Solver::Summary* summary) { + *summary = Solver::Summary(); + summary->initial_cost = 0.0; + summary->fixed_cost = 0.0; + summary->final_cost = 0.0; + string error; + + Minimizer::Options minimizer_options; + minimizer_options.evaluator.reset( + CHECK_NOTNULL(Evaluator::Create(evaluator_options_, program, &error))); + minimizer_options.jacobian.reset( + CHECK_NOTNULL(minimizer_options.evaluator->CreateJacobian())); + + TrustRegionStrategy::Options trs_options; + trs_options.linear_solver = linear_solver; + minimizer_options.trust_region_strategy.reset( + CHECK_NOTNULL(TrustRegionStrategy::Create(trs_options))); + minimizer_options.is_silent = true; + + TrustRegionMinimizer minimizer; + minimizer.Minimize(minimizer_options, parameter, summary); +} + +bool CoordinateDescentMinimizer::IsOrderingValid( + const Program& program, + const ParameterBlockOrdering& ordering, + string* message) { + const map >& group_to_elements = + ordering.group_to_elements(); + + // Verify that each group is an independent set + map >::const_iterator it = group_to_elements.begin(); + for (; it != group_to_elements.end(); ++it) { + if (!program.IsParameterBlockSetIndependent(it->second)) { + *message = + StringPrintf("The user-provided " + "parameter_blocks_for_inner_iterations does not " + "form an independent set. Group Id: %d", it->first); + return false; + } + } + return true; +} + +// Find a recursive decomposition of the Hessian matrix as a set +// of independent sets of decreasing size and invert it. This +// seems to work better in practice, i.e., Cameras before +// points. +ParameterBlockOrdering* CoordinateDescentMinimizer::CreateOrdering( + const Program& program) { + scoped_ptr ordering(new ParameterBlockOrdering); + ComputeRecursiveIndependentSetOrdering(program, ordering.get()); + ordering->Reverse(); + return ordering.release(); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/coordinate_descent_minimizer.h b/internal/ceres/coordinate_descent_minimizer.h new file mode 100644 index 0000000..25ea04c --- /dev/null +++ b/internal/ceres/coordinate_descent_minimizer.h @@ -0,0 +1,102 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_COORDINATE_DESCENT_MINIMIZER_H_ +#define CERES_INTERNAL_COORDINATE_DESCENT_MINIMIZER_H_ + +#include +#include + +#include "ceres/evaluator.h" +#include "ceres/minimizer.h" +#include "ceres/problem_impl.h" +#include "ceres/solver.h" + +namespace ceres { +namespace internal { + +class Program; +class LinearSolver; + +// Given a Program, and a ParameterBlockOrdering which partitions +// (non-exhaustively) the Hessian matrix into independent sets, +// perform coordinate descent on the parameter blocks in the +// ordering. The independent set structure allows for all parameter +// blocks in the same independent set to be optimized in parallel, and +// the order of the independent set determines the order in which the +// parameter block groups are optimized. +// +// The minimizer assumes that none of the parameter blocks in the +// program are constant. +class CoordinateDescentMinimizer : public Minimizer { + public: + bool Init(const Program& program, + const ProblemImpl::ParameterMap& parameter_map, + const ParameterBlockOrdering& ordering, + std::string* error); + + // Minimizer interface. + virtual ~CoordinateDescentMinimizer(); + virtual void Minimize(const Minimizer::Options& options, + double* parameters, + Solver::Summary* summary); + + // Verify that each group in the ordering forms an independent set. + static bool IsOrderingValid(const Program& program, + const ParameterBlockOrdering& ordering, + std::string* message); + + // Find a recursive decomposition of the Hessian matrix as a set + // of independent sets of decreasing size and invert it. This + // seems to work better in practice, i.e., Cameras before + // points. + static ParameterBlockOrdering* CreateOrdering(const Program& program); + + private: + void Solve(Program* program, + LinearSolver* linear_solver, + double* parameters, + Solver::Summary* summary); + + std::vector parameter_blocks_; + std::vector > residual_blocks_; + // The optimization is performed in rounds. In each round all the + // parameter blocks that form one independent set are optimized in + // parallel. This array, marks the boundaries of the independent + // sets in parameter_blocks_. + std::vector independent_set_offsets_; + + Evaluator::Options evaluator_options_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_COORDINATE_DESCENT_MINIMIZER_H_ diff --git a/internal/ceres/corrector.cc b/internal/ceres/corrector.cc new file mode 100644 index 0000000..7201828 --- /dev/null +++ b/internal/ceres/corrector.cc @@ -0,0 +1,158 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/corrector.h" + +#include +#include +#include "ceres/internal/eigen.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +Corrector::Corrector(const double sq_norm, const double rho[3]) { + CHECK_GE(sq_norm, 0.0); + sqrt_rho1_ = sqrt(rho[1]); + + // If sq_norm = 0.0, the correction becomes trivial, the residual + // and the jacobian are scaled by the squareroot of the derivative + // of rho. Handling this case explicitly avoids the divide by zero + // error that would occur below. + // + // The case where rho'' < 0 also gets special handling. Technically + // it shouldn't, and the computation of the scaling should proceed + // as below, however we found in experiments that applying the + // curvature correction when rho'' < 0, which is the case when we + // are in the outlier region slows down the convergence of the + // algorithm significantly. + // + // Thus, we have divided the action of the robustifier into two + // parts. In the inliner region, we do the full second order + // correction which re-wights the gradient of the function by the + // square root of the derivative of rho, and the Gauss-Newton + // Hessian gets both the scaling and the rank-1 curvature + // correction. Normaly, alpha is upper bounded by one, but with this + // change, alpha is bounded above by zero. + // + // Empirically we have observed that the full Triggs correction and + // the clamped correction both start out as very good approximations + // to the loss function when we are in the convex part of the + // function, but as the function starts transitioning from convex to + // concave, the Triggs approximation diverges more and more and + // ultimately becomes linear. The clamped Triggs model however + // remains quadratic. + // + // The reason why the Triggs approximation becomes so poor is + // because the curvature correction that it applies to the gauss + // newton hessian goes from being a full rank correction to a rank + // deficient correction making the inversion of the Hessian fraught + // with all sorts of misery and suffering. + // + // The clamped correction retains its quadratic nature and inverting it + // is always well formed. + if ((sq_norm == 0.0) || (rho[2] <= 0.0)) { + residual_scaling_ = sqrt_rho1_; + alpha_sq_norm_ = 0.0; + return; + } + + // We now require that the first derivative of the loss function be + // positive only if the second derivative is positive. This is + // because when the second derivative is non-positive, we do not use + // the second order correction suggested by BANS and instead use a + // simpler first order strategy which does not use a division by the + // gradient of the loss function. + CHECK_GT(rho[1], 0.0); + + // Calculate the smaller of the two solutions to the equation + // + // 0.5 * alpha^2 - alpha - rho'' / rho' * z'z = 0. + // + // Start by calculating the discriminant D. + const double D = 1.0 + 2.0 * sq_norm * rho[2] / rho[1]; + + // Since both rho[1] and rho[2] are guaranteed to be positive at + // this point, we know that D > 1.0. + + const double alpha = 1.0 - sqrt(D); + + // Calculate the constants needed by the correction routines. + residual_scaling_ = sqrt_rho1_ / (1 - alpha); + alpha_sq_norm_ = alpha / sq_norm; +} + +void Corrector::CorrectResiduals(const int num_rows, double* residuals) { + DCHECK(residuals != NULL); + // Equation 11 in BANS. + VectorRef(residuals, num_rows) *= residual_scaling_; +} + +void Corrector::CorrectJacobian(const int num_rows, + const int num_cols, + double* residuals, + double* jacobian) { + DCHECK(residuals != NULL); + DCHECK(jacobian != NULL); + + // The common case (rho[2] <= 0). + if (alpha_sq_norm_ == 0.0) { + VectorRef(jacobian, num_rows * num_cols) *= sqrt_rho1_; + return; + } + + // Equation 11 in BANS. + // + // J = sqrt(rho) * (J - alpha^2 r * r' J) + // + // In days gone by this loop used to be a single Eigen expression of + // the form + // + // J = sqrt_rho1_ * (J - alpha_sq_norm_ * r* (r.transpose() * J)); + // + // Which turns out to about 17x slower on bal problems. The reason + // is that Eigen is unable to figure out that this expression can be + // evaluated columnwise and ends up creating a temporary. + for (int c = 0; c < num_cols; ++c) { + double r_transpose_j = 0.0; + for (int r = 0; r < num_rows; ++r) { + r_transpose_j += jacobian[r * num_cols + c] * residuals[r]; + } + + for (int r = 0; r < num_rows; ++r) { + jacobian[r * num_cols + c] = sqrt_rho1_ * + (jacobian[r * num_cols + c] - + alpha_sq_norm_ * residuals[r] * r_transpose_j); + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/corrector.h b/internal/ceres/corrector.h new file mode 100644 index 0000000..315f012 --- /dev/null +++ b/internal/ceres/corrector.h @@ -0,0 +1,90 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Class definition for the object that is responsible for applying a +// second order correction to the Gauss-Newton based on the ideas in +// BANS by Triggs et al. + +#ifndef CERES_INTERNAL_CORRECTOR_H_ +#define CERES_INTERNAL_CORRECTOR_H_ + +namespace ceres { +namespace internal { + +// Corrector is responsible for applying the second order correction +// to the residual and jacobian of a least squares problem based on a +// radial robust loss. +// +// The key idea here is to look at the expressions for the robustified +// gauss newton approximation and then take its squareroot to get the +// corresponding corrections to the residual and jacobian. For the +// full expressions see Eq. 10 and 11 in BANS by Triggs et al. +class Corrector { + public: + // The constructor takes the squared norm, the value, the first and + // second derivatives of the LossFunction. It precalculates some of + // the constants that are needed to apply the correction. The + // correction constant alpha is constrained to be smaller than 1, if + // it becomes larger than 1, then it will reverse the sign of the + // residual and the correction. If alpha is equal to 1 will result + // in a divide by zero error. Thus we constrain alpha to be upper + // bounded by 1 - epsilon_. + // + // rho[1] needs to be positive. The constructor will crash if this + // condition is not met. + // + // In practical use CorrectJacobian should always be called before + // CorrectResidual, because the jacobian correction depends on the + // value of the uncorrected residual values. + explicit Corrector(double sq_norm, const double rho[3]); + + // residuals *= sqrt(rho[1]) / (1 - alpha) + void CorrectResiduals(int num_rows, double* residuals); + + // jacobian = sqrt(rho[1]) * jacobian - + // sqrt(rho[1]) * alpha / sq_norm * residuals residuals' * jacobian. + // + // The method assumes that the jacobian has row-major storage. It is + // the caller's responsibility to ensure that the pointer to + // jacobian is not null. + void CorrectJacobian(int num_rows, + int num_cols, + double* residuals, + double* jacobian); + + private: + double sqrt_rho1_; + double residual_scaling_; + double alpha_sq_norm_; +}; +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_CORRECTOR_H_ diff --git a/internal/ceres/corrector_test.cc b/internal/ceres/corrector_test.cc new file mode 100644 index 0000000..a6581fd --- /dev/null +++ b/internal/ceres/corrector_test.cc @@ -0,0 +1,276 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/corrector.h" + +#include +#include +#include +#include +#include "gtest/gtest.h" +#include "ceres/random.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +// If rho[1] is zero, the Corrector constructor should crash. +TEST(Corrector, ZeroGradientDeathTest) { + const double kRho[] = {0.0, 0.0, 1.0}; + EXPECT_DEATH_IF_SUPPORTED({Corrector c(1.0, kRho);}, + ".*"); +} + +// If rho[1] is negative, the Corrector constructor should crash. +TEST(Corrector, NegativeGradientDeathTest) { + const double kRho[] = {0.0, -0.1, 1.0}; + EXPECT_DEATH_IF_SUPPORTED({Corrector c(1.0, kRho);}, + ".*"); +} + +TEST(Corrector, ScalarCorrection) { + double residuals = sqrt(3.0); + double jacobian = 10.0; + double sq_norm = residuals * residuals; + + const double kRho[] = {sq_norm, 0.1, -0.01}; + + // In light of the rho'' < 0 clamping now implemented in + // corrector.cc, alpha = 0 whenever rho'' < 0. + const double kAlpha = 0.0; + + // Thus the expected value of the residual is + // residual[i] * sqrt(kRho[1]) / (1.0 - kAlpha). + const double kExpectedResidual = + residuals * sqrt(kRho[1]) / (1 - kAlpha); + + // The jacobian in this case will be + // sqrt(kRho[1]) * (1 - kAlpha) * jacobian. + const double kExpectedJacobian = sqrt(kRho[1]) * (1 - kAlpha) * jacobian; + + Corrector c(sq_norm, kRho); + c.CorrectJacobian(1.0, 1.0, &residuals, &jacobian); + c.CorrectResiduals(1.0, &residuals); + + ASSERT_NEAR(residuals, kExpectedResidual, 1e-6); + ASSERT_NEAR(kExpectedJacobian, jacobian, 1e-6); +} + +TEST(Corrector, ScalarCorrectionZeroResidual) { + double residuals = 0.0; + double jacobian = 10.0; + double sq_norm = residuals * residuals; + + const double kRho[] = {0.0, 0.1, -0.01}; + Corrector c(sq_norm, kRho); + + // The alpha equation is + // 1/2 alpha^2 - alpha + 0.0 = 0. + // i.e. alpha = 1.0 - sqrt(1.0). + // alpha = 0.0. + // Thus the expected value of the residual is + // residual[i] * sqrt(kRho[1]) + const double kExpectedResidual = residuals * sqrt(kRho[1]); + + // The jacobian in this case will be + // sqrt(kRho[1]) * jacobian. + const double kExpectedJacobian = sqrt(kRho[1]) * jacobian; + + c.CorrectJacobian(1, 1, &residuals, &jacobian); + c.CorrectResiduals(1, &residuals); + + ASSERT_NEAR(residuals, kExpectedResidual, 1e-6); + ASSERT_NEAR(kExpectedJacobian, jacobian, 1e-6); +} + +// Scaling behaviour for one dimensional functions. +TEST(Corrector, ScalarCorrectionAlphaClamped) { + double residuals = sqrt(3.0); + double jacobian = 10.0; + double sq_norm = residuals * residuals; + + const double kRho[] = {3, 0.1, -0.1}; + + // rho[2] < 0 -> alpha = 0.0 + const double kAlpha = 0.0; + + // Thus the expected value of the residual is + // residual[i] * sqrt(kRho[1]) / (1.0 - kAlpha). + const double kExpectedResidual = + residuals * sqrt(kRho[1]) / (1.0 - kAlpha); + + // The jacobian in this case will be scaled by + // sqrt(rho[1]) * (1 - alpha) * J. + const double kExpectedJacobian = sqrt(kRho[1]) * + (1.0 - kAlpha) * jacobian; + + Corrector c(sq_norm, kRho); + c.CorrectJacobian(1, 1, &residuals, &jacobian); + c.CorrectResiduals(1, &residuals); + + ASSERT_NEAR(residuals, kExpectedResidual, 1e-6); + ASSERT_NEAR(kExpectedJacobian, jacobian, 1e-6); +} + +// Test that the corrected multidimensional residual and jacobians +// match the expected values and the resulting modified normal +// equations match the robustified gauss newton approximation. +TEST(Corrector, MultidimensionalGaussNewtonApproximation) { + double residuals[3]; + double jacobian[2 * 3]; + double rho[3]; + + // Eigen matrix references for linear algebra. + MatrixRef jac(jacobian, 3, 2); + VectorRef res(residuals, 3); + + // Ground truth values of the modified jacobian and residuals. + Matrix g_jac(3, 2); + Vector g_res(3); + + // Ground truth values of the robustified Gauss-Newton + // approximation. + Matrix g_hess(2, 2); + Vector g_grad(2); + + // Corrected hessian and gradient implied by the modified jacobian + // and hessians. + Matrix c_hess(2, 2); + Vector c_grad(2); + + srand(5); + for (int iter = 0; iter < 10000; ++iter) { + // Initialize the jacobian and residual. + for (int i = 0; i < 2 * 3; ++i) + jacobian[i] = RandDouble(); + for (int i = 0; i < 3; ++i) + residuals[i] = RandDouble(); + + const double sq_norm = res.dot(res); + + rho[0] = sq_norm; + rho[1] = RandDouble(); + rho[2] = 2.0 * RandDouble() - 1.0; + + // If rho[2] > 0, then the curvature correction to the correction + // and the gauss newton approximation will match. Otherwise, we + // will clamp alpha to 0. + + const double kD = 1 + 2 * rho[2] / rho[1] * sq_norm; + const double kAlpha = (rho[2] > 0.0) ? 1 - sqrt(kD) : 0.0; + + // Ground truth values. + g_res = sqrt(rho[1]) / (1.0 - kAlpha) * res; + g_jac = sqrt(rho[1]) * (jac - kAlpha / sq_norm * + res * res.transpose() * jac); + + g_grad = rho[1] * jac.transpose() * res; + g_hess = rho[1] * jac.transpose() * jac + + 2.0 * rho[2] * jac.transpose() * res * res.transpose() * jac; + + Corrector c(sq_norm, rho); + c.CorrectJacobian(3, 2, residuals, jacobian); + c.CorrectResiduals(3, residuals); + + // Corrected gradient and hessian. + c_grad = jac.transpose() * res; + c_hess = jac.transpose() * jac; + + ASSERT_NEAR((g_res - res).norm(), 0.0, 1e-10); + ASSERT_NEAR((g_jac - jac).norm(), 0.0, 1e-10); + + ASSERT_NEAR((g_grad - c_grad).norm(), 0.0, 1e-10); + } +} + +TEST(Corrector, MultidimensionalGaussNewtonApproximationZeroResidual) { + double residuals[3]; + double jacobian[2 * 3]; + double rho[3]; + + // Eigen matrix references for linear algebra. + MatrixRef jac(jacobian, 3, 2); + VectorRef res(residuals, 3); + + // Ground truth values of the modified jacobian and residuals. + Matrix g_jac(3, 2); + Vector g_res(3); + + // Ground truth values of the robustified Gauss-Newton + // approximation. + Matrix g_hess(2, 2); + Vector g_grad(2); + + // Corrected hessian and gradient implied by the modified jacobian + // and hessians. + Matrix c_hess(2, 2); + Vector c_grad(2); + + srand(5); + for (int iter = 0; iter < 10000; ++iter) { + // Initialize the jacobian. + for (int i = 0; i < 2 * 3; ++i) + jacobian[i] = RandDouble(); + + // Zero residuals + res.setZero(); + + const double sq_norm = res.dot(res); + + rho[0] = sq_norm; + rho[1] = RandDouble(); + rho[2] = 2 * RandDouble() - 1.0; + + // Ground truth values. + g_res = sqrt(rho[1]) * res; + g_jac = sqrt(rho[1]) * jac; + + g_grad = rho[1] * jac.transpose() * res; + g_hess = rho[1] * jac.transpose() * jac + + 2.0 * rho[2] * jac.transpose() * res * res.transpose() * jac; + + Corrector c(sq_norm, rho); + c.CorrectJacobian(3, 2, residuals, jacobian); + c.CorrectResiduals(3, residuals); + + // Corrected gradient and hessian. + c_grad = jac.transpose() * res; + c_hess = jac.transpose() * jac; + + ASSERT_NEAR((g_res - res).norm(), 0.0, 1e-10); + ASSERT_NEAR((g_jac - jac).norm(), 0.0, 1e-10); + + ASSERT_NEAR((g_grad - c_grad).norm(), 0.0, 1e-10); + ASSERT_NEAR((g_hess - c_hess).norm(), 0.0, 1e-10); + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/cost_function_to_functor_test.cc b/internal/ceres/cost_function_to_functor_test.cc new file mode 100644 index 0000000..6c9a940 --- /dev/null +++ b/internal/ceres/cost_function_to_functor_test.cc @@ -0,0 +1,351 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/cost_function_to_functor.h" +#include "ceres/dynamic_autodiff_cost_function.h" +#include "ceres/dynamic_cost_function_to_functor.h" +#include "ceres/autodiff_cost_function.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::vector; +const double kTolerance = 1e-18; + +void ExpectCostFunctionsAreEqual(const CostFunction& cost_function, + const CostFunction& actual_cost_function) { + EXPECT_EQ(cost_function.num_residuals(), + actual_cost_function.num_residuals()); + const int num_residuals = cost_function.num_residuals(); + const vector& parameter_block_sizes = + cost_function.parameter_block_sizes(); + const vector& actual_parameter_block_sizes = + actual_cost_function.parameter_block_sizes(); + EXPECT_EQ(parameter_block_sizes.size(), + actual_parameter_block_sizes.size()); + + int num_parameters = 0; + for (int i = 0; i < parameter_block_sizes.size(); ++i) { + EXPECT_EQ(parameter_block_sizes[i], actual_parameter_block_sizes[i]); + num_parameters += parameter_block_sizes[i]; + } + + scoped_array parameters(new double[num_parameters]); + for (int i = 0; i < num_parameters; ++i) { + parameters[i] = static_cast(i) + 1.0; + } + + scoped_array residuals(new double[num_residuals]); + scoped_array jacobians(new double[num_parameters * num_residuals]); + + scoped_array actual_residuals(new double[num_residuals]); + scoped_array actual_jacobians + (new double[num_parameters * num_residuals]); + + scoped_array parameter_blocks( + new double*[parameter_block_sizes.size()]); + scoped_array jacobian_blocks( + new double*[parameter_block_sizes.size()]); + scoped_array actual_jacobian_blocks( + new double*[parameter_block_sizes.size()]); + + num_parameters = 0; + for (int i = 0; i < parameter_block_sizes.size(); ++i) { + parameter_blocks[i] = parameters.get() + num_parameters; + jacobian_blocks[i] = jacobians.get() + num_parameters * num_residuals; + actual_jacobian_blocks[i] = + actual_jacobians.get() + num_parameters * num_residuals; + num_parameters += parameter_block_sizes[i]; + } + + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.get(), + residuals.get(), NULL)); + EXPECT_TRUE(actual_cost_function.Evaluate(parameter_blocks.get(), + actual_residuals.get(), NULL)); + for (int i = 0; i < num_residuals; ++i) { + EXPECT_NEAR(residuals[i], actual_residuals[i], kTolerance) + << "residual id: " << i; + } + + + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.get(), + residuals.get(), + jacobian_blocks.get())); + EXPECT_TRUE(actual_cost_function.Evaluate(parameter_blocks.get(), + actual_residuals.get(), + actual_jacobian_blocks.get())); + for (int i = 0; i < num_residuals; ++i) { + EXPECT_NEAR(residuals[i], actual_residuals[i], kTolerance) + << "residual : " << i; + } + + for (int i = 0; i < num_residuals * num_parameters; ++i) { + EXPECT_NEAR(jacobians[i], actual_jacobians[i], kTolerance) + << "jacobian : " << i << " " + << jacobians[i] << " " << actual_jacobians[i]; + } +} + +struct OneParameterBlockFunctor { + public: + template + bool operator()(const T* x1, T* residuals) const { + residuals[0] = x1[0] * x1[0]; + residuals[1] = x1[1] * x1[1]; + return true; + } +}; + +struct TwoParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1]; + return true; + } +}; + +struct ThreeParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1]; + return true; + } +}; + +struct FourParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1]; + return true; + } +}; + +struct FiveParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1]; + return true; + } +}; + +struct SixParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, const T* x6, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0] + x6[0] * x6[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1] + x6[1] * x6[1]; + return true; + } +}; + +struct SevenParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, const T* x6, const T* x7, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0] + x6[0] * x6[0] + x7[0] * x7[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1] + x6[1] * x6[1] + x7[1] * x7[1]; + return true; + } +}; + +struct EightParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, const T* x6, const T* x7, const T* x8, + T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0] + x6[0] * x6[0] + x7[0] * x7[0] + + x8[0] * x8[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1] + x6[1] * x6[1] + x7[1] * x7[1] + + x8[1] * x8[1]; + return true; + } +}; + +struct NineParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, const T* x6, const T* x7, const T* x8, + const T* x9, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0] + x6[0] * x6[0] + x7[0] * x7[0] + + x8[0] * x8[0] + x9[0] * x9[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1] + x6[1] * x6[1] + x7[1] * x7[1] + + x8[1] * x8[1] + x9[1] * x9[1]; + return true; + } +}; + +struct TenParameterBlockFunctor { + public: + template + bool operator()(const T* x1, const T* x2, const T* x3, const T* x4, + const T* x5, const T* x6, const T* x7, const T* x8, + const T* x9, const T* x10, T* residuals) const { + residuals[0] = x1[0] * x1[0] + x2[0] * x2[0] + x3[0] * x3[0] + + x4[0] * x4[0] + x5[0] * x5[0] + x6[0] * x6[0] + x7[0] * x7[0] + + x8[0] * x8[0] + x9[0] * x9[0] + x10[0] * x10[0]; + residuals[1] = x1[1] * x1[1] + x2[1] * x2[1] + x3[1] * x3[1] + + x4[1] * x4[1] + x5[1] * x5[1] + x6[1] * x6[1] + x7[1] * x7[1] + + x8[1] * x8[1] + x9[1] * x9[1] + x10[1] * x10[1]; + return true; + } +}; + +class DynamicTwoParameterBlockFunctor { + public: + template + bool operator()(T const* const* parameters, T* residuals) const { + for (int i = 0; i < 2; ++i) { + residuals[0] = parameters[i][0] * parameters[i][0]; + residuals[1] = parameters[i][1] * parameters[i][1]; + } + return true; + } +}; + +#define TEST_BODY(NAME) \ + TEST(CostFunctionToFunctor, NAME) { \ + scoped_ptr cost_function( \ + new AutoDiffCostFunction< \ + CostFunctionToFunctor<2, PARAMETER_BLOCK_SIZES >, \ + 2, PARAMETER_BLOCK_SIZES>(new CostFunctionToFunctor< \ + 2, PARAMETER_BLOCK_SIZES >( \ + new AutoDiffCostFunction< \ + NAME##Functor, 2, PARAMETER_BLOCK_SIZES >( \ + new NAME##Functor)))); \ + \ +scoped_ptr actual_cost_function( \ + new AutoDiffCostFunction( \ + new NAME##Functor)); \ +ExpectCostFunctionsAreEqual(*cost_function, *actual_cost_function); \ +} + +#define PARAMETER_BLOCK_SIZES 2 +TEST_BODY(OneParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2 +TEST_BODY(TwoParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2 +TEST_BODY(ThreeParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2 +TEST_BODY(FourParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2 +TEST_BODY(FiveParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2,2 +TEST_BODY(SixParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2,2,2 +TEST_BODY(SevenParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2,2,2,2 +TEST_BODY(EightParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2,2,2,2,2 +TEST_BODY(NineParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#define PARAMETER_BLOCK_SIZES 2,2,2,2,2,2,2,2,2,2 +TEST_BODY(TenParameterBlock) +#undef PARAMETER_BLOCK_SIZES + +#undef TEST_BODY + +TEST(CostFunctionToFunctor, DynamicNumberOfResiduals) { + scoped_ptr cost_function( + new AutoDiffCostFunction< + CostFunctionToFunctor, ceres::DYNAMIC, 2, 2>( + new CostFunctionToFunctor( + new AutoDiffCostFunction( + new TwoParameterBlockFunctor)), 2)); + + scoped_ptr actual_cost_function( + new AutoDiffCostFunction( + new TwoParameterBlockFunctor)); + ExpectCostFunctionsAreEqual(*cost_function, *actual_cost_function); +} + +TEST(CostFunctionToFunctor, DynamicCostFunctionToFunctor) { + DynamicAutoDiffCostFunction* + actual_cost_function( + new DynamicAutoDiffCostFunction( + new DynamicTwoParameterBlockFunctor)); + actual_cost_function->AddParameterBlock(2); + actual_cost_function->AddParameterBlock(2); + actual_cost_function->SetNumResiduals(2); + + DynamicAutoDiffCostFunction cost_function( + new DynamicCostFunctionToFunctor(actual_cost_function)); + cost_function.AddParameterBlock(2); + cost_function.AddParameterBlock(2); + cost_function.SetNumResiduals(2); + + ExpectCostFunctionsAreEqual(cost_function, *actual_cost_function); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/covariance.cc b/internal/ceres/covariance.cc new file mode 100644 index 0000000..cb280a3 --- /dev/null +++ b/internal/ceres/covariance.cc @@ -0,0 +1,99 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/covariance.h" + +#include +#include +#include "ceres/covariance_impl.h" +#include "ceres/problem.h" +#include "ceres/problem_impl.h" + +namespace ceres { + +using std::make_pair; +using std::pair; +using std::vector; + +Covariance::Covariance(const Covariance::Options& options) { + impl_.reset(new internal::CovarianceImpl(options)); +} + +Covariance::~Covariance() { +} + +bool Covariance::Compute( + const vector >& covariance_blocks, + Problem* problem) { + return impl_->Compute(covariance_blocks, problem->problem_impl_.get()); +} + +bool Covariance::Compute( + const vector& parameter_blocks, + Problem* problem) { + return impl_->Compute(parameter_blocks, problem->problem_impl_.get()); +} + +bool Covariance::GetCovarianceBlock(const double* parameter_block1, + const double* parameter_block2, + double* covariance_block) const { + return impl_->GetCovarianceBlockInTangentOrAmbientSpace(parameter_block1, + parameter_block2, + true, // ambient + covariance_block); +} + +bool Covariance::GetCovarianceBlockInTangentSpace( + const double* parameter_block1, + const double* parameter_block2, + double* covariance_block) const { + return impl_->GetCovarianceBlockInTangentOrAmbientSpace(parameter_block1, + parameter_block2, + false, // tangent + covariance_block); +} + +bool Covariance::GetCovarianceMatrix( + const vector& parameter_blocks, + double* covariance_matrix) { + return impl_->GetCovarianceMatrixInTangentOrAmbientSpace(parameter_blocks, + true, // ambient + covariance_matrix); +} + +bool Covariance::GetCovarianceMatrixInTangentSpace( + const std::vector& parameter_blocks, + double *covariance_matrix) { + return impl_->GetCovarianceMatrixInTangentOrAmbientSpace(parameter_blocks, + false, // tangent + covariance_matrix); +} + +} // namespace ceres diff --git a/internal/ceres/covariance_impl.cc b/internal/ceres/covariance_impl.cc new file mode 100644 index 0000000..1f594c1 --- /dev/null +++ b/internal/ceres/covariance_impl.cc @@ -0,0 +1,928 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/covariance_impl.h" + +#ifdef CERES_USE_OPENMP +#include +#endif + +#include +#include +#include +#include +#include +#include + +#include "Eigen/SparseCore" +#include "Eigen/SparseQR" +#include "Eigen/SVD" + +#include "ceres/collections_port.h" +#include "ceres/compressed_col_sparse_matrix_utils.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/covariance.h" +#include "ceres/crs_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/map_util.h" +#include "ceres/parameter_block.h" +#include "ceres/problem_impl.h" +#include "ceres/residual_block.h" +#include "ceres/suitesparse.h" +#include "ceres/wall_time.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::make_pair; +using std::map; +using std::pair; +using std::sort; +using std::swap; +using std::vector; + +typedef vector > CovarianceBlocks; + +CovarianceImpl::CovarianceImpl(const Covariance::Options& options) + : options_(options), + is_computed_(false), + is_valid_(false) { +#ifndef CERES_USE_OPENMP + if (options_.num_threads > 1) { + LOG(WARNING) + << "OpenMP support is not compiled into this binary; " + << "only options.num_threads = 1 is supported. Switching " + << "to single threaded mode."; + options_.num_threads = 1; + } +#endif + evaluate_options_.num_threads = options_.num_threads; + evaluate_options_.apply_loss_function = options_.apply_loss_function; +} + +CovarianceImpl::~CovarianceImpl() { +} + +template void CheckForDuplicates(vector blocks) { + sort(blocks.begin(), blocks.end()); + typename vector::iterator it = + std::adjacent_find(blocks.begin(), blocks.end()); + if (it != blocks.end()) { + // In case there are duplicates, we search for their location. + map > blocks_map; + for (int i = 0; i < blocks.size(); ++i) { + blocks_map[blocks[i]].push_back(i); + } + + std::ostringstream duplicates; + while (it != blocks.end()) { + duplicates << "("; + for (int i = 0; i < blocks_map[*it].size() - 1; ++i) { + duplicates << blocks_map[*it][i] << ", "; + } + duplicates << blocks_map[*it].back() << ")"; + it = std::adjacent_find(it + 1, blocks.end()); + if (it < blocks.end()) { + duplicates << " and "; + } + } + + LOG(FATAL) << "Covariance::Compute called with duplicate blocks at " + << "indices " << duplicates.str(); + } +} + +bool CovarianceImpl::Compute(const CovarianceBlocks& covariance_blocks, + ProblemImpl* problem) { + CheckForDuplicates >(covariance_blocks); + problem_ = problem; + parameter_block_to_row_index_.clear(); + covariance_matrix_.reset(NULL); + is_valid_ = (ComputeCovarianceSparsity(covariance_blocks, problem) && + ComputeCovarianceValues()); + is_computed_ = true; + return is_valid_; +} + +bool CovarianceImpl::Compute(const vector& parameter_blocks, + ProblemImpl* problem) { + CheckForDuplicates(parameter_blocks); + CovarianceBlocks covariance_blocks; + for (int i = 0; i < parameter_blocks.size(); ++i) { + for (int j = i; j < parameter_blocks.size(); ++j) { + covariance_blocks.push_back(make_pair(parameter_blocks[i], + parameter_blocks[j])); + } + } + + return Compute(covariance_blocks, problem); +} + +bool CovarianceImpl::GetCovarianceBlockInTangentOrAmbientSpace( + const double* original_parameter_block1, + const double* original_parameter_block2, + bool lift_covariance_to_ambient_space, + double* covariance_block) const { + CHECK(is_computed_) + << "Covariance::GetCovarianceBlock called before Covariance::Compute"; + CHECK(is_valid_) + << "Covariance::GetCovarianceBlock called when Covariance::Compute " + << "returned false."; + + // If either of the two parameter blocks is constant, then the + // covariance block is also zero. + if (constant_parameter_blocks_.count(original_parameter_block1) > 0 || + constant_parameter_blocks_.count(original_parameter_block2) > 0) { + const ProblemImpl::ParameterMap& parameter_map = problem_->parameter_map(); + ParameterBlock* block1 = + FindOrDie(parameter_map, + const_cast(original_parameter_block1)); + + ParameterBlock* block2 = + FindOrDie(parameter_map, + const_cast(original_parameter_block2)); + + const int block1_size = block1->Size(); + const int block2_size = block2->Size(); + const int block1_local_size = block1->LocalSize(); + const int block2_local_size = block2->LocalSize(); + if (!lift_covariance_to_ambient_space) { + MatrixRef(covariance_block, block1_local_size, block2_local_size) + .setZero(); + } else { + MatrixRef(covariance_block, block1_size, block2_size).setZero(); + } + return true; + } + + const double* parameter_block1 = original_parameter_block1; + const double* parameter_block2 = original_parameter_block2; + const bool transpose = parameter_block1 > parameter_block2; + if (transpose) { + swap(parameter_block1, parameter_block2); + } + + // Find where in the covariance matrix the block is located. + const int row_begin = + FindOrDie(parameter_block_to_row_index_, parameter_block1); + const int col_begin = + FindOrDie(parameter_block_to_row_index_, parameter_block2); + const int* rows = covariance_matrix_->rows(); + const int* cols = covariance_matrix_->cols(); + const int row_size = rows[row_begin + 1] - rows[row_begin]; + const int* cols_begin = cols + rows[row_begin]; + + // The only part that requires work is walking the compressed column + // vector to determine where the set of columns correspnding to the + // covariance block begin. + int offset = 0; + while (cols_begin[offset] != col_begin && offset < row_size) { + ++offset; + } + + if (offset == row_size) { + LOG(ERROR) << "Unable to find covariance block for " + << original_parameter_block1 << " " + << original_parameter_block2; + return false; + } + + const ProblemImpl::ParameterMap& parameter_map = problem_->parameter_map(); + ParameterBlock* block1 = + FindOrDie(parameter_map, const_cast(parameter_block1)); + ParameterBlock* block2 = + FindOrDie(parameter_map, const_cast(parameter_block2)); + const LocalParameterization* local_param1 = block1->local_parameterization(); + const LocalParameterization* local_param2 = block2->local_parameterization(); + const int block1_size = block1->Size(); + const int block1_local_size = block1->LocalSize(); + const int block2_size = block2->Size(); + const int block2_local_size = block2->LocalSize(); + + ConstMatrixRef cov(covariance_matrix_->values() + rows[row_begin], + block1_size, + row_size); + + // Fast path when there are no local parameterizations or if the + // user does not want it lifted to the ambient space. + if ((local_param1 == NULL && local_param2 == NULL) || + !lift_covariance_to_ambient_space) { + if (transpose) { + MatrixRef(covariance_block, block2_local_size, block1_local_size) = + cov.block(0, offset, block1_local_size, + block2_local_size).transpose(); + } else { + MatrixRef(covariance_block, block1_local_size, block2_local_size) = + cov.block(0, offset, block1_local_size, block2_local_size); + } + return true; + } + + // If local parameterizations are used then the covariance that has + // been computed is in the tangent space and it needs to be lifted + // back to the ambient space. + // + // This is given by the formula + // + // C'_12 = J_1 C_12 J_2' + // + // Where C_12 is the local tangent space covariance for parameter + // blocks 1 and 2. J_1 and J_2 are respectively the local to global + // jacobians for parameter blocks 1 and 2. + // + // See Result 5.11 on page 142 of Hartley & Zisserman (2nd Edition) + // for a proof. + // + // TODO(sameeragarwal): Add caching of local parameterization, so + // that they are computed just once per parameter block. + Matrix block1_jacobian(block1_size, block1_local_size); + if (local_param1 == NULL) { + block1_jacobian.setIdentity(); + } else { + local_param1->ComputeJacobian(parameter_block1, block1_jacobian.data()); + } + + Matrix block2_jacobian(block2_size, block2_local_size); + // Fast path if the user is requesting a diagonal block. + if (parameter_block1 == parameter_block2) { + block2_jacobian = block1_jacobian; + } else { + if (local_param2 == NULL) { + block2_jacobian.setIdentity(); + } else { + local_param2->ComputeJacobian(parameter_block2, block2_jacobian.data()); + } + } + + if (transpose) { + MatrixRef(covariance_block, block2_size, block1_size) = + block2_jacobian * + cov.block(0, offset, block1_local_size, block2_local_size).transpose() * + block1_jacobian.transpose(); + } else { + MatrixRef(covariance_block, block1_size, block2_size) = + block1_jacobian * + cov.block(0, offset, block1_local_size, block2_local_size) * + block2_jacobian.transpose(); + } + + return true; +} + +bool CovarianceImpl::GetCovarianceMatrixInTangentOrAmbientSpace( + const vector& parameters, + bool lift_covariance_to_ambient_space, + double* covariance_matrix) const { + CHECK(is_computed_) + << "Covariance::GetCovarianceMatrix called before Covariance::Compute"; + CHECK(is_valid_) + << "Covariance::GetCovarianceMatrix called when Covariance::Compute " + << "returned false."; + + const ProblemImpl::ParameterMap& parameter_map = problem_->parameter_map(); + // For OpenMP compatibility we need to define these vectors in advance + const int num_parameters = parameters.size(); + vector parameter_sizes; + vector cum_parameter_size; + parameter_sizes.reserve(num_parameters); + cum_parameter_size.resize(num_parameters + 1); + cum_parameter_size[0] = 0; + for (int i = 0; i < num_parameters; ++i) { + ParameterBlock* block = + FindOrDie(parameter_map, const_cast(parameters[i])); + if (lift_covariance_to_ambient_space) { + parameter_sizes.push_back(block->Size()); + } else { + parameter_sizes.push_back(block->LocalSize()); + } + } + std::partial_sum(parameter_sizes.begin(), parameter_sizes.end(), + cum_parameter_size.begin() + 1); + const int max_covariance_block_size = + *std::max_element(parameter_sizes.begin(), parameter_sizes.end()); + const int covariance_size = cum_parameter_size.back(); + + // Assemble the blocks in the covariance matrix. + MatrixRef covariance(covariance_matrix, covariance_size, covariance_size); + const int num_threads = options_.num_threads; + scoped_array workspace( + new double[num_threads * max_covariance_block_size * + max_covariance_block_size]); + + bool success = true; + +// The collapse() directive is only supported in OpenMP 3.0 and higher. OpenMP +// 3.0 was released in May 2008 (hence the version number). +#if _OPENMP >= 200805 +# pragma omp parallel for num_threads(num_threads) schedule(dynamic) collapse(2) +#else +# pragma omp parallel for num_threads(num_threads) schedule(dynamic) +#endif + for (int i = 0; i < num_parameters; ++i) { + for (int j = 0; j < num_parameters; ++j) { + // The second loop can't start from j = i for compatibility with OpenMP + // collapse command. The conditional serves as a workaround + if (j >= i) { + int covariance_row_idx = cum_parameter_size[i]; + int covariance_col_idx = cum_parameter_size[j]; + int size_i = parameter_sizes[i]; + int size_j = parameter_sizes[j]; +#ifdef CERES_USE_OPENMP + int thread_id = omp_get_thread_num(); +#else + int thread_id = 0; +#endif + double* covariance_block = + workspace.get() + + thread_id * max_covariance_block_size * max_covariance_block_size; + if (!GetCovarianceBlockInTangentOrAmbientSpace( + parameters[i], parameters[j], lift_covariance_to_ambient_space, + covariance_block)) { + success = false; + } + + covariance.block(covariance_row_idx, covariance_col_idx, + size_i, size_j) = + MatrixRef(covariance_block, size_i, size_j); + + if (i != j) { + covariance.block(covariance_col_idx, covariance_row_idx, + size_j, size_i) = + MatrixRef(covariance_block, size_i, size_j).transpose(); + + } + } + } + } + return success; +} + +// Determine the sparsity pattern of the covariance matrix based on +// the block pairs requested by the user. +bool CovarianceImpl::ComputeCovarianceSparsity( + const CovarianceBlocks& original_covariance_blocks, + ProblemImpl* problem) { + EventLogger event_logger("CovarianceImpl::ComputeCovarianceSparsity"); + + // Determine an ordering for the parameter block, by sorting the + // parameter blocks by their pointers. + vector all_parameter_blocks; + problem->GetParameterBlocks(&all_parameter_blocks); + const ProblemImpl::ParameterMap& parameter_map = problem->parameter_map(); + HashSet parameter_blocks_in_use; + vector residual_blocks; + problem->GetResidualBlocks(&residual_blocks); + + for (int i = 0; i < residual_blocks.size(); ++i) { + ResidualBlock* residual_block = residual_blocks[i]; + parameter_blocks_in_use.insert(residual_block->parameter_blocks(), + residual_block->parameter_blocks() + + residual_block->NumParameterBlocks()); + } + + constant_parameter_blocks_.clear(); + vector& active_parameter_blocks = + evaluate_options_.parameter_blocks; + active_parameter_blocks.clear(); + for (int i = 0; i < all_parameter_blocks.size(); ++i) { + double* parameter_block = all_parameter_blocks[i]; + ParameterBlock* block = FindOrDie(parameter_map, parameter_block); + if (!block->IsConstant() && (parameter_blocks_in_use.count(block) > 0)) { + active_parameter_blocks.push_back(parameter_block); + } else { + constant_parameter_blocks_.insert(parameter_block); + } + } + + std::sort(active_parameter_blocks.begin(), active_parameter_blocks.end()); + + // Compute the number of rows. Map each parameter block to the + // first row corresponding to it in the covariance matrix using the + // ordering of parameter blocks just constructed. + int num_rows = 0; + parameter_block_to_row_index_.clear(); + for (int i = 0; i < active_parameter_blocks.size(); ++i) { + double* parameter_block = active_parameter_blocks[i]; + const int parameter_block_size = + problem->ParameterBlockLocalSize(parameter_block); + parameter_block_to_row_index_[parameter_block] = num_rows; + num_rows += parameter_block_size; + } + + // Compute the number of non-zeros in the covariance matrix. Along + // the way flip any covariance blocks which are in the lower + // triangular part of the matrix. + int num_nonzeros = 0; + CovarianceBlocks covariance_blocks; + for (int i = 0; i < original_covariance_blocks.size(); ++i) { + const pair& block_pair = + original_covariance_blocks[i]; + if (constant_parameter_blocks_.count(block_pair.first) > 0 || + constant_parameter_blocks_.count(block_pair.second) > 0) { + continue; + } + + int index1 = FindOrDie(parameter_block_to_row_index_, block_pair.first); + int index2 = FindOrDie(parameter_block_to_row_index_, block_pair.second); + const int size1 = problem->ParameterBlockLocalSize(block_pair.first); + const int size2 = problem->ParameterBlockLocalSize(block_pair.second); + num_nonzeros += size1 * size2; + + // Make sure we are constructing a block upper triangular matrix. + if (index1 > index2) { + covariance_blocks.push_back(make_pair(block_pair.second, + block_pair.first)); + } else { + covariance_blocks.push_back(block_pair); + } + } + + if (covariance_blocks.size() == 0) { + VLOG(2) << "No non-zero covariance blocks found"; + covariance_matrix_.reset(NULL); + return true; + } + + // Sort the block pairs. As a consequence we get the covariance + // blocks as they will occur in the CompressedRowSparseMatrix that + // will store the covariance. + sort(covariance_blocks.begin(), covariance_blocks.end()); + + // Fill the sparsity pattern of the covariance matrix. + covariance_matrix_.reset( + new CompressedRowSparseMatrix(num_rows, num_rows, num_nonzeros)); + + int* rows = covariance_matrix_->mutable_rows(); + int* cols = covariance_matrix_->mutable_cols(); + + // Iterate over parameter blocks and in turn over the rows of the + // covariance matrix. For each parameter block, look in the upper + // triangular part of the covariance matrix to see if there are any + // blocks requested by the user. If this is the case then fill out a + // set of compressed rows corresponding to this parameter block. + // + // The key thing that makes this loop work is the fact that the + // row/columns of the covariance matrix are ordered by the pointer + // values of the parameter blocks. Thus iterating over the keys of + // parameter_block_to_row_index_ corresponds to iterating over the + // rows of the covariance matrix in order. + int i = 0; // index into covariance_blocks. + int cursor = 0; // index into the covariance matrix. + for (map::const_iterator it = + parameter_block_to_row_index_.begin(); + it != parameter_block_to_row_index_.end(); + ++it) { + const double* row_block = it->first; + const int row_block_size = problem->ParameterBlockLocalSize(row_block); + int row_begin = it->second; + + // Iterate over the covariance blocks contained in this row block + // and count the number of columns in this row block. + int num_col_blocks = 0; + int num_columns = 0; + for (int j = i; j < covariance_blocks.size(); ++j, ++num_col_blocks) { + const pair& block_pair = + covariance_blocks[j]; + if (block_pair.first != row_block) { + break; + } + num_columns += problem->ParameterBlockLocalSize(block_pair.second); + } + + // Fill out all the compressed rows for this parameter block. + for (int r = 0; r < row_block_size; ++r) { + rows[row_begin + r] = cursor; + for (int c = 0; c < num_col_blocks; ++c) { + const double* col_block = covariance_blocks[i + c].second; + const int col_block_size = problem->ParameterBlockLocalSize(col_block); + int col_begin = FindOrDie(parameter_block_to_row_index_, col_block); + for (int k = 0; k < col_block_size; ++k) { + cols[cursor++] = col_begin++; + } + } + } + + i+= num_col_blocks; + } + + rows[num_rows] = cursor; + return true; +} + +bool CovarianceImpl::ComputeCovarianceValues() { + if (options_.algorithm_type == DENSE_SVD) { + return ComputeCovarianceValuesUsingDenseSVD(); + } + + if (options_.algorithm_type == SPARSE_QR) { + if (options_.sparse_linear_algebra_library_type == EIGEN_SPARSE) { + return ComputeCovarianceValuesUsingEigenSparseQR(); + } + + if (options_.sparse_linear_algebra_library_type == SUITE_SPARSE) { +#if !defined(CERES_NO_SUITESPARSE) + return ComputeCovarianceValuesUsingSuiteSparseQR(); +#else + LOG(ERROR) << "SuiteSparse is required to use the SPARSE_QR algorithm " + << "with " + << "Covariance::Options::sparse_linear_algebra_library_type " + << "= SUITE_SPARSE."; + return false; +#endif + } + + LOG(ERROR) << "Unsupported " + << "Covariance::Options::sparse_linear_algebra_library_type " + << "= " + << SparseLinearAlgebraLibraryTypeToString( + options_.sparse_linear_algebra_library_type); + return false; + } + + LOG(ERROR) << "Unsupported Covariance::Options::algorithm_type = " + << CovarianceAlgorithmTypeToString(options_.algorithm_type); + return false; +} + +bool CovarianceImpl::ComputeCovarianceValuesUsingSuiteSparseQR() { + EventLogger event_logger( + "CovarianceImpl::ComputeCovarianceValuesUsingSparseQR"); + +#ifndef CERES_NO_SUITESPARSE + if (covariance_matrix_.get() == NULL) { + // Nothing to do, all zeros covariance matrix. + return true; + } + + CRSMatrix jacobian; + problem_->Evaluate(evaluate_options_, NULL, NULL, NULL, &jacobian); + event_logger.AddEvent("Evaluate"); + + // Construct a compressed column form of the Jacobian. + const int num_rows = jacobian.num_rows; + const int num_cols = jacobian.num_cols; + const int num_nonzeros = jacobian.values.size(); + + vector transpose_rows(num_cols + 1, 0); + vector transpose_cols(num_nonzeros, 0); + vector transpose_values(num_nonzeros, 0); + + for (int idx = 0; idx < num_nonzeros; ++idx) { + transpose_rows[jacobian.cols[idx] + 1] += 1; + } + + for (int i = 1; i < transpose_rows.size(); ++i) { + transpose_rows[i] += transpose_rows[i - 1]; + } + + for (int r = 0; r < num_rows; ++r) { + for (int idx = jacobian.rows[r]; idx < jacobian.rows[r + 1]; ++idx) { + const int c = jacobian.cols[idx]; + const int transpose_idx = transpose_rows[c]; + transpose_cols[transpose_idx] = r; + transpose_values[transpose_idx] = jacobian.values[idx]; + ++transpose_rows[c]; + } + } + + for (int i = transpose_rows.size() - 1; i > 0 ; --i) { + transpose_rows[i] = transpose_rows[i - 1]; + } + transpose_rows[0] = 0; + + cholmod_sparse cholmod_jacobian; + cholmod_jacobian.nrow = num_rows; + cholmod_jacobian.ncol = num_cols; + cholmod_jacobian.nzmax = num_nonzeros; + cholmod_jacobian.nz = NULL; + cholmod_jacobian.p = reinterpret_cast(&transpose_rows[0]); + cholmod_jacobian.i = reinterpret_cast(&transpose_cols[0]); + cholmod_jacobian.x = reinterpret_cast(&transpose_values[0]); + cholmod_jacobian.z = NULL; + cholmod_jacobian.stype = 0; // Matrix is not symmetric. + cholmod_jacobian.itype = CHOLMOD_LONG; + cholmod_jacobian.xtype = CHOLMOD_REAL; + cholmod_jacobian.dtype = CHOLMOD_DOUBLE; + cholmod_jacobian.sorted = 1; + cholmod_jacobian.packed = 1; + + cholmod_common cc; + cholmod_l_start(&cc); + + cholmod_sparse* R = NULL; + SuiteSparse_long* permutation = NULL; + + // Compute a Q-less QR factorization of the Jacobian. Since we are + // only interested in inverting J'J = R'R, we do not need Q. This + // saves memory and gives us R as a permuted compressed column + // sparse matrix. + // + // TODO(sameeragarwal): Currently the symbolic factorization and the + // numeric factorization is done at the same time, and this does not + // explicitly account for the block column and row structure in the + // matrix. When using AMD, we have observed in the past that + // computing the ordering with the block matrix is significantly + // more efficient, both in runtime as well as the quality of + // ordering computed. So, it maybe worth doing that analysis + // separately. + const SuiteSparse_long rank = + SuiteSparseQR(SPQR_ORDERING_BESTAMD, + SPQR_DEFAULT_TOL, + cholmod_jacobian.ncol, + &cholmod_jacobian, + &R, + &permutation, + &cc); + event_logger.AddEvent("Numeric Factorization"); + CHECK_NOTNULL(permutation); + CHECK_NOTNULL(R); + + if (rank < cholmod_jacobian.ncol) { + LOG(ERROR) << "Jacobian matrix is rank deficient. " + << "Number of columns: " << cholmod_jacobian.ncol + << " rank: " << rank; + free(permutation); + cholmod_l_free_sparse(&R, &cc); + cholmod_l_finish(&cc); + return false; + } + + vector inverse_permutation(num_cols); + for (SuiteSparse_long i = 0; i < num_cols; ++i) { + inverse_permutation[permutation[i]] = i; + } + + const int* rows = covariance_matrix_->rows(); + const int* cols = covariance_matrix_->cols(); + double* values = covariance_matrix_->mutable_values(); + + // The following loop exploits the fact that the i^th column of A^{-1} + // is given by the solution to the linear system + // + // A x = e_i + // + // where e_i is a vector with e(i) = 1 and all other entries zero. + // + // Since the covariance matrix is symmetric, the i^th row and column + // are equal. + const int num_threads = options_.num_threads; + scoped_array workspace(new double[num_threads * num_cols]); + +#pragma omp parallel for num_threads(num_threads) schedule(dynamic) + for (int r = 0; r < num_cols; ++r) { + const int row_begin = rows[r]; + const int row_end = rows[r + 1]; + if (row_end == row_begin) { + continue; + } + +# ifdef CERES_USE_OPENMP + int thread_id = omp_get_thread_num(); +# else + int thread_id = 0; +# endif + + double* solution = workspace.get() + thread_id * num_cols; + SolveRTRWithSparseRHS( + num_cols, + static_cast(R->i), + static_cast(R->p), + static_cast(R->x), + inverse_permutation[r], + solution); + for (int idx = row_begin; idx < row_end; ++idx) { + const int c = cols[idx]; + values[idx] = solution[inverse_permutation[c]]; + } + } + + free(permutation); + cholmod_l_free_sparse(&R, &cc); + cholmod_l_finish(&cc); + event_logger.AddEvent("Inversion"); + return true; + +#else // CERES_NO_SUITESPARSE + + return false; + +#endif // CERES_NO_SUITESPARSE +} + +bool CovarianceImpl::ComputeCovarianceValuesUsingDenseSVD() { + EventLogger event_logger( + "CovarianceImpl::ComputeCovarianceValuesUsingDenseSVD"); + if (covariance_matrix_.get() == NULL) { + // Nothing to do, all zeros covariance matrix. + return true; + } + + CRSMatrix jacobian; + problem_->Evaluate(evaluate_options_, NULL, NULL, NULL, &jacobian); + event_logger.AddEvent("Evaluate"); + + Matrix dense_jacobian(jacobian.num_rows, jacobian.num_cols); + dense_jacobian.setZero(); + for (int r = 0; r < jacobian.num_rows; ++r) { + for (int idx = jacobian.rows[r]; idx < jacobian.rows[r + 1]; ++idx) { + const int c = jacobian.cols[idx]; + dense_jacobian(r, c) = jacobian.values[idx]; + } + } + event_logger.AddEvent("ConvertToDenseMatrix"); + + Eigen::JacobiSVD svd(dense_jacobian, + Eigen::ComputeThinU | Eigen::ComputeThinV); + + event_logger.AddEvent("SingularValueDecomposition"); + + const Vector singular_values = svd.singularValues(); + const int num_singular_values = singular_values.rows(); + Vector inverse_squared_singular_values(num_singular_values); + inverse_squared_singular_values.setZero(); + + const double max_singular_value = singular_values[0]; + const double min_singular_value_ratio = + sqrt(options_.min_reciprocal_condition_number); + + const bool automatic_truncation = (options_.null_space_rank < 0); + const int max_rank = std::min(num_singular_values, + num_singular_values - options_.null_space_rank); + + // Compute the squared inverse of the singular values. Truncate the + // computation based on min_singular_value_ratio and + // null_space_rank. When either of these two quantities are active, + // the resulting covariance matrix is a Moore-Penrose inverse + // instead of a regular inverse. + for (int i = 0; i < max_rank; ++i) { + const double singular_value_ratio = singular_values[i] / max_singular_value; + if (singular_value_ratio < min_singular_value_ratio) { + // Since the singular values are in decreasing order, if + // automatic truncation is enabled, then from this point on + // all values will fail the ratio test and there is nothing to + // do in this loop. + if (automatic_truncation) { + break; + } else { + LOG(ERROR) << "Error: Covariance matrix is near rank deficient " + << "and the user did not specify a non-zero" + << "Covariance::Options::null_space_rank " + << "to enable the computation of a Pseudo-Inverse. " + << "Reciprocal condition number: " + << singular_value_ratio * singular_value_ratio << " " + << "min_reciprocal_condition_number: " + << options_.min_reciprocal_condition_number; + return false; + } + } + + inverse_squared_singular_values[i] = + 1.0 / (singular_values[i] * singular_values[i]); + } + + Matrix dense_covariance = + svd.matrixV() * + inverse_squared_singular_values.asDiagonal() * + svd.matrixV().transpose(); + event_logger.AddEvent("PseudoInverse"); + + const int num_rows = covariance_matrix_->num_rows(); + const int* rows = covariance_matrix_->rows(); + const int* cols = covariance_matrix_->cols(); + double* values = covariance_matrix_->mutable_values(); + + for (int r = 0; r < num_rows; ++r) { + for (int idx = rows[r]; idx < rows[r + 1]; ++idx) { + const int c = cols[idx]; + values[idx] = dense_covariance(r, c); + } + } + event_logger.AddEvent("CopyToCovarianceMatrix"); + return true; +} + +bool CovarianceImpl::ComputeCovarianceValuesUsingEigenSparseQR() { + EventLogger event_logger( + "CovarianceImpl::ComputeCovarianceValuesUsingEigenSparseQR"); + if (covariance_matrix_.get() == NULL) { + // Nothing to do, all zeros covariance matrix. + return true; + } + + CRSMatrix jacobian; + problem_->Evaluate(evaluate_options_, NULL, NULL, NULL, &jacobian); + event_logger.AddEvent("Evaluate"); + + typedef Eigen::SparseMatrix EigenSparseMatrix; + + // Convert the matrix to column major order as required by SparseQR. + EigenSparseMatrix sparse_jacobian = + Eigen::MappedSparseMatrix( + jacobian.num_rows, jacobian.num_cols, + static_cast(jacobian.values.size()), + jacobian.rows.data(), jacobian.cols.data(), jacobian.values.data()); + event_logger.AddEvent("ConvertToSparseMatrix"); + + Eigen::SparseQR > + qr_solver(sparse_jacobian); + event_logger.AddEvent("QRDecomposition"); + + if (qr_solver.info() != Eigen::Success) { + LOG(ERROR) << "Eigen::SparseQR decomposition failed."; + return false; + } + + if (qr_solver.rank() < jacobian.num_cols) { + LOG(ERROR) << "Jacobian matrix is rank deficient. " + << "Number of columns: " << jacobian.num_cols + << " rank: " << qr_solver.rank(); + return false; + } + + const int* rows = covariance_matrix_->rows(); + const int* cols = covariance_matrix_->cols(); + double* values = covariance_matrix_->mutable_values(); + + // Compute the inverse column permutation used by QR factorization. + Eigen::PermutationMatrix inverse_permutation = + qr_solver.colsPermutation().inverse(); + + // The following loop exploits the fact that the i^th column of A^{-1} + // is given by the solution to the linear system + // + // A x = e_i + // + // where e_i is a vector with e(i) = 1 and all other entries zero. + // + // Since the covariance matrix is symmetric, the i^th row and column + // are equal. + const int num_cols = jacobian.num_cols; + const int num_threads = options_.num_threads; + scoped_array workspace(new double[num_threads * num_cols]); + +#pragma omp parallel for num_threads(num_threads) schedule(dynamic) + for (int r = 0; r < num_cols; ++r) { + const int row_begin = rows[r]; + const int row_end = rows[r + 1]; + if (row_end == row_begin) { + continue; + } + +# ifdef CERES_USE_OPENMP + int thread_id = omp_get_thread_num(); +# else + int thread_id = 0; +# endif + + double* solution = workspace.get() + thread_id * num_cols; + SolveRTRWithSparseRHS( + num_cols, + qr_solver.matrixR().innerIndexPtr(), + qr_solver.matrixR().outerIndexPtr(), + &qr_solver.matrixR().data().value(0), + inverse_permutation.indices().coeff(r), + solution); + + // Assign the values of the computed covariance using the + // inverse permutation used in the QR factorization. + for (int idx = row_begin; idx < row_end; ++idx) { + const int c = cols[idx]; + values[idx] = solution[inverse_permutation.indices().coeff(c)]; + } + } + + event_logger.AddEvent("Inverse"); + + return true; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/covariance_impl.h b/internal/ceres/covariance_impl.h new file mode 100644 index 0000000..a3f0761 --- /dev/null +++ b/internal/ceres/covariance_impl.h @@ -0,0 +1,101 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_COVARIANCE_IMPL_H_ +#define CERES_INTERNAL_COVARIANCE_IMPL_H_ + +#include +#include +#include +#include +#include "ceres/covariance.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/problem_impl.h" +#include "ceres/suitesparse.h" + +namespace ceres { +namespace internal { + +class CompressedRowSparseMatrix; + +class CovarianceImpl { + public: + explicit CovarianceImpl(const Covariance::Options& options); + ~CovarianceImpl(); + + bool Compute( + const std::vector >& covariance_blocks, + ProblemImpl* problem); + + bool Compute( + const std::vector& parameter_blocks, + ProblemImpl* problem); + + bool GetCovarianceBlockInTangentOrAmbientSpace( + const double* parameter_block1, + const double* parameter_block2, + bool lift_covariance_to_ambient_space, + double* covariance_block) const; + + bool GetCovarianceMatrixInTangentOrAmbientSpace( + const std::vector& parameters, + bool lift_covariance_to_ambient_space, + double *covariance_matrix) const; + + bool ComputeCovarianceSparsity( + const std::vector >& covariance_blocks, + ProblemImpl* problem); + + bool ComputeCovarianceValues(); + bool ComputeCovarianceValuesUsingDenseSVD(); + bool ComputeCovarianceValuesUsingSuiteSparseQR(); + bool ComputeCovarianceValuesUsingEigenSparseQR(); + + const CompressedRowSparseMatrix* covariance_matrix() const { + return covariance_matrix_.get(); + } + + private: + ProblemImpl* problem_; + Covariance::Options options_; + Problem::EvaluateOptions evaluate_options_; + bool is_computed_; + bool is_valid_; + std::map parameter_block_to_row_index_; + std::set constant_parameter_blocks_; + scoped_ptr covariance_matrix_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_COVARIANCE_IMPL_H_ diff --git a/internal/ceres/covariance_test.cc b/internal/ceres/covariance_test.cc new file mode 100644 index 0000000..92a7626 --- /dev/null +++ b/internal/ceres/covariance_test.cc @@ -0,0 +1,1277 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/covariance.h" + +#include +#include +#include +#include +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/cost_function.h" +#include "ceres/covariance_impl.h" +#include "ceres/local_parameterization.h" +#include "ceres/map_util.h" +#include "ceres/problem_impl.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::make_pair; +using std::map; +using std::pair; +using std::vector; + +class UnaryCostFunction: public CostFunction { + public: + UnaryCostFunction(const int num_residuals, + const int32 parameter_block_size, + const double* jacobian) + : jacobian_(jacobian, jacobian + num_residuals * parameter_block_size) { + set_num_residuals(num_residuals); + mutable_parameter_block_sizes()->push_back(parameter_block_size); + } + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + for (int i = 0; i < num_residuals(); ++i) { + residuals[i] = 1; + } + + if (jacobians == NULL) { + return true; + } + + if (jacobians[0] != NULL) { + copy(jacobian_.begin(), jacobian_.end(), jacobians[0]); + } + + return true; + } + + private: + vector jacobian_; +}; + + +class BinaryCostFunction: public CostFunction { + public: + BinaryCostFunction(const int num_residuals, + const int32 parameter_block1_size, + const int32 parameter_block2_size, + const double* jacobian1, + const double* jacobian2) + : jacobian1_(jacobian1, + jacobian1 + num_residuals * parameter_block1_size), + jacobian2_(jacobian2, + jacobian2 + num_residuals * parameter_block2_size) { + set_num_residuals(num_residuals); + mutable_parameter_block_sizes()->push_back(parameter_block1_size); + mutable_parameter_block_sizes()->push_back(parameter_block2_size); + } + + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + for (int i = 0; i < num_residuals(); ++i) { + residuals[i] = 2; + } + + if (jacobians == NULL) { + return true; + } + + if (jacobians[0] != NULL) { + copy(jacobian1_.begin(), jacobian1_.end(), jacobians[0]); + } + + if (jacobians[1] != NULL) { + copy(jacobian2_.begin(), jacobian2_.end(), jacobians[1]); + } + + return true; + } + + private: + vector jacobian1_; + vector jacobian2_; +}; + +// x_plus_delta = delta * x; +class PolynomialParameterization : public LocalParameterization { + public: + virtual ~PolynomialParameterization() {} + + virtual bool Plus(const double* x, + const double* delta, + double* x_plus_delta) const { + x_plus_delta[0] = delta[0] * x[0]; + x_plus_delta[1] = delta[0] * x[1]; + return true; + } + + virtual bool ComputeJacobian(const double* x, double* jacobian) const { + jacobian[0] = x[0]; + jacobian[1] = x[1]; + return true; + } + + virtual int GlobalSize() const { return 2; } + virtual int LocalSize() const { return 1; } +}; + +TEST(CovarianceImpl, ComputeCovarianceSparsity) { + double parameters[10]; + + double* block1 = parameters; + double* block2 = block1 + 1; + double* block3 = block2 + 2; + double* block4 = block3 + 3; + + ProblemImpl problem; + + // Add in random order + Vector junk_jacobian = Vector::Zero(10); + problem.AddResidualBlock( + new UnaryCostFunction(1, 1, junk_jacobian.data()), NULL, block1); + problem.AddResidualBlock( + new UnaryCostFunction(1, 4, junk_jacobian.data()), NULL, block4); + problem.AddResidualBlock( + new UnaryCostFunction(1, 3, junk_jacobian.data()), NULL, block3); + problem.AddResidualBlock( + new UnaryCostFunction(1, 2, junk_jacobian.data()), NULL, block2); + + // Sparsity pattern + // + // Note that the problem structure does not imply this sparsity + // pattern since all the residual blocks are unary. But the + // ComputeCovarianceSparsity function in its current incarnation + // does not pay attention to this fact and only looks at the + // parameter block pairs that the user provides. + // + // X . . . . . X X X X + // . X X X X X . . . . + // . X X X X X . . . . + // . . . X X X . . . . + // . . . X X X . . . . + // . . . X X X . . . . + // . . . . . . X X X X + // . . . . . . X X X X + // . . . . . . X X X X + // . . . . . . X X X X + + int expected_rows[] = {0, 5, 10, 15, 18, 21, 24, 28, 32, 36, 40}; + int expected_cols[] = {0, 6, 7, 8, 9, + 1, 2, 3, 4, 5, + 1, 2, 3, 4, 5, + 3, 4, 5, + 3, 4, 5, + 3, 4, 5, + 6, 7, 8, 9, + 6, 7, 8, 9, + 6, 7, 8, 9, + 6, 7, 8, 9}; + + + vector > covariance_blocks; + covariance_blocks.push_back(make_pair(block1, block1)); + covariance_blocks.push_back(make_pair(block4, block4)); + covariance_blocks.push_back(make_pair(block2, block2)); + covariance_blocks.push_back(make_pair(block3, block3)); + covariance_blocks.push_back(make_pair(block2, block3)); + covariance_blocks.push_back(make_pair(block4, block1)); // reversed + + Covariance::Options options; + CovarianceImpl covariance_impl(options); + EXPECT_TRUE(covariance_impl + .ComputeCovarianceSparsity(covariance_blocks, &problem)); + + const CompressedRowSparseMatrix* crsm = covariance_impl.covariance_matrix(); + + EXPECT_EQ(crsm->num_rows(), 10); + EXPECT_EQ(crsm->num_cols(), 10); + EXPECT_EQ(crsm->num_nonzeros(), 40); + + const int* rows = crsm->rows(); + for (int r = 0; r < crsm->num_rows() + 1; ++r) { + EXPECT_EQ(rows[r], expected_rows[r]) + << r << " " + << rows[r] << " " + << expected_rows[r]; + } + + const int* cols = crsm->cols(); + for (int c = 0; c < crsm->num_nonzeros(); ++c) { + EXPECT_EQ(cols[c], expected_cols[c]) + << c << " " + << cols[c] << " " + << expected_cols[c]; + } +} + +TEST(CovarianceImpl, ComputeCovarianceSparsityWithConstantParameterBlock) { + double parameters[10]; + + double* block1 = parameters; + double* block2 = block1 + 1; + double* block3 = block2 + 2; + double* block4 = block3 + 3; + + ProblemImpl problem; + + // Add in random order + Vector junk_jacobian = Vector::Zero(10); + problem.AddResidualBlock( + new UnaryCostFunction(1, 1, junk_jacobian.data()), NULL, block1); + problem.AddResidualBlock( + new UnaryCostFunction(1, 4, junk_jacobian.data()), NULL, block4); + problem.AddResidualBlock( + new UnaryCostFunction(1, 3, junk_jacobian.data()), NULL, block3); + problem.AddResidualBlock( + new UnaryCostFunction(1, 2, junk_jacobian.data()), NULL, block2); + problem.SetParameterBlockConstant(block3); + + // Sparsity pattern + // + // Note that the problem structure does not imply this sparsity + // pattern since all the residual blocks are unary. But the + // ComputeCovarianceSparsity function in its current incarnation + // does not pay attention to this fact and only looks at the + // parameter block pairs that the user provides. + // + // X . . X X X X + // . X X . . . . + // . X X . . . . + // . . . X X X X + // . . . X X X X + // . . . X X X X + // . . . X X X X + + int expected_rows[] = {0, 5, 7, 9, 13, 17, 21, 25}; + int expected_cols[] = {0, 3, 4, 5, 6, + 1, 2, + 1, 2, + 3, 4, 5, 6, + 3, 4, 5, 6, + 3, 4, 5, 6, + 3, 4, 5, 6}; + + vector > covariance_blocks; + covariance_blocks.push_back(make_pair(block1, block1)); + covariance_blocks.push_back(make_pair(block4, block4)); + covariance_blocks.push_back(make_pair(block2, block2)); + covariance_blocks.push_back(make_pair(block3, block3)); + covariance_blocks.push_back(make_pair(block2, block3)); + covariance_blocks.push_back(make_pair(block4, block1)); // reversed + + Covariance::Options options; + CovarianceImpl covariance_impl(options); + EXPECT_TRUE(covariance_impl + .ComputeCovarianceSparsity(covariance_blocks, &problem)); + + const CompressedRowSparseMatrix* crsm = covariance_impl.covariance_matrix(); + + EXPECT_EQ(crsm->num_rows(), 7); + EXPECT_EQ(crsm->num_cols(), 7); + EXPECT_EQ(crsm->num_nonzeros(), 25); + + const int* rows = crsm->rows(); + for (int r = 0; r < crsm->num_rows() + 1; ++r) { + EXPECT_EQ(rows[r], expected_rows[r]) + << r << " " + << rows[r] << " " + << expected_rows[r]; + } + + const int* cols = crsm->cols(); + for (int c = 0; c < crsm->num_nonzeros(); ++c) { + EXPECT_EQ(cols[c], expected_cols[c]) + << c << " " + << cols[c] << " " + << expected_cols[c]; + } +} + +TEST(CovarianceImpl, ComputeCovarianceSparsityWithFreeParameterBlock) { + double parameters[10]; + + double* block1 = parameters; + double* block2 = block1 + 1; + double* block3 = block2 + 2; + double* block4 = block3 + 3; + + ProblemImpl problem; + + // Add in random order + Vector junk_jacobian = Vector::Zero(10); + problem.AddResidualBlock( + new UnaryCostFunction(1, 1, junk_jacobian.data()), NULL, block1); + problem.AddResidualBlock( + new UnaryCostFunction(1, 4, junk_jacobian.data()), NULL, block4); + problem.AddParameterBlock(block3, 3); + problem.AddResidualBlock( + new UnaryCostFunction(1, 2, junk_jacobian.data()), NULL, block2); + + // Sparsity pattern + // + // Note that the problem structure does not imply this sparsity + // pattern since all the residual blocks are unary. But the + // ComputeCovarianceSparsity function in its current incarnation + // does not pay attention to this fact and only looks at the + // parameter block pairs that the user provides. + // + // X . . X X X X + // . X X . . . . + // . X X . . . . + // . . . X X X X + // . . . X X X X + // . . . X X X X + // . . . X X X X + + int expected_rows[] = {0, 5, 7, 9, 13, 17, 21, 25}; + int expected_cols[] = {0, 3, 4, 5, 6, + 1, 2, + 1, 2, + 3, 4, 5, 6, + 3, 4, 5, 6, + 3, 4, 5, 6, + 3, 4, 5, 6}; + + vector > covariance_blocks; + covariance_blocks.push_back(make_pair(block1, block1)); + covariance_blocks.push_back(make_pair(block4, block4)); + covariance_blocks.push_back(make_pair(block2, block2)); + covariance_blocks.push_back(make_pair(block3, block3)); + covariance_blocks.push_back(make_pair(block2, block3)); + covariance_blocks.push_back(make_pair(block4, block1)); // reversed + + Covariance::Options options; + CovarianceImpl covariance_impl(options); + EXPECT_TRUE(covariance_impl + .ComputeCovarianceSparsity(covariance_blocks, &problem)); + + const CompressedRowSparseMatrix* crsm = covariance_impl.covariance_matrix(); + + EXPECT_EQ(crsm->num_rows(), 7); + EXPECT_EQ(crsm->num_cols(), 7); + EXPECT_EQ(crsm->num_nonzeros(), 25); + + const int* rows = crsm->rows(); + for (int r = 0; r < crsm->num_rows() + 1; ++r) { + EXPECT_EQ(rows[r], expected_rows[r]) + << r << " " + << rows[r] << " " + << expected_rows[r]; + } + + const int* cols = crsm->cols(); + for (int c = 0; c < crsm->num_nonzeros(); ++c) { + EXPECT_EQ(cols[c], expected_cols[c]) + << c << " " + << cols[c] << " " + << expected_cols[c]; + } +} + +class CovarianceTest : public ::testing::Test { + protected: + typedef map > BoundsMap; + + virtual void SetUp() { + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + + x[0] = 1; + x[1] = 1; + y[0] = 2; + y[1] = 2; + y[2] = 2; + z[0] = 3; + + { + double jacobian[] = { 1.0, 0.0, 0.0, 1.0}; + problem_.AddResidualBlock(new UnaryCostFunction(2, 2, jacobian), NULL, x); + } + + { + double jacobian[] = { 2.0, 0.0, 0.0, 0.0, 2.0, 0.0, 0.0, 0.0, 2.0 }; + problem_.AddResidualBlock(new UnaryCostFunction(3, 3, jacobian), NULL, y); + } + + { + double jacobian = 5.0; + problem_.AddResidualBlock(new UnaryCostFunction(1, 1, &jacobian), + NULL, + z); + } + + { + double jacobian1[] = { 1.0, 2.0, 3.0 }; + double jacobian2[] = { -5.0, -6.0 }; + problem_.AddResidualBlock( + new BinaryCostFunction(1, 3, 2, jacobian1, jacobian2), + NULL, + y, + x); + } + + { + double jacobian1[] = {2.0 }; + double jacobian2[] = { 3.0, -2.0 }; + problem_.AddResidualBlock( + new BinaryCostFunction(1, 1, 2, jacobian1, jacobian2), + NULL, + z, + x); + } + + all_covariance_blocks_.push_back(make_pair(x, x)); + all_covariance_blocks_.push_back(make_pair(y, y)); + all_covariance_blocks_.push_back(make_pair(z, z)); + all_covariance_blocks_.push_back(make_pair(x, y)); + all_covariance_blocks_.push_back(make_pair(x, z)); + all_covariance_blocks_.push_back(make_pair(y, z)); + + column_bounds_[x] = make_pair(0, 2); + column_bounds_[y] = make_pair(2, 5); + column_bounds_[z] = make_pair(5, 6); + } + + // Computes covariance in ambient space. + void ComputeAndCompareCovarianceBlocks(const Covariance::Options& options, + const double* expected_covariance) { + ComputeAndCompareCovarianceBlocksInTangentOrAmbientSpace( + options, + true, // ambient + expected_covariance); + } + + // Computes covariance in tangent space. + void ComputeAndCompareCovarianceBlocksInTangentSpace( + const Covariance::Options& options, + const double* expected_covariance) { + ComputeAndCompareCovarianceBlocksInTangentOrAmbientSpace( + options, + false, // tangent + expected_covariance); + } + + void ComputeAndCompareCovarianceBlocksInTangentOrAmbientSpace( + const Covariance::Options& options, + bool lift_covariance_to_ambient_space, + const double* expected_covariance) { + // Generate all possible combination of block pairs and check if the + // covariance computation is correct. + for (int i = 0; i <= 64; ++i) { + vector > covariance_blocks; + if (i & 1) { + covariance_blocks.push_back(all_covariance_blocks_[0]); + } + + if (i & 2) { + covariance_blocks.push_back(all_covariance_blocks_[1]); + } + + if (i & 4) { + covariance_blocks.push_back(all_covariance_blocks_[2]); + } + + if (i & 8) { + covariance_blocks.push_back(all_covariance_blocks_[3]); + } + + if (i & 16) { + covariance_blocks.push_back(all_covariance_blocks_[4]); + } + + if (i & 32) { + covariance_blocks.push_back(all_covariance_blocks_[5]); + } + + Covariance covariance(options); + EXPECT_TRUE(covariance.Compute(covariance_blocks, &problem_)); + + for (int i = 0; i < covariance_blocks.size(); ++i) { + const double* block1 = covariance_blocks[i].first; + const double* block2 = covariance_blocks[i].second; + // block1, block2 + GetCovarianceBlockAndCompare(block1, + block2, + lift_covariance_to_ambient_space, + covariance, + expected_covariance); + // block2, block1 + GetCovarianceBlockAndCompare(block2, + block1, + lift_covariance_to_ambient_space, + covariance, + expected_covariance); + } + } + } + + void GetCovarianceBlockAndCompare(const double* block1, + const double* block2, + bool lift_covariance_to_ambient_space, + const Covariance& covariance, + const double* expected_covariance) { + const BoundsMap& column_bounds = lift_covariance_to_ambient_space ? + column_bounds_ : local_column_bounds_; + const int row_begin = FindOrDie(column_bounds, block1).first; + const int row_end = FindOrDie(column_bounds, block1).second; + const int col_begin = FindOrDie(column_bounds, block2).first; + const int col_end = FindOrDie(column_bounds, block2).second; + + Matrix actual(row_end - row_begin, col_end - col_begin); + if (lift_covariance_to_ambient_space) { + EXPECT_TRUE(covariance.GetCovarianceBlock(block1, + block2, + actual.data())); + } else { + EXPECT_TRUE(covariance.GetCovarianceBlockInTangentSpace(block1, + block2, + actual.data())); + } + + int dof = 0; // degrees of freedom = sum of LocalSize()s + for (BoundsMap::const_iterator iter = column_bounds.begin(); + iter != column_bounds.end(); ++iter) { + dof = std::max(dof, iter->second.second); + } + ConstMatrixRef expected(expected_covariance, dof, dof); + double diff_norm = (expected.block(row_begin, + col_begin, + row_end - row_begin, + col_end - col_begin) - actual).norm(); + diff_norm /= (row_end - row_begin) * (col_end - col_begin); + + const double kTolerance = 1e-5; + EXPECT_NEAR(diff_norm, 0.0, kTolerance) + << "rows: " << row_begin << " " << row_end << " " + << "cols: " << col_begin << " " << col_end << " " + << "\n\n expected: \n " << expected.block(row_begin, + col_begin, + row_end - row_begin, + col_end - col_begin) + << "\n\n actual: \n " << actual + << "\n\n full expected: \n" << expected; + } + + double parameters_[6]; + Problem problem_; + vector > all_covariance_blocks_; + BoundsMap column_bounds_; + BoundsMap local_column_bounds_; +}; + + +TEST_F(CovarianceTest, NormalBehavior) { + // J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // J'J + // + // 35 24 -5 -10 -15 6 + // 24 41 -6 -12 -18 -4 + // -5 -6 5 2 3 0 + // -10 -12 2 8 6 0 + // -15 -18 3 6 13 0 + // 6 -4 0 0 0 29 + + // inv(J'J) computed using octave. + double expected_covariance[] = { + 7.0747e-02, -8.4923e-03, 1.6821e-02, 3.3643e-02, 5.0464e-02, -1.5809e-02, // NOLINT + -8.4923e-03, 8.1352e-02, 2.4758e-02, 4.9517e-02, 7.4275e-02, 1.2978e-02, // NOLINT + 1.6821e-02, 2.4758e-02, 2.4904e-01, -1.9271e-03, -2.8906e-03, -6.5325e-05, // NOLINT + 3.3643e-02, 4.9517e-02, -1.9271e-03, 2.4615e-01, -5.7813e-03, -1.3065e-04, // NOLINT + 5.0464e-02, 7.4275e-02, -2.8906e-03, -5.7813e-03, 2.4133e-01, -1.9598e-04, // NOLINT + -1.5809e-02, 1.2978e-02, -6.5325e-05, -1.3065e-04, -1.9598e-04, 3.9544e-02, // NOLINT + }; + + Covariance::Options options; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +#ifdef CERES_USE_OPENMP + +TEST_F(CovarianceTest, ThreadedNormalBehavior) { + // J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // J'J + // + // 35 24 -5 -10 -15 6 + // 24 41 -6 -12 -18 -4 + // -5 -6 5 2 3 0 + // -10 -12 2 8 6 0 + // -15 -18 3 6 13 0 + // 6 -4 0 0 0 29 + + // inv(J'J) computed using octave. + double expected_covariance[] = { + 7.0747e-02, -8.4923e-03, 1.6821e-02, 3.3643e-02, 5.0464e-02, -1.5809e-02, // NOLINT + -8.4923e-03, 8.1352e-02, 2.4758e-02, 4.9517e-02, 7.4275e-02, 1.2978e-02, // NOLINT + 1.6821e-02, 2.4758e-02, 2.4904e-01, -1.9271e-03, -2.8906e-03, -6.5325e-05, // NOLINT + 3.3643e-02, 4.9517e-02, -1.9271e-03, 2.4615e-01, -5.7813e-03, -1.3065e-04, // NOLINT + 5.0464e-02, 7.4275e-02, -2.8906e-03, -5.7813e-03, 2.4133e-01, -1.9598e-04, // NOLINT + -1.5809e-02, 1.2978e-02, -6.5325e-05, -1.3065e-04, -1.9598e-04, 3.9544e-02, // NOLINT + }; + + Covariance::Options options; + options.num_threads = 4; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +#endif // CERES_USE_OPENMP + +TEST_F(CovarianceTest, ConstantParameterBlock) { + problem_.SetParameterBlockConstant(parameters_); + + // J + // + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // 0 0 1 2 3 0 + // 0 0 0 0 0 2 + + // J'J + // + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 5 2 3 0 + // 0 0 2 8 6 0 + // 0 0 3 6 13 0 + // 0 0 0 0 0 29 + + // pinv(J'J) computed using octave. + double expected_covariance[] = { + 0, 0, 0, 0, 0, 0, // NOLINT + 0, 0, 0, 0, 0, 0, // NOLINT + 0, 0, 0.23611, -0.02778, -0.04167, -0.00000, // NOLINT + 0, 0, -0.02778, 0.19444, -0.08333, -0.00000, // NOLINT + 0, 0, -0.04167, -0.08333, 0.12500, -0.00000, // NOLINT + 0, 0, -0.00000, -0.00000, -0.00000, 0.03448 // NOLINT + }; + + Covariance::Options options; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +TEST_F(CovarianceTest, LocalParameterization) { + double* x = parameters_; + double* y = x + 2; + + problem_.SetParameterization(x, new PolynomialParameterization); + + vector subset; + subset.push_back(2); + problem_.SetParameterization(y, new SubsetParameterization(3, subset)); + + // Raw Jacobian: J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // Local to global jacobian: A + // + // 1 0 0 0 + // 1 0 0 0 + // 0 1 0 0 + // 0 0 1 0 + // 0 0 0 0 + // 0 0 0 1 + + // A * inv((J*A)'*(J*A)) * A' + // Computed using octave. + double expected_covariance[] = { + 0.01766, 0.01766, 0.02158, 0.04316, 0.00000, -0.00122, + 0.01766, 0.01766, 0.02158, 0.04316, 0.00000, -0.00122, + 0.02158, 0.02158, 0.24860, -0.00281, 0.00000, -0.00149, + 0.04316, 0.04316, -0.00281, 0.24439, 0.00000, -0.00298, + 0.00000, 0.00000, 0.00000, 0.00000, 0.00000, 0.00000, + -0.00122, -0.00122, -0.00149, -0.00298, 0.00000, 0.03457 + }; + + Covariance::Options options; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +TEST_F(CovarianceTest, LocalParameterizationInTangentSpace) { + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + + problem_.SetParameterization(x, new PolynomialParameterization); + + vector subset; + subset.push_back(2); + problem_.SetParameterization(y, new SubsetParameterization(3, subset)); + + local_column_bounds_[x] = make_pair(0, 1); + local_column_bounds_[y] = make_pair(1, 3); + local_column_bounds_[z] = make_pair(3, 4); + + // Raw Jacobian: J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // Local to global jacobian: A + // + // 1 0 0 0 + // 1 0 0 0 + // 0 1 0 0 + // 0 0 1 0 + // 0 0 0 0 + // 0 0 0 1 + + // inv((J*A)'*(J*A)) + // Computed using octave. + double expected_covariance[] = { + 0.01766, 0.02158, 0.04316, -0.00122, + 0.02158, 0.24860, -0.00281, -0.00149, + 0.04316, -0.00281, 0.24439, -0.00298, + -0.00122, -0.00149, -0.00298, 0.03457 // NOLINT + }; + + Covariance::Options options; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +} + +TEST_F(CovarianceTest, LocalParameterizationInTangentSpaceWithConstantBlocks) { + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + + problem_.SetParameterization(x, new PolynomialParameterization); + problem_.SetParameterBlockConstant(x); + + vector subset; + subset.push_back(2); + problem_.SetParameterization(y, new SubsetParameterization(3, subset)); + problem_.SetParameterBlockConstant(y); + + local_column_bounds_[x] = make_pair(0, 1); + local_column_bounds_[y] = make_pair(1, 3); + local_column_bounds_[z] = make_pair(3, 4); + + // Raw Jacobian: J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // Local to global jacobian: A + // + // 0 0 0 0 + // 0 0 0 0 + // 0 0 0 0 + // 0 0 0 0 + // 0 0 0 0 + // 0 0 0 1 + + // pinv((J*A)'*(J*A)) + // Computed using octave. + double expected_covariance[] = { + 0.0, 0.0, 0.0, 0.0, + 0.0, 0.0, 0.0, 0.0, + 0.0, 0.0, 0.0, 0.0, + 0.0, 0.0, 0.0, 0.034482 // NOLINT + }; + + Covariance::Options options; + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +} + +TEST_F(CovarianceTest, TruncatedRank) { + // J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 2 0 0 0 + // 0 0 0 2 0 0 + // 0 0 0 0 2 0 + // 0 0 0 0 0 5 + // -5 -6 1 2 3 0 + // 3 -2 0 0 0 2 + + // J'J + // + // 35 24 -5 -10 -15 6 + // 24 41 -6 -12 -18 -4 + // -5 -6 5 2 3 0 + // -10 -12 2 8 6 0 + // -15 -18 3 6 13 0 + // 6 -4 0 0 0 29 + + // 3.4142 is the smallest eigen value of J'J. The following matrix + // was obtained by dropping the eigenvector corresponding to this + // eigenvalue. + double expected_covariance[] = { + 5.4135e-02, -3.5121e-02, 1.7257e-04, 3.4514e-04, 5.1771e-04, -1.6076e-02, // NOLINT + -3.5121e-02, 3.8667e-02, -1.9288e-03, -3.8576e-03, -5.7864e-03, 1.2549e-02, // NOLINT + 1.7257e-04, -1.9288e-03, 2.3235e-01, -3.5297e-02, -5.2946e-02, -3.3329e-04, // NOLINT + 3.4514e-04, -3.8576e-03, -3.5297e-02, 1.7941e-01, -1.0589e-01, -6.6659e-04, // NOLINT + 5.1771e-04, -5.7864e-03, -5.2946e-02, -1.0589e-01, 9.1162e-02, -9.9988e-04, // NOLINT + -1.6076e-02, 1.2549e-02, -3.3329e-04, -6.6659e-04, -9.9988e-04, 3.9539e-02 // NOLINT + }; + + + { + Covariance::Options options; + options.algorithm_type = DENSE_SVD; + // Force dropping of the smallest eigenvector. + options.null_space_rank = 1; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + } + + { + Covariance::Options options; + options.algorithm_type = DENSE_SVD; + // Force dropping of the smallest eigenvector via the ratio but + // automatic truncation. + options.min_reciprocal_condition_number = 0.044494; + options.null_space_rank = -1; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + } +} + +TEST_F(CovarianceTest, DenseCovarianceMatrixFromSetOfParameters) { + Covariance::Options options; + Covariance covariance(options); + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + vector parameter_blocks; + parameter_blocks.push_back(x); + parameter_blocks.push_back(y); + parameter_blocks.push_back(z); + covariance.Compute(parameter_blocks, &problem_); + double expected_covariance[36]; + covariance.GetCovarianceMatrix(parameter_blocks, expected_covariance); + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +TEST_F(CovarianceTest, DenseCovarianceMatrixFromSetOfParametersThreaded) { + Covariance::Options options; + options.num_threads = 4; + Covariance covariance(options); + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + vector parameter_blocks; + parameter_blocks.push_back(x); + parameter_blocks.push_back(y); + parameter_blocks.push_back(z); + covariance.Compute(parameter_blocks, &problem_); + double expected_covariance[36]; + covariance.GetCovarianceMatrix(parameter_blocks, expected_covariance); + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +TEST_F(CovarianceTest, DenseCovarianceMatrixFromSetOfParametersInTangentSpace) { + Covariance::Options options; + Covariance covariance(options); + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + + problem_.SetParameterization(x, new PolynomialParameterization); + + vector subset; + subset.push_back(2); + problem_.SetParameterization(y, new SubsetParameterization(3, subset)); + + local_column_bounds_[x] = make_pair(0, 1); + local_column_bounds_[y] = make_pair(1, 3); + local_column_bounds_[z] = make_pair(3, 4); + + vector parameter_blocks; + parameter_blocks.push_back(x); + parameter_blocks.push_back(y); + parameter_blocks.push_back(z); + covariance.Compute(parameter_blocks, &problem_); + double expected_covariance[16]; + covariance.GetCovarianceMatrixInTangentSpace(parameter_blocks, + expected_covariance); + +#ifndef CERES_NO_SUITESPARSE + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; + + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +#endif + + options.algorithm_type = DENSE_SVD; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + options.sparse_linear_algebra_library_type = EIGEN_SPARSE; + ComputeAndCompareCovarianceBlocksInTangentSpace(options, expected_covariance); +} + +TEST_F(CovarianceTest, ComputeCovarianceFailure) { + Covariance::Options options; + Covariance covariance(options); + double* x = parameters_; + double* y = x + 2; + vector parameter_blocks; + parameter_blocks.push_back(x); + parameter_blocks.push_back(x); + parameter_blocks.push_back(y); + parameter_blocks.push_back(y); + EXPECT_DEATH_IF_SUPPORTED(covariance.Compute(parameter_blocks, &problem_), + "Covariance::Compute called with duplicate blocks " + "at indices \\(0, 1\\) and \\(2, 3\\)"); + vector > covariance_blocks; + covariance_blocks.push_back(make_pair(x, x)); + covariance_blocks.push_back(make_pair(x, x)); + covariance_blocks.push_back(make_pair(y, y)); + covariance_blocks.push_back(make_pair(y, y)); + EXPECT_DEATH_IF_SUPPORTED(covariance.Compute(covariance_blocks, &problem_), + "Covariance::Compute called with duplicate blocks " + "at indices \\(0, 1\\) and \\(2, 3\\)"); +} + +class RankDeficientCovarianceTest : public CovarianceTest { + protected: + virtual void SetUp() { + double* x = parameters_; + double* y = x + 2; + double* z = y + 3; + + { + double jacobian[] = { 1.0, 0.0, 0.0, 1.0}; + problem_.AddResidualBlock(new UnaryCostFunction(2, 2, jacobian), NULL, x); + } + + { + double jacobian[] = { 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 }; + problem_.AddResidualBlock(new UnaryCostFunction(3, 3, jacobian), NULL, y); + } + + { + double jacobian = 5.0; + problem_.AddResidualBlock(new UnaryCostFunction(1, 1, &jacobian), + NULL, + z); + } + + { + double jacobian1[] = { 0.0, 0.0, 0.0 }; + double jacobian2[] = { -5.0, -6.0 }; + problem_.AddResidualBlock( + new BinaryCostFunction(1, 3, 2, jacobian1, jacobian2), + NULL, + y, + x); + } + + { + double jacobian1[] = {2.0 }; + double jacobian2[] = { 3.0, -2.0 }; + problem_.AddResidualBlock( + new BinaryCostFunction(1, 1, 2, jacobian1, jacobian2), + NULL, + z, + x); + } + + all_covariance_blocks_.push_back(make_pair(x, x)); + all_covariance_blocks_.push_back(make_pair(y, y)); + all_covariance_blocks_.push_back(make_pair(z, z)); + all_covariance_blocks_.push_back(make_pair(x, y)); + all_covariance_blocks_.push_back(make_pair(x, z)); + all_covariance_blocks_.push_back(make_pair(y, z)); + + column_bounds_[x] = make_pair(0, 2); + column_bounds_[y] = make_pair(2, 5); + column_bounds_[z] = make_pair(5, 6); + } +}; + +TEST_F(RankDeficientCovarianceTest, AutomaticTruncation) { + // J + // + // 1 0 0 0 0 0 + // 0 1 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 0 0 0 5 + // -5 -6 0 0 0 0 + // 3 -2 0 0 0 2 + + // J'J + // + // 35 24 0 0 0 6 + // 24 41 0 0 0 -4 + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 0 0 0 0 0 0 + // 6 -4 0 0 0 29 + + // pinv(J'J) computed using octave. + double expected_covariance[] = { + 0.053998, -0.033145, 0.000000, 0.000000, 0.000000, -0.015744, + -0.033145, 0.045067, 0.000000, 0.000000, 0.000000, 0.013074, + 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, + 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, + 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, 0.000000, + -0.015744, 0.013074, 0.000000, 0.000000, 0.000000, 0.039543 + }; + + Covariance::Options options; + options.algorithm_type = DENSE_SVD; + options.null_space_rank = -1; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); +} + +class LargeScaleCovarianceTest : public ::testing::Test { + protected: + virtual void SetUp() { + num_parameter_blocks_ = 2000; + parameter_block_size_ = 5; + parameters_.reset( + new double[parameter_block_size_ * num_parameter_blocks_]); + + Matrix jacobian(parameter_block_size_, parameter_block_size_); + for (int i = 0; i < num_parameter_blocks_; ++i) { + jacobian.setIdentity(); + jacobian *= (i + 1); + + double* block_i = parameters_.get() + i * parameter_block_size_; + problem_.AddResidualBlock(new UnaryCostFunction(parameter_block_size_, + parameter_block_size_, + jacobian.data()), + NULL, + block_i); + for (int j = i; j < num_parameter_blocks_; ++j) { + double* block_j = parameters_.get() + j * parameter_block_size_; + all_covariance_blocks_.push_back(make_pair(block_i, block_j)); + } + } + } + + void ComputeAndCompare( + CovarianceAlgorithmType algorithm_type, + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type, + int num_threads) { + Covariance::Options options; + options.algorithm_type = algorithm_type; + options.sparse_linear_algebra_library_type = + sparse_linear_algebra_library_type; + options.num_threads = num_threads; + Covariance covariance(options); + EXPECT_TRUE(covariance.Compute(all_covariance_blocks_, &problem_)); + + Matrix expected(parameter_block_size_, parameter_block_size_); + Matrix actual(parameter_block_size_, parameter_block_size_); + const double kTolerance = 1e-16; + + for (int i = 0; i < num_parameter_blocks_; ++i) { + expected.setIdentity(); + expected /= (i + 1.0) * (i + 1.0); + + double* block_i = parameters_.get() + i * parameter_block_size_; + covariance.GetCovarianceBlock(block_i, block_i, actual.data()); + EXPECT_NEAR((expected - actual).norm(), 0.0, kTolerance) + << "block: " << i << ", " << i << "\n" + << "expected: \n" << expected << "\n" + << "actual: \n" << actual; + + expected.setZero(); + for (int j = i + 1; j < num_parameter_blocks_; ++j) { + double* block_j = parameters_.get() + j * parameter_block_size_; + covariance.GetCovarianceBlock(block_i, block_j, actual.data()); + EXPECT_NEAR((expected - actual).norm(), 0.0, kTolerance) + << "block: " << i << ", " << j << "\n" + << "expected: \n" << expected << "\n" + << "actual: \n" << actual; + } + } + } + + scoped_array parameters_; + int parameter_block_size_; + int num_parameter_blocks_; + + Problem problem_; + vector > all_covariance_blocks_; +}; + +#if !defined(CERES_NO_SUITESPARSE) && defined(CERES_USE_OPENMP) + +TEST_F(LargeScaleCovarianceTest, Parallel) { + ComputeAndCompare(SPARSE_QR, SUITE_SPARSE, 4); +} + +#endif // !defined(CERES_NO_SUITESPARSE) && defined(CERES_USE_OPENMP) + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/cubic_interpolation_test.cc b/internal/ceres/cubic_interpolation_test.cc new file mode 100644 index 0000000..df43696 --- /dev/null +++ b/internal/ceres/cubic_interpolation_test.cc @@ -0,0 +1,510 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/cubic_interpolation.h" + +#include "ceres/jet.h" +#include "ceres/internal/scoped_ptr.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +static const double kTolerance = 1e-12; + +TEST(Grid1D, OneDataDimension) { + int x[] = {1, 2, 3}; + Grid1D grid(x, 0, 3); + for (int i = 0; i < 3; ++i) { + double value; + grid.GetValue(i, &value); + EXPECT_EQ(value, static_cast(i + 1)); + } +} + +TEST(Grid1D, OneDataDimensionOutOfBounds) { + int x[] = {1, 2, 3}; + Grid1D grid(x, 0, 3); + double value; + grid.GetValue(-1, &value); + EXPECT_EQ(value, x[0]); + grid.GetValue(-2, &value); + EXPECT_EQ(value, x[0]); + grid.GetValue(3, &value); + EXPECT_EQ(value, x[2]); + grid.GetValue(4, &value); + EXPECT_EQ(value, x[2]); +} + +TEST(Grid1D, TwoDataDimensionIntegerDataInterleaved) { + int x[] = {1, 5, + 2, 6, + 3, 7}; + + Grid1D grid(x, 0, 3); + for (int i = 0; i < 3; ++i) { + double value[2]; + grid.GetValue(i, value); + EXPECT_EQ(value[0], static_cast(i + 1)); + EXPECT_EQ(value[1], static_cast(i + 5)); + } +} + + +TEST(Grid1D, TwoDataDimensionIntegerDataStacked) { + int x[] = {1, 2, 3, + 5, 6, 7}; + + Grid1D grid(x, 0, 3); + for (int i = 0; i < 3; ++i) { + double value[2]; + grid.GetValue(i, value); + EXPECT_EQ(value[0], static_cast(i + 1)); + EXPECT_EQ(value[1], static_cast(i + 5)); + } +} + +TEST(Grid2D, OneDataDimensionRowMajor) { + int x[] = {1, 2, 3, + 2, 3, 4}; + Grid2D grid(x, 0, 2, 0, 3); + for (int r = 0; r < 2; ++r) { + for (int c = 0; c < 3; ++c) { + double value; + grid.GetValue(r, c, &value); + EXPECT_EQ(value, static_cast(r + c + 1)); + } + } +} + +TEST(Grid2D, OneDataDimensionRowMajorOutOfBounds) { + int x[] = {1, 2, 3, + 2, 3, 4}; + Grid2D grid(x, 0, 2, 0, 3); + double value; + grid.GetValue(-1, -1, &value); + EXPECT_EQ(value, x[0]); + grid.GetValue(-1, 0, &value); + EXPECT_EQ(value, x[0]); + grid.GetValue(-1, 1, &value); + EXPECT_EQ(value, x[1]); + grid.GetValue(-1, 2, &value); + EXPECT_EQ(value, x[2]); + grid.GetValue(-1, 3, &value); + EXPECT_EQ(value, x[2]); + grid.GetValue(0, 3, &value); + EXPECT_EQ(value, x[2]); + grid.GetValue(1, 3, &value); + EXPECT_EQ(value, x[5]); + grid.GetValue(2, 3, &value); + EXPECT_EQ(value, x[5]); + grid.GetValue(2, 2, &value); + EXPECT_EQ(value, x[5]); + grid.GetValue(2, 1, &value); + EXPECT_EQ(value, x[4]); + grid.GetValue(2, 0, &value); + EXPECT_EQ(value, x[3]); + grid.GetValue(2, -1, &value); + EXPECT_EQ(value, x[3]); + grid.GetValue(1, -1, &value); + EXPECT_EQ(value, x[3]); + grid.GetValue(0, -1, &value); + EXPECT_EQ(value, x[0]); +} + +TEST(Grid2D, TwoDataDimensionRowMajorInterleaved) { + int x[] = {1, 4, 2, 8, 3, 12, + 2, 8, 3, 12, 4, 16}; + Grid2D grid(x, 0, 2, 0, 3); + for (int r = 0; r < 2; ++r) { + for (int c = 0; c < 3; ++c) { + double value[2]; + grid.GetValue(r, c, value); + EXPECT_EQ(value[0], static_cast(r + c + 1)); + EXPECT_EQ(value[1], static_cast(4 *(r + c + 1))); + } + } +} + +TEST(Grid2D, TwoDataDimensionRowMajorStacked) { + int x[] = {1, 2, 3, + 2, 3, 4, + 4, 8, 12, + 8, 12, 16}; + Grid2D grid(x, 0, 2, 0, 3); + for (int r = 0; r < 2; ++r) { + for (int c = 0; c < 3; ++c) { + double value[2]; + grid.GetValue(r, c, value); + EXPECT_EQ(value[0], static_cast(r + c + 1)); + EXPECT_EQ(value[1], static_cast(4 *(r + c + 1))); + } + } +} + +TEST(Grid2D, TwoDataDimensionColMajorInterleaved) { + int x[] = { 1, 4, 2, 8, + 2, 8, 3, 12, + 3, 12, 4, 16}; + Grid2D grid(x, 0, 2, 0, 3); + for (int r = 0; r < 2; ++r) { + for (int c = 0; c < 3; ++c) { + double value[2]; + grid.GetValue(r, c, value); + EXPECT_EQ(value[0], static_cast(r + c + 1)); + EXPECT_EQ(value[1], static_cast(4 *(r + c + 1))); + } + } +} + +TEST(Grid2D, TwoDataDimensionColMajorStacked) { + int x[] = {1, 2, + 2, 3, + 3, 4, + 4, 8, + 8, 12, + 12, 16}; + Grid2D grid(x, 0, 2, 0, 3); + for (int r = 0; r < 2; ++r) { + for (int c = 0; c < 3; ++c) { + double value[2]; + grid.GetValue(r, c, value); + EXPECT_EQ(value[0], static_cast(r + c + 1)); + EXPECT_EQ(value[1], static_cast(4 *(r + c + 1))); + } + } +} + +class CubicInterpolatorTest : public ::testing::Test { + public: + template + void RunPolynomialInterpolationTest(const double a, + const double b, + const double c, + const double d) { + values_.reset(new double[kDataDimension * kNumSamples]); + + for (int x = 0; x < kNumSamples; ++x) { + for (int dim = 0; dim < kDataDimension; ++dim) { + values_[x * kDataDimension + dim] = + (dim * dim + 1) * (a * x * x * x + b * x * x + c * x + d); + } + } + + Grid1D grid(values_.get(), 0, kNumSamples); + CubicInterpolator > interpolator(grid); + + // Check values in the all the cells but the first and the last + // ones. In these cells, the interpolated function values should + // match exactly the values of the function being interpolated. + // + // On the boundary, we extrapolate the values of the function on + // the basis of its first derivative, so we do not expect the + // function values and its derivatives not to match. + for (int j = 0; j < kNumTestSamples; ++j) { + const double x = 1.0 + 7.0 / (kNumTestSamples - 1) * j; + double expected_f[kDataDimension], expected_dfdx[kDataDimension]; + double f[kDataDimension], dfdx[kDataDimension]; + + for (int dim = 0; dim < kDataDimension; ++dim) { + expected_f[dim] = + (dim * dim + 1) * (a * x * x * x + b * x * x + c * x + d); + expected_dfdx[dim] = (dim * dim + 1) * (3.0 * a * x * x + 2.0 * b * x + c); + } + + interpolator.Evaluate(x, f, dfdx); + for (int dim = 0; dim < kDataDimension; ++dim) { + EXPECT_NEAR(f[dim], expected_f[dim], kTolerance) + << "x: " << x << " dim: " << dim + << " actual f(x): " << expected_f[dim] + << " estimated f(x): " << f[dim]; + EXPECT_NEAR(dfdx[dim], expected_dfdx[dim], kTolerance) + << "x: " << x << " dim: " << dim + << " actual df(x)/dx: " << expected_dfdx[dim] + << " estimated df(x)/dx: " << dfdx[dim]; + } + } + } + + private: + static const int kNumSamples = 10; + static const int kNumTestSamples = 100; + scoped_array values_; +}; + +TEST_F(CubicInterpolatorTest, ConstantFunction) { + RunPolynomialInterpolationTest<1>(0.0, 0.0, 0.0, 0.5); + RunPolynomialInterpolationTest<2>(0.0, 0.0, 0.0, 0.5); + RunPolynomialInterpolationTest<3>(0.0, 0.0, 0.0, 0.5); +} + +TEST_F(CubicInterpolatorTest, LinearFunction) { + RunPolynomialInterpolationTest<1>(0.0, 0.0, 1.0, 0.5); + RunPolynomialInterpolationTest<2>(0.0, 0.0, 1.0, 0.5); + RunPolynomialInterpolationTest<3>(0.0, 0.0, 1.0, 0.5); +} + +TEST_F(CubicInterpolatorTest, QuadraticFunction) { + RunPolynomialInterpolationTest<1>(0.0, 0.4, 1.0, 0.5); + RunPolynomialInterpolationTest<2>(0.0, 0.4, 1.0, 0.5); + RunPolynomialInterpolationTest<3>(0.0, 0.4, 1.0, 0.5); +} + + +TEST(CubicInterpolator, JetEvaluation) { + const double values[] = {1.0, 2.0, 2.0, 5.0, 3.0, 9.0, 2.0, 7.0}; + + Grid1D grid(values, 0, 4); + CubicInterpolator > interpolator(grid); + + double f[2], dfdx[2]; + const double x = 2.5; + interpolator.Evaluate(x, f, dfdx); + + // Create a Jet with the same scalar part as x, so that the output + // Jet will be evaluated at x. + Jet x_jet; + x_jet.a = x; + x_jet.v(0) = 1.0; + x_jet.v(1) = 1.1; + x_jet.v(2) = 1.2; + x_jet.v(3) = 1.3; + + Jet f_jets[2]; + interpolator.Evaluate(x_jet, f_jets); + + // Check that the scalar part of the Jet is f(x). + EXPECT_EQ(f_jets[0].a, f[0]); + EXPECT_EQ(f_jets[1].a, f[1]); + + // Check that the derivative part of the Jet is dfdx * x_jet.v + // by the chain rule. + EXPECT_NEAR((f_jets[0].v - dfdx[0] * x_jet.v).norm(), 0.0, kTolerance); + EXPECT_NEAR((f_jets[1].v - dfdx[1] * x_jet.v).norm(), 0.0, kTolerance); +} + +class BiCubicInterpolatorTest : public ::testing::Test { + public: + template + void RunPolynomialInterpolationTest(const Eigen::Matrix3d& coeff) { + values_.reset(new double[kNumRows * kNumCols * kDataDimension]); + coeff_ = coeff; + double* v = values_.get(); + for (int r = 0; r < kNumRows; ++r) { + for (int c = 0; c < kNumCols; ++c) { + for (int dim = 0; dim < kDataDimension; ++dim) { + *v++ = (dim * dim + 1) * EvaluateF(r, c); + } + } + } + + Grid2D grid(values_.get(), 0, kNumRows, 0, kNumCols); + BiCubicInterpolator > interpolator(grid); + + for (int j = 0; j < kNumRowSamples; ++j) { + const double r = 1.0 + 7.0 / (kNumRowSamples - 1) * j; + for (int k = 0; k < kNumColSamples; ++k) { + const double c = 1.0 + 7.0 / (kNumColSamples - 1) * k; + double f[kDataDimension], dfdr[kDataDimension], dfdc[kDataDimension]; + interpolator.Evaluate(r, c, f, dfdr, dfdc); + for (int dim = 0; dim < kDataDimension; ++dim) { + EXPECT_NEAR(f[dim], (dim * dim + 1) * EvaluateF(r, c), kTolerance); + EXPECT_NEAR(dfdr[dim], (dim * dim + 1) * EvaluatedFdr(r, c), kTolerance); + EXPECT_NEAR(dfdc[dim], (dim * dim + 1) * EvaluatedFdc(r, c), kTolerance); + } + } + } + } + + private: + double EvaluateF(double r, double c) { + Eigen::Vector3d x; + x(0) = r; + x(1) = c; + x(2) = 1; + return x.transpose() * coeff_ * x; + } + + double EvaluatedFdr(double r, double c) { + Eigen::Vector3d x; + x(0) = r; + x(1) = c; + x(2) = 1; + return (coeff_.row(0) + coeff_.col(0).transpose()) * x; + } + + double EvaluatedFdc(double r, double c) { + Eigen::Vector3d x; + x(0) = r; + x(1) = c; + x(2) = 1; + return (coeff_.row(1) + coeff_.col(1).transpose()) * x; + } + + + Eigen::Matrix3d coeff_; + static const int kNumRows = 10; + static const int kNumCols = 10; + static const int kNumRowSamples = 100; + static const int kNumColSamples = 100; + scoped_array values_; +}; + +TEST_F(BiCubicInterpolatorTest, ZeroFunction) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree00Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree01Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 2) = 0.1; + coeff(2, 0) = 0.1; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree10Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 1) = 0.1; + coeff(1, 0) = 0.1; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree11Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 1) = 0.1; + coeff(1, 0) = 0.1; + coeff(0, 2) = 0.2; + coeff(2, 0) = 0.2; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree12Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 1) = 0.1; + coeff(1, 0) = 0.1; + coeff(0, 2) = 0.2; + coeff(2, 0) = 0.2; + coeff(1, 1) = 0.3; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree21Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 1) = 0.1; + coeff(1, 0) = 0.1; + coeff(0, 2) = 0.2; + coeff(2, 0) = 0.2; + coeff(0, 0) = 0.3; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST_F(BiCubicInterpolatorTest, Degree22Function) { + Eigen::Matrix3d coeff = Eigen::Matrix3d::Zero(); + coeff(2, 2) = 1.0; + coeff(0, 1) = 0.1; + coeff(1, 0) = 0.1; + coeff(0, 2) = 0.2; + coeff(2, 0) = 0.2; + coeff(0, 0) = 0.3; + coeff(0, 1) = -0.4; + coeff(1, 0) = -0.4; + RunPolynomialInterpolationTest<1>(coeff); + RunPolynomialInterpolationTest<2>(coeff); + RunPolynomialInterpolationTest<3>(coeff); +} + +TEST(BiCubicInterpolator, JetEvaluation) { + const double values[] = {1.0, 5.0, 2.0, 10.0, 2.0, 6.0, 3.0, 5.0, + 1.0, 2.0, 2.0, 2.0, 2.0, 2.0, 3.0, 1.0}; + + Grid2D grid(values, 0, 2, 0, 4); + BiCubicInterpolator > interpolator(grid); + + double f[2], dfdr[2], dfdc[2]; + const double r = 0.5; + const double c = 2.5; + interpolator.Evaluate(r, c, f, dfdr, dfdc); + + // Create a Jet with the same scalar part as x, so that the output + // Jet will be evaluated at x. + Jet r_jet; + r_jet.a = r; + r_jet.v(0) = 1.0; + r_jet.v(1) = 1.1; + r_jet.v(2) = 1.2; + r_jet.v(3) = 1.3; + + Jet c_jet; + c_jet.a = c; + c_jet.v(0) = 2.0; + c_jet.v(1) = 3.1; + c_jet.v(2) = 4.2; + c_jet.v(3) = 5.3; + + Jet f_jets[2]; + interpolator.Evaluate(r_jet, c_jet, f_jets); + EXPECT_EQ(f_jets[0].a, f[0]); + EXPECT_EQ(f_jets[1].a, f[1]); + EXPECT_NEAR((f_jets[0].v - dfdr[0] * r_jet.v - dfdc[0] * c_jet.v).norm(), + 0.0, + kTolerance); + EXPECT_NEAR((f_jets[1].v - dfdr[1] * r_jet.v - dfdc[1] * c_jet.v).norm(), + 0.0, + kTolerance); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/cxsparse.cc b/internal/ceres/cxsparse.cc new file mode 100644 index 0000000..11ff943 --- /dev/null +++ b/internal/ceres/cxsparse.cc @@ -0,0 +1,283 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_NO_CXSPARSE + +#include "ceres/cxsparse.h" + +#include +#include + +#include "ceres/compressed_col_sparse_matrix_utils.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/triplet_sparse_matrix.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::vector; + +CXSparse::CXSparse() : scratch_(NULL), scratch_size_(0) {} + +CXSparse::~CXSparse() { + if (scratch_size_ > 0) { + cs_di_free(scratch_); + } +} + +csn* CXSparse::Cholesky(cs_di* A, cs_dis* symbolic_factor) { + return cs_di_chol(A, symbolic_factor); +} + +void CXSparse::Solve(cs_dis* symbolic_factor, csn* numeric_factor, double* b) { + // Make sure we have enough scratch space available. + const int num_cols = numeric_factor->L->n; + if (scratch_size_ < num_cols) { + if (scratch_size_ > 0) { + cs_di_free(scratch_); + } + scratch_ = + reinterpret_cast(cs_di_malloc(num_cols, sizeof(CS_ENTRY))); + scratch_size_ = num_cols; + } + + // When the Cholesky factor succeeded, these methods are + // guaranteed to succeeded as well. In the comments below, "x" + // refers to the scratch space. + // + // Set x = P * b. + CHECK(cs_di_ipvec(symbolic_factor->pinv, b, scratch_, num_cols)); + // Set x = L \ x. + CHECK(cs_di_lsolve(numeric_factor->L, scratch_)); + // Set x = L' \ x. + CHECK(cs_di_ltsolve(numeric_factor->L, scratch_)); + // Set b = P' * x. + CHECK(cs_di_pvec(symbolic_factor->pinv, scratch_, b, num_cols)); +} + +bool CXSparse::SolveCholesky(cs_di* lhs, double* rhs_and_solution) { + return cs_cholsol(1, lhs, rhs_and_solution); +} + +cs_dis* CXSparse::AnalyzeCholesky(cs_di* A) { + // order = 1 for Cholesky factor. + return cs_schol(1, A); +} + +cs_dis* CXSparse::AnalyzeCholeskyWithNaturalOrdering(cs_di* A) { + // order = 0 for Natural ordering. + return cs_schol(0, A); +} + +cs_dis* CXSparse::BlockAnalyzeCholesky(cs_di* A, + const vector& row_blocks, + const vector& col_blocks) { + const int num_row_blocks = row_blocks.size(); + const int num_col_blocks = col_blocks.size(); + + vector block_rows; + vector block_cols; + CompressedColumnScalarMatrixToBlockMatrix( + A->i, A->p, row_blocks, col_blocks, &block_rows, &block_cols); + cs_di block_matrix; + block_matrix.m = num_row_blocks; + block_matrix.n = num_col_blocks; + block_matrix.nz = -1; + block_matrix.nzmax = block_rows.size(); + block_matrix.p = &block_cols[0]; + block_matrix.i = &block_rows[0]; + block_matrix.x = NULL; + + int* ordering = cs_amd(1, &block_matrix); + vector block_ordering(num_row_blocks, -1); + std::copy(ordering, ordering + num_row_blocks, &block_ordering[0]); + cs_free(ordering); + + vector scalar_ordering; + BlockOrderingToScalarOrdering(row_blocks, block_ordering, &scalar_ordering); + + cs_dis* symbolic_factor = + reinterpret_cast(cs_calloc(1, sizeof(cs_dis))); + symbolic_factor->pinv = cs_pinv(&scalar_ordering[0], A->n); + cs* permuted_A = cs_symperm(A, symbolic_factor->pinv, 0); + + symbolic_factor->parent = cs_etree(permuted_A, 0); + int* postordering = cs_post(symbolic_factor->parent, A->n); + int* column_counts = + cs_counts(permuted_A, symbolic_factor->parent, postordering, 0); + cs_free(postordering); + cs_spfree(permuted_A); + + symbolic_factor->cp = (int*)cs_malloc(A->n + 1, sizeof(int)); + symbolic_factor->lnz = cs_cumsum(symbolic_factor->cp, column_counts, A->n); + symbolic_factor->unz = symbolic_factor->lnz; + + cs_free(column_counts); + + if (symbolic_factor->lnz < 0) { + cs_sfree(symbolic_factor); + symbolic_factor = NULL; + } + + return symbolic_factor; +} + +cs_di CXSparse::CreateSparseMatrixTransposeView(CompressedRowSparseMatrix* A) { + cs_di At; + At.m = A->num_cols(); + At.n = A->num_rows(); + At.nz = -1; + At.nzmax = A->num_nonzeros(); + At.p = A->mutable_rows(); + At.i = A->mutable_cols(); + At.x = A->mutable_values(); + return At; +} + +cs_di* CXSparse::CreateSparseMatrix(TripletSparseMatrix* tsm) { + cs_di_sparse tsm_wrapper; + tsm_wrapper.nzmax = tsm->num_nonzeros(); + tsm_wrapper.nz = tsm->num_nonzeros(); + tsm_wrapper.m = tsm->num_rows(); + tsm_wrapper.n = tsm->num_cols(); + tsm_wrapper.p = tsm->mutable_cols(); + tsm_wrapper.i = tsm->mutable_rows(); + tsm_wrapper.x = tsm->mutable_values(); + + return cs_compress(&tsm_wrapper); +} + +void CXSparse::ApproximateMinimumDegreeOrdering(cs_di* A, int* ordering) { + int* cs_ordering = cs_amd(1, A); + std::copy(cs_ordering, cs_ordering + A->m, ordering); + cs_free(cs_ordering); +} + +cs_di* CXSparse::TransposeMatrix(cs_di* A) { return cs_di_transpose(A, 1); } + +cs_di* CXSparse::MatrixMatrixMultiply(cs_di* A, cs_di* B) { + return cs_di_multiply(A, B); +} + +void CXSparse::Free(cs_di* sparse_matrix) { cs_di_spfree(sparse_matrix); } + +void CXSparse::Free(cs_dis* symbolic_factor) { cs_di_sfree(symbolic_factor); } + +void CXSparse::Free(csn* numeric_factor) { cs_di_nfree(numeric_factor); } + +CXSparseCholesky* CXSparseCholesky::Create(const OrderingType ordering_type) { + return new CXSparseCholesky(ordering_type); +} + +CompressedRowSparseMatrix::StorageType CXSparseCholesky::StorageType() const { + return CompressedRowSparseMatrix::LOWER_TRIANGULAR; +} + +CXSparseCholesky::CXSparseCholesky(const OrderingType ordering_type) + : ordering_type_(ordering_type), + symbolic_factor_(NULL), + numeric_factor_(NULL) {} + +CXSparseCholesky::~CXSparseCholesky() { + FreeSymbolicFactorization(); + FreeNumericFactorization(); +} + +LinearSolverTerminationType CXSparseCholesky::Factorize( + CompressedRowSparseMatrix* lhs, std::string* message) { + CHECK_EQ(lhs->storage_type(), StorageType()); + if (lhs == NULL) { + *message = "Failure: Input lhs is NULL."; + return LINEAR_SOLVER_FATAL_ERROR; + } + + cs_di cs_lhs = cs_.CreateSparseMatrixTransposeView(lhs); + + if (symbolic_factor_ == NULL) { + if (ordering_type_ == NATURAL) { + symbolic_factor_ = cs_.AnalyzeCholeskyWithNaturalOrdering(&cs_lhs); + } else { + if (!lhs->col_blocks().empty() && !(lhs->row_blocks().empty())) { + symbolic_factor_ = cs_.BlockAnalyzeCholesky( + &cs_lhs, lhs->col_blocks(), lhs->row_blocks()); + } else { + symbolic_factor_ = cs_.AnalyzeCholesky(&cs_lhs); + } + } + + if (symbolic_factor_ == NULL) { + *message = "CXSparse Failure : Symbolic factorization failed."; + return LINEAR_SOLVER_FATAL_ERROR; + } + } + + FreeNumericFactorization(); + numeric_factor_ = cs_.Cholesky(&cs_lhs, symbolic_factor_); + if (numeric_factor_ == NULL) { + *message = "CXSparse Failure : Numeric factorization failed."; + return LINEAR_SOLVER_FAILURE; + } + + return LINEAR_SOLVER_SUCCESS; +} + +LinearSolverTerminationType CXSparseCholesky::Solve(const double* rhs, + double* solution, + std::string* message) { + CHECK(numeric_factor_ != NULL) + << "Solve called without a call to Factorize first."; + const int num_cols = numeric_factor_->L->n; + memcpy(solution, rhs, num_cols * sizeof(*solution)); + cs_.Solve(symbolic_factor_, numeric_factor_, solution); + return LINEAR_SOLVER_SUCCESS; +} + +void CXSparseCholesky::FreeSymbolicFactorization() { + if (symbolic_factor_ != NULL) { + cs_.Free(symbolic_factor_); + symbolic_factor_ = NULL; + } +} + +void CXSparseCholesky::FreeNumericFactorization() { + if (numeric_factor_ != NULL) { + cs_.Free(numeric_factor_); + numeric_factor_ = NULL; + } +} + +} // namespace internal +} // namespace ceres + +#endif // CERES_NO_CXSPARSE diff --git a/internal/ceres/cxsparse.h b/internal/ceres/cxsparse.h new file mode 100644 index 0000000..1ad79f9 --- /dev/null +++ b/internal/ceres/cxsparse.h @@ -0,0 +1,178 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: strandmark@google.com (Petter Strandmark) + +#ifndef CERES_INTERNAL_CXSPARSE_H_ +#define CERES_INTERNAL_CXSPARSE_H_ + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_NO_CXSPARSE + +#include +#include + +#include "ceres/linear_solver.h" +#include "ceres/sparse_cholesky.h" +#include "cs.h" + +namespace ceres { +namespace internal { + +class CompressedRowSparseMatrix; +class TripletSparseMatrix; + +// This object provides access to solving linear systems using Cholesky +// factorization with a known symbolic factorization. This features does not +// explicity exist in CXSparse. The methods in the class are nonstatic because +// the class manages internal scratch space. +class CXSparse { + public: + CXSparse(); + ~CXSparse(); + + // Solve the system lhs * solution = rhs in place by using an + // approximate minimum degree fill reducing ordering. + bool SolveCholesky(cs_di* lhs, double* rhs_and_solution); + + // Solves a linear system given its symbolic and numeric factorization. + void Solve(cs_dis* symbolic_factor, + csn* numeric_factor, + double* rhs_and_solution); + + // Compute the numeric Cholesky factorization of A, given its + // symbolic factorization. + // + // Caller owns the result. + csn* Cholesky(cs_di* A, cs_dis* symbolic_factor); + + // Creates a sparse matrix from a compressed-column form. No memory is + // allocated or copied; the structure A is filled out with info from the + // argument. + cs_di CreateSparseMatrixTransposeView(CompressedRowSparseMatrix* A); + + // Creates a new matrix from a triplet form. Deallocate the returned matrix + // with Free. May return NULL if the compression or allocation fails. + cs_di* CreateSparseMatrix(TripletSparseMatrix* A); + + // B = A' + // + // The returned matrix should be deallocated with Free when not used + // anymore. + cs_di* TransposeMatrix(cs_di* A); + + // C = A * B + // + // The returned matrix should be deallocated with Free when not used + // anymore. + cs_di* MatrixMatrixMultiply(cs_di* A, cs_di* B); + + // Computes a symbolic factorization of A that can be used in SolveCholesky. + // + // The returned matrix should be deallocated with Free when not used anymore. + cs_dis* AnalyzeCholesky(cs_di* A); + + // Computes a symbolic factorization of A that can be used in + // SolveCholesky, but does not compute a fill-reducing ordering. + // + // The returned matrix should be deallocated with Free when not used anymore. + cs_dis* AnalyzeCholeskyWithNaturalOrdering(cs_di* A); + + // Computes a symbolic factorization of A that can be used in + // SolveCholesky. The difference from AnalyzeCholesky is that this + // function first detects the block sparsity of the matrix using + // information about the row and column blocks and uses this block + // sparse matrix to find a fill-reducing ordering. This ordering is + // then used to find a symbolic factorization. This can result in a + // significant performance improvement AnalyzeCholesky on block + // sparse matrices. + // + // The returned matrix should be deallocated with Free when not used + // anymore. + cs_dis* BlockAnalyzeCholesky(cs_di* A, + const std::vector& row_blocks, + const std::vector& col_blocks); + + // Compute an fill-reducing approximate minimum degree ordering of + // the matrix A. ordering should be non-NULL and should point to + // enough memory to hold the ordering for the rows of A. + void ApproximateMinimumDegreeOrdering(cs_di* A, int* ordering); + + void Free(cs_di* sparse_matrix); + void Free(cs_dis* symbolic_factorization); + void Free(csn* numeric_factorization); + + private: + // Cached scratch space + CS_ENTRY* scratch_; + int scratch_size_; +}; + +// An implementation of SparseCholesky interface using the CXSparse +// library. +class CXSparseCholesky : public SparseCholesky { + public: + // Factory + static CXSparseCholesky* Create(const OrderingType ordering_type); + + // SparseCholesky interface. + virtual ~CXSparseCholesky(); + virtual CompressedRowSparseMatrix::StorageType StorageType() const; + virtual LinearSolverTerminationType Factorize(CompressedRowSparseMatrix* lhs, + std::string* message); + virtual LinearSolverTerminationType Solve(const double* rhs, + double* solution, + std::string* message); + + private: + CXSparseCholesky(const OrderingType ordering_type); + void FreeSymbolicFactorization(); + void FreeNumericFactorization(); + + const OrderingType ordering_type_; + CXSparse cs_; + cs_dis* symbolic_factor_; + csn* numeric_factor_; +}; + +} // namespace internal +} // namespace ceres + +#else // CERES_NO_CXSPARSE + +typedef void cs_dis; + +class CXSparse { + public: + void Free(void* arg) {} +}; +#endif // CERES_NO_CXSPARSE + +#endif // CERES_INTERNAL_CXSPARSE_H_ diff --git a/internal/ceres/dense_jacobian_writer.h b/internal/ceres/dense_jacobian_writer.h new file mode 100644 index 0000000..1b04f38 --- /dev/null +++ b/internal/ceres/dense_jacobian_writer.h @@ -0,0 +1,108 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A jacobian writer that writes to dense Eigen matrices. + +#ifndef CERES_INTERNAL_DENSE_JACOBIAN_WRITER_H_ +#define CERES_INTERNAL_DENSE_JACOBIAN_WRITER_H_ + +#include "ceres/casts.h" +#include "ceres/dense_sparse_matrix.h" +#include "ceres/parameter_block.h" +#include "ceres/program.h" +#include "ceres/residual_block.h" +#include "ceres/scratch_evaluate_preparer.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +class DenseJacobianWriter { + public: + DenseJacobianWriter(Evaluator::Options /* ignored */, + Program* program) + : program_(program) { + } + + // JacobianWriter interface. + + // Since the dense matrix has different layout than that assumed by the cost + // functions, use scratch space to store the jacobians temporarily then copy + // them over to the larger jacobian later. + ScratchEvaluatePreparer* CreateEvaluatePreparers(int num_threads) { + return ScratchEvaluatePreparer::Create(*program_, num_threads); + } + + SparseMatrix* CreateJacobian() const { + return new DenseSparseMatrix(program_->NumResiduals(), + program_->NumEffectiveParameters(), + true); + } + + void Write(int residual_id, + int residual_offset, + double **jacobians, + SparseMatrix* jacobian) { + DenseSparseMatrix* dense_jacobian = down_cast(jacobian); + const ResidualBlock* residual_block = + program_->residual_blocks()[residual_id]; + int num_parameter_blocks = residual_block->NumParameterBlocks(); + int num_residuals = residual_block->NumResiduals(); + + // Now copy the jacobians for each parameter into the dense jacobian matrix. + for (int j = 0; j < num_parameter_blocks; ++j) { + ParameterBlock* parameter_block = residual_block->parameter_blocks()[j]; + + // If the parameter block is fixed, then there is nothing to do. + if (parameter_block->IsConstant()) { + continue; + } + + const int parameter_block_size = parameter_block->LocalSize(); + ConstMatrixRef parameter_jacobian(jacobians[j], + num_residuals, + parameter_block_size); + + dense_jacobian->mutable_matrix().block( + residual_offset, + parameter_block->delta_offset(), + num_residuals, + parameter_block_size) = parameter_jacobian; + } + } + + private: + Program* program_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DENSE_JACOBIAN_WRITER_H_ diff --git a/internal/ceres/dense_linear_solver_test.cc b/internal/ceres/dense_linear_solver_test.cc new file mode 100644 index 0000000..48da2bd --- /dev/null +++ b/internal/ceres/dense_linear_solver_test.cc @@ -0,0 +1,134 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/casts.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/linear_solver.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/types.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +typedef ::testing:: + tuple + Param; + +std::string ParamInfoToString(testing::TestParamInfo info) { + Param param = info.param; + std::stringstream ss; + ss << LinearSolverTypeToString(::testing::get<0>(param)) << "_" + << DenseLinearAlgebraLibraryTypeToString(::testing::get<1>(param)) << "_" + << (::testing::get<2>(param) ? "Regularized" : "Unregularized") << "_" + << ::testing::get<3>(param); + return ss.str(); +} + +class DenseLinearSolverTest : public ::testing::TestWithParam {}; + +TEST_P(DenseLinearSolverTest, _) { + Param param = GetParam(); + const bool regularized = testing::get<2>(param); + + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(testing::get<3>(param))); + DenseSparseMatrix lhs(*down_cast(problem->A.get())); + + const int num_cols = lhs.num_cols(); + const int num_rows = lhs.num_rows(); + + Vector rhs = Vector::Zero(num_rows + num_cols); + rhs.head(num_rows) = ConstVectorRef(problem->b.get(), num_rows); + + LinearSolver::Options options; + options.type = ::testing::get<0>(param); + options.dense_linear_algebra_library_type = ::testing::get<1>(param); + scoped_ptr solver(LinearSolver::Create(options)); + + LinearSolver::PerSolveOptions per_solve_options; + if (regularized) { + per_solve_options.D = problem->D.get(); + } + + Vector solution(num_cols); + LinearSolver::Summary summary = + solver->Solve(&lhs, rhs.data(), per_solve_options, solution.data()); + EXPECT_EQ(summary.termination_type, LINEAR_SOLVER_SUCCESS); + + // If solving for the regularized solution, add the diagonal to the + // matrix. This makes subsequent computations simpler. + if (testing::get<2>(param)) { + lhs.AppendDiagonal(problem->D.get()); + }; + + Vector tmp = Vector::Zero(num_rows + num_cols); + lhs.RightMultiply(solution.data(), tmp.data()); + Vector actual_normal_rhs = Vector::Zero(num_cols); + lhs.LeftMultiply(tmp.data(), actual_normal_rhs.data()); + + Vector expected_normal_rhs = Vector::Zero(num_cols); + lhs.LeftMultiply(rhs.data(), expected_normal_rhs.data()); + const double residual = (expected_normal_rhs - actual_normal_rhs).norm() / + expected_normal_rhs.norm(); + + EXPECT_NEAR(residual, 0.0, 10 * std::numeric_limits::epsilon()); +} + +// TODO(sameeragarwal): Should we move away from hard coded linear +// least squares problem to randomly generated ones? +#ifndef CERES_NO_LAPACK + +INSTANTIATE_TEST_CASE_P( + DenseLinearSolver, + DenseLinearSolverTest, + ::testing::Combine(::testing::Values(DENSE_QR, DENSE_NORMAL_CHOLESKY), + ::testing::Values(EIGEN, LAPACK), + ::testing::Values(true, false), + ::testing::Values(0, 1)), + ParamInfoToString); + +#else + +INSTANTIATE_TEST_CASE_P( + DenseLinearSolver, + DenseLinearSolverTest, + ::testing::Combine(::testing::Values(DENSE_QR, DENSE_NORMAL_CHOLESKY), + ::testing::Values(EIGEN), + ::testing::Values(true, false), + ::testing::Values(0, 1)), + ParamInfoToString); + +#endif + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dense_normal_cholesky_solver.cc b/internal/ceres/dense_normal_cholesky_solver.cc new file mode 100644 index 0000000..b13cf3f --- /dev/null +++ b/internal/ceres/dense_normal_cholesky_solver.cc @@ -0,0 +1,166 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/dense_normal_cholesky_solver.h" + +#include + +#include "Eigen/Dense" +#include "ceres/blas.h" +#include "ceres/dense_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/lapack.h" +#include "ceres/linear_solver.h" +#include "ceres/types.h" +#include "ceres/wall_time.h" + +namespace ceres { +namespace internal { + +DenseNormalCholeskySolver::DenseNormalCholeskySolver( + const LinearSolver::Options& options) + : options_(options) {} + +LinearSolver::Summary DenseNormalCholeskySolver::SolveImpl( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + if (options_.dense_linear_algebra_library_type == EIGEN) { + return SolveUsingEigen(A, b, per_solve_options, x); + } else { + return SolveUsingLAPACK(A, b, per_solve_options, x); + } +} + +LinearSolver::Summary DenseNormalCholeskySolver::SolveUsingEigen( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + EventLogger event_logger("DenseNormalCholeskySolver::Solve"); + + const int num_rows = A->num_rows(); + const int num_cols = A->num_cols(); + + ConstColMajorMatrixRef Aref = A->matrix(); + Matrix lhs(num_cols, num_cols); + lhs.setZero(); + + event_logger.AddEvent("Setup"); + + // lhs += A'A + // + // Using rankUpdate instead of GEMM, exposes the fact that its the + // same matrix being multiplied with itself and that the product is + // symmetric. + lhs.selfadjointView().rankUpdate(Aref.transpose()); + + // rhs = A'b + Vector rhs = Aref.transpose() * ConstVectorRef(b, num_rows); + + if (per_solve_options.D != NULL) { + ConstVectorRef D(per_solve_options.D, num_cols); + lhs += D.array().square().matrix().asDiagonal(); + } + event_logger.AddEvent("Product"); + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + Eigen::LLT llt = + lhs.selfadjointView().llt(); + + if (llt.info() != Eigen::Success) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = "Eigen LLT decomposition failed."; + } else { + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = "Success."; + } + + VectorRef(x, num_cols) = llt.solve(rhs); + event_logger.AddEvent("Solve"); + return summary; +} + +LinearSolver::Summary DenseNormalCholeskySolver::SolveUsingLAPACK( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + EventLogger event_logger("DenseNormalCholeskySolver::Solve"); + + if (per_solve_options.D != NULL) { + // Temporarily append a diagonal block to the A matrix, but undo + // it before returning the matrix to the user. + A->AppendDiagonal(per_solve_options.D); + } + + const int num_cols = A->num_cols(); + Matrix lhs(num_cols, num_cols); + event_logger.AddEvent("Setup"); + + // lhs = A'A + // + // Note: This is a bit delicate, it assumes that the stride on this + // matrix is the same as the number of rows. + BLAS::SymmetricRankKUpdate(A->num_rows(), + num_cols, + A->values(), + true, + 1.0, + 0.0, + lhs.data()); + + if (per_solve_options.D != NULL) { + // Undo the modifications to the matrix A. + A->RemoveDiagonal(); + } + + // TODO(sameeragarwal): Replace this with a gemv call for true blasness. + // rhs = A'b + VectorRef(x, num_cols) = + A->matrix().transpose() * ConstVectorRef(b, A->num_rows()); + event_logger.AddEvent("Product"); + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = + LAPACK::SolveInPlaceUsingCholesky(num_cols, + lhs.data(), + x, + &summary.message); + event_logger.AddEvent("Solve"); + return summary; +} +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dense_normal_cholesky_solver.h b/internal/ceres/dense_normal_cholesky_solver.h new file mode 100644 index 0000000..11287eb --- /dev/null +++ b/internal/ceres/dense_normal_cholesky_solver.h @@ -0,0 +1,107 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Solve dense rectangular systems Ax = b by forming the normal +// equations and solving them using the Cholesky factorization. + +#ifndef CERES_INTERNAL_DENSE_NORMAL_CHOLESKY_SOLVER_H_ +#define CERES_INTERNAL_DENSE_NORMAL_CHOLESKY_SOLVER_H_ + +#include "ceres/linear_solver.h" +#include "ceres/internal/macros.h" + +namespace ceres { +namespace internal { + +class DenseSparseMatrix; + +// This class implements the LinearSolver interface for solving +// rectangular/unsymmetric (well constrained) linear systems of the +// form +// +// Ax = b +// +// Since there does not usually exist a solution that satisfies these +// equations, the solver instead solves the linear least squares +// problem +// +// min_x |Ax - b|^2 +// +// Setting the gradient of the above optimization problem to zero +// gives us the normal equations +// +// A'Ax = A'b +// +// A'A is a positive definite matrix (hopefully), and the resulting +// linear system can be solved using Cholesky factorization. +// +// If the PerSolveOptions struct has a non-null array D, then the +// augmented/regularized linear system +// +// [ A ]x = [b] +// [ diag(D) ] [0] +// +// is solved. +// +// This class uses the LDLT factorization routines from the Eigen +// library. This solver always returns a solution, it is the user's +// responsibility to judge if the solution is good enough for their +// purposes. +class DenseNormalCholeskySolver: public DenseSparseMatrixSolver { + public: + explicit DenseNormalCholeskySolver(const LinearSolver::Options& options); + + private: + virtual LinearSolver::Summary SolveImpl( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + LinearSolver::Summary SolveUsingLAPACK( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + LinearSolver::Summary SolveUsingEigen( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + const LinearSolver::Options options_; + CERES_DISALLOW_COPY_AND_ASSIGN(DenseNormalCholeskySolver); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DENSE_NORMAL_CHOLESKY_SOLVER_H_ diff --git a/internal/ceres/dense_qr_solver.cc b/internal/ceres/dense_qr_solver.cc new file mode 100644 index 0000000..e85fdfc --- /dev/null +++ b/internal/ceres/dense_qr_solver.cc @@ -0,0 +1,170 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/dense_qr_solver.h" + + +#include +#include "Eigen/Dense" +#include "ceres/dense_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/lapack.h" +#include "ceres/linear_solver.h" +#include "ceres/types.h" +#include "ceres/wall_time.h" + +namespace ceres { +namespace internal { + +DenseQRSolver::DenseQRSolver(const LinearSolver::Options& options) + : options_(options) { + work_.resize(1); +} + +LinearSolver::Summary DenseQRSolver::SolveImpl( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + if (options_.dense_linear_algebra_library_type == EIGEN) { + return SolveUsingEigen(A, b, per_solve_options, x); + } else { + return SolveUsingLAPACK(A, b, per_solve_options, x); + } +} + +LinearSolver::Summary DenseQRSolver::SolveUsingLAPACK( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + EventLogger event_logger("DenseQRSolver::Solve"); + + const int num_rows = A->num_rows(); + const int num_cols = A->num_cols(); + + if (per_solve_options.D != NULL) { + // Temporarily append a diagonal block to the A matrix, but undo + // it before returning the matrix to the user. + A->AppendDiagonal(per_solve_options.D); + } + + // TODO(sameeragarwal): Since we are copying anyways, the diagonal + // can be appended to the matrix instead of doing it on A. + lhs_ = A->matrix(); + + if (per_solve_options.D != NULL) { + // Undo the modifications to the matrix A. + A->RemoveDiagonal(); + } + + // rhs = [b;0] to account for the additional rows in the lhs. + if (rhs_.rows() != lhs_.rows()) { + rhs_.resize(lhs_.rows()); + } + rhs_.setZero(); + rhs_.head(num_rows) = ConstVectorRef(b, num_rows); + + if (work_.rows() == 1) { + const int work_size = + LAPACK::EstimateWorkSizeForQR(lhs_.rows(), lhs_.cols()); + VLOG(3) << "Working memory for Dense QR factorization: " + << work_size * sizeof(double); + work_.resize(work_size); + } + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = LAPACK::SolveInPlaceUsingQR(lhs_.rows(), + lhs_.cols(), + lhs_.data(), + work_.rows(), + work_.data(), + rhs_.data(), + &summary.message); + event_logger.AddEvent("Solve"); + if (summary.termination_type == LINEAR_SOLVER_SUCCESS) { + VectorRef(x, num_cols) = rhs_.head(num_cols); + } + + event_logger.AddEvent("TearDown"); + return summary; +} + +LinearSolver::Summary DenseQRSolver::SolveUsingEigen( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + EventLogger event_logger("DenseQRSolver::Solve"); + + const int num_rows = A->num_rows(); + const int num_cols = A->num_cols(); + + if (per_solve_options.D != NULL) { + // Temporarily append a diagonal block to the A matrix, but undo + // it before returning the matrix to the user. + A->AppendDiagonal(per_solve_options.D); + } + + // rhs = [b;0] to account for the additional rows in the lhs. + const int augmented_num_rows = + num_rows + ((per_solve_options.D != NULL) ? num_cols : 0); + if (rhs_.rows() != augmented_num_rows) { + rhs_.resize(augmented_num_rows); + rhs_.setZero(); + } + rhs_.head(num_rows) = ConstVectorRef(b, num_rows); + event_logger.AddEvent("Setup"); + + // Solve the system. + VectorRef(x, num_cols) = A->matrix().householderQr().solve(rhs_); + event_logger.AddEvent("Solve"); + + if (per_solve_options.D != NULL) { + // Undo the modifications to the matrix A. + A->RemoveDiagonal(); + } + + // We always succeed, since the QR solver returns the best solution + // it can. It is the job of the caller to determine if the solution + // is good enough or not. + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = "Success."; + + event_logger.AddEvent("TearDown"); + return summary; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dense_qr_solver.h b/internal/ceres/dense_qr_solver.h new file mode 100644 index 0000000..1a6e089 --- /dev/null +++ b/internal/ceres/dense_qr_solver.h @@ -0,0 +1,115 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Solve dense rectangular systems Ax = b using the QR factorization. +#ifndef CERES_INTERNAL_DENSE_QR_SOLVER_H_ +#define CERES_INTERNAL_DENSE_QR_SOLVER_H_ + +#include "ceres/linear_solver.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/macros.h" + +namespace ceres { +namespace internal { + +class DenseSparseMatrix; + +// This class implements the LinearSolver interface for solving +// rectangular/unsymmetric (well constrained) linear systems of the +// form +// +// Ax = b +// +// Since there does not usually exist a solution that satisfies these +// equations, the solver instead solves the linear least squares +// problem +// +// min_x |Ax - b|^2 +// +// The solution strategy is based on computing the QR decomposition of +// A, i.e. +// +// A = QR +// +// Where Q is an orthonormal matrix and R is an upper triangular +// matrix. Then +// +// Ax = b +// QRx = b +// Q'QRx = Q'b +// Rx = Q'b +// x = R^{-1} Q'b +// +// If the PerSolveOptions struct has a non-null array D, then the +// augmented/regularized linear system +// +// [ A ]x = [b] +// [ diag(D) ] [0] +// +// is solved. +// +// This class uses the dense QR factorization routines from the Eigen +// library. This solver always returns a solution, it is the user's +// responsibility to judge if the solution is good enough for their +// purposes. +class DenseQRSolver: public DenseSparseMatrixSolver { + public: + explicit DenseQRSolver(const LinearSolver::Options& options); + + private: + virtual LinearSolver::Summary SolveImpl( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + LinearSolver::Summary SolveUsingEigen( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + LinearSolver::Summary SolveUsingLAPACK( + DenseSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x); + + const LinearSolver::Options options_; + ColMajorMatrix lhs_; + Vector rhs_; + Vector work_; + CERES_DISALLOW_COPY_AND_ASSIGN(DenseQRSolver); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DENSE_QR_SOLVER_H_ diff --git a/internal/ceres/dense_sparse_matrix.cc b/internal/ceres/dense_sparse_matrix.cc new file mode 100644 index 0000000..19db867 --- /dev/null +++ b/internal/ceres/dense_sparse_matrix.cc @@ -0,0 +1,183 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include "ceres/dense_sparse_matrix.h" + +#include +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/port.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +DenseSparseMatrix::DenseSparseMatrix(int num_rows, int num_cols) + : has_diagonal_appended_(false), + has_diagonal_reserved_(false) { + m_.resize(num_rows, num_cols); + m_.setZero(); +} + +DenseSparseMatrix::DenseSparseMatrix(int num_rows, + int num_cols, + bool reserve_diagonal) + : has_diagonal_appended_(false), + has_diagonal_reserved_(reserve_diagonal) { + if (reserve_diagonal) { + // Allocate enough space for the diagonal. + m_.resize(num_rows + num_cols, num_cols); + } else { + m_.resize(num_rows, num_cols); + } + m_.setZero(); +} + +DenseSparseMatrix::DenseSparseMatrix(const TripletSparseMatrix& m) + : m_(Eigen::MatrixXd::Zero(m.num_rows(), m.num_cols())), + has_diagonal_appended_(false), + has_diagonal_reserved_(false) { + const double *values = m.values(); + const int *rows = m.rows(); + const int *cols = m.cols(); + int num_nonzeros = m.num_nonzeros(); + + for (int i = 0; i < num_nonzeros; ++i) { + m_(rows[i], cols[i]) += values[i]; + } +} + +DenseSparseMatrix::DenseSparseMatrix(const ColMajorMatrix& m) + : m_(m), + has_diagonal_appended_(false), + has_diagonal_reserved_(false) { +} + +void DenseSparseMatrix::SetZero() { + m_.setZero(); +} + +void DenseSparseMatrix::RightMultiply(const double* x, double* y) const { + VectorRef(y, num_rows()) += matrix() * ConstVectorRef(x, num_cols()); +} + +void DenseSparseMatrix::LeftMultiply(const double* x, double* y) const { + VectorRef(y, num_cols()) += + matrix().transpose() * ConstVectorRef(x, num_rows()); +} + +void DenseSparseMatrix::SquaredColumnNorm(double* x) const { + VectorRef(x, num_cols()) = m_.colwise().squaredNorm(); +} + +void DenseSparseMatrix::ScaleColumns(const double* scale) { + m_ *= ConstVectorRef(scale, num_cols()).asDiagonal(); +} + +void DenseSparseMatrix::ToDenseMatrix(Matrix* dense_matrix) const { + *dense_matrix = m_.block(0, 0, num_rows(), num_cols()); +} + +void DenseSparseMatrix::AppendDiagonal(double *d) { + CHECK(!has_diagonal_appended_); + if (!has_diagonal_reserved_) { + ColMajorMatrix tmp = m_; + m_.resize(m_.rows() + m_.cols(), m_.cols()); + m_.setZero(); + m_.block(0, 0, tmp.rows(), tmp.cols()) = tmp; + has_diagonal_reserved_ = true; + } + + m_.bottomLeftCorner(m_.cols(), m_.cols()) = + ConstVectorRef(d, m_.cols()).asDiagonal(); + has_diagonal_appended_ = true; +} + +void DenseSparseMatrix::RemoveDiagonal() { + CHECK(has_diagonal_appended_); + has_diagonal_appended_ = false; + // Leave the diagonal reserved. +} + +int DenseSparseMatrix::num_rows() const { + if (has_diagonal_reserved_ && !has_diagonal_appended_) { + return m_.rows() - m_.cols(); + } + return m_.rows(); +} + +int DenseSparseMatrix::num_cols() const { + return m_.cols(); +} + +int DenseSparseMatrix::num_nonzeros() const { + if (has_diagonal_reserved_ && !has_diagonal_appended_) { + return (m_.rows() - m_.cols()) * m_.cols(); + } + return m_.rows() * m_.cols(); +} + +ConstColMajorMatrixRef DenseSparseMatrix::matrix() const { + return ConstColMajorMatrixRef( + m_.data(), + ((has_diagonal_reserved_ && !has_diagonal_appended_) + ? m_.rows() - m_.cols() + : m_.rows()), + m_.cols(), + Eigen::Stride(m_.rows(), 1)); +} + +ColMajorMatrixRef DenseSparseMatrix::mutable_matrix() { + return ColMajorMatrixRef( + m_.data(), + ((has_diagonal_reserved_ && !has_diagonal_appended_) + ? m_.rows() - m_.cols() + : m_.rows()), + m_.cols(), + Eigen::Stride(m_.rows(), 1)); +} + + +void DenseSparseMatrix::ToTextFile(FILE* file) const { + CHECK_NOTNULL(file); + const int active_rows = + (has_diagonal_reserved_ && !has_diagonal_appended_) + ? (m_.rows() - m_.cols()) + : m_.rows(); + + for (int r = 0; r < active_rows; ++r) { + for (int c = 0; c < m_.cols(); ++c) { + fprintf(file, "% 10d % 10d %17f\n", r, c, m_(r, c)); + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dense_sparse_matrix.h b/internal/ceres/dense_sparse_matrix.h new file mode 100644 index 0000000..b011bfd --- /dev/null +++ b/internal/ceres/dense_sparse_matrix.h @@ -0,0 +1,109 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// A dense matrix implemented under the SparseMatrix interface. + +#ifndef CERES_INTERNAL_DENSE_SPARSE_MATRIX_H_ +#define CERES_INTERNAL_DENSE_SPARSE_MATRIX_H_ + +#include "ceres/sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/macros.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/types.h" + +namespace ceres { +namespace internal { + +class TripletSparseMatrix; + +class DenseSparseMatrix : public SparseMatrix { + public: + // Build a matrix with the same content as the TripletSparseMatrix + // m. This assumes that m does not have any repeated entries. + explicit DenseSparseMatrix(const TripletSparseMatrix& m); + explicit DenseSparseMatrix(const ColMajorMatrix& m); + + DenseSparseMatrix(int num_rows, int num_cols); + DenseSparseMatrix(int num_rows, int num_cols, bool reserve_diagonal); + + virtual ~DenseSparseMatrix() {} + + // SparseMatrix interface. + virtual void SetZero(); + virtual void RightMultiply(const double* x, double* y) const; + virtual void LeftMultiply(const double* x, double* y) const; + virtual void SquaredColumnNorm(double* x) const; + virtual void ScaleColumns(const double* scale); + virtual void ToDenseMatrix(Matrix* dense_matrix) const; + virtual void ToTextFile(FILE* file) const; + virtual int num_rows() const; + virtual int num_cols() const; + virtual int num_nonzeros() const; + virtual const double* values() const { return m_.data(); } + virtual double* mutable_values() { return m_.data(); } + + ConstColMajorMatrixRef matrix() const; + ColMajorMatrixRef mutable_matrix(); + + // Only one diagonal can be appended at a time. The diagonal is appended to + // as a new set of rows, e.g. + // + // Original matrix: + // + // x x x + // x x x + // x x x + // + // After append diagonal (1, 2, 3): + // + // x x x + // x x x + // x x x + // 1 0 0 + // 0 2 0 + // 0 0 3 + // + // Calling RemoveDiagonal removes the block. It is a fatal error to append a + // diagonal to a matrix that already has an appended diagonal, and it is also + // a fatal error to remove a diagonal from a matrix that has none. + void AppendDiagonal(double *d); + void RemoveDiagonal(); + + private: + ColMajorMatrix m_; + bool has_diagonal_appended_; + bool has_diagonal_reserved_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DENSE_SPARSE_MATRIX_H_ diff --git a/internal/ceres/dense_sparse_matrix_test.cc b/internal/ceres/dense_sparse_matrix_test.cc new file mode 100644 index 0000000..a77f5e3 --- /dev/null +++ b/internal/ceres/dense_sparse_matrix_test.cc @@ -0,0 +1,169 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// TODO(keir): Implement a generic "compare sparse matrix implementations" test +// suite that can compare all the implementations. Then this file would shrink +// in size. + +#include "ceres/dense_sparse_matrix.h" + +#include "ceres/casts.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +void CompareMatrices(const SparseMatrix* a, const SparseMatrix* b) { + EXPECT_EQ(a->num_rows(), b->num_rows()); + EXPECT_EQ(a->num_cols(), b->num_cols()); + + int num_rows = a->num_rows(); + int num_cols = a->num_cols(); + + for (int i = 0; i < num_cols; ++i) { + Vector x = Vector::Zero(num_cols); + x(i) = 1.0; + + Vector y_a = Vector::Zero(num_rows); + Vector y_b = Vector::Zero(num_rows); + + a->RightMultiply(x.data(), y_a.data()); + b->RightMultiply(x.data(), y_b.data()); + + EXPECT_EQ((y_a - y_b).norm(), 0); + } +} + +class DenseSparseMatrixTest : public ::testing::Test { + protected : + virtual void SetUp() { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(1)); + + CHECK_NOTNULL(problem.get()); + + tsm.reset(down_cast(problem->A.release())); + dsm.reset(new DenseSparseMatrix(*tsm)); + + num_rows = tsm->num_rows(); + num_cols = tsm->num_cols(); + } + + int num_rows; + int num_cols; + + scoped_ptr tsm; + scoped_ptr dsm; +}; + +TEST_F(DenseSparseMatrixTest, RightMultiply) { + CompareMatrices(tsm.get(), dsm.get()); + + // Try with a not entirely zero vector to verify column interactions, which + // could be masked by a subtle bug when using the elementary vectors. + Vector a(num_cols); + for (int i = 0; i < num_cols; i++) { + a(i) = i; + } + Vector b1 = Vector::Zero(num_rows); + Vector b2 = Vector::Zero(num_rows); + + tsm->RightMultiply(a.data(), b1.data()); + dsm->RightMultiply(a.data(), b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); +} + +TEST_F(DenseSparseMatrixTest, LeftMultiply) { + for (int i = 0; i < num_rows; ++i) { + Vector a = Vector::Zero(num_rows); + a(i) = 1.0; + + Vector b1 = Vector::Zero(num_cols); + Vector b2 = Vector::Zero(num_cols); + + tsm->LeftMultiply(a.data(), b1.data()); + dsm->LeftMultiply(a.data(), b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); + } + + // Try with a not entirely zero vector to verify column interactions, which + // could be masked by a subtle bug when using the elementary vectors. + Vector a(num_rows); + for (int i = 0; i < num_rows; i++) { + a(i) = i; + } + Vector b1 = Vector::Zero(num_cols); + Vector b2 = Vector::Zero(num_cols); + + tsm->LeftMultiply(a.data(), b1.data()); + dsm->LeftMultiply(a.data(), b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); +} + +TEST_F(DenseSparseMatrixTest, ColumnNorm) { + Vector b1 = Vector::Zero(num_cols); + Vector b2 = Vector::Zero(num_cols); + + tsm->SquaredColumnNorm(b1.data()); + dsm->SquaredColumnNorm(b2.data()); + + EXPECT_EQ((b1 - b2).norm(), 0); +} + +TEST_F(DenseSparseMatrixTest, Scale) { + Vector scale(num_cols); + for (int i = 0; i < num_cols; ++i) { + scale(i) = i + 1; + } + tsm->ScaleColumns(scale.data()); + dsm->ScaleColumns(scale.data()); + CompareMatrices(tsm.get(), dsm.get()); +} + +TEST_F(DenseSparseMatrixTest, ToDenseMatrix) { + Matrix tsm_dense; + Matrix dsm_dense; + + tsm->ToDenseMatrix(&tsm_dense); + dsm->ToDenseMatrix(&dsm_dense); + + EXPECT_EQ((tsm_dense - dsm_dense).norm(), 0.0); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/detect_structure.cc b/internal/ceres/detect_structure.cc new file mode 100644 index 0000000..959a0ee --- /dev/null +++ b/internal/ceres/detect_structure.cc @@ -0,0 +1,120 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/detect_structure.h" +#include "ceres/internal/eigen.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +void DetectStructure(const CompressedRowBlockStructure& bs, + const int num_eliminate_blocks, + int* row_block_size, + int* e_block_size, + int* f_block_size) { + const int num_row_blocks = bs.rows.size(); + *row_block_size = 0; + *e_block_size = 0; + *f_block_size = 0; + + // Iterate over row blocks of the matrix, checking if row_block, + // e_block or f_block sizes remain constant. + for (int r = 0; r < num_row_blocks; ++r) { + const CompressedRow& row = bs.rows[r]; + // We do not care about the sizes of the blocks in rows which do + // not contain e_blocks. + if (row.cells.front().block_id >= num_eliminate_blocks) { + break; + } + + // Detect fixed or dynamic row block size. + if (*row_block_size == 0) { + *row_block_size = row.block.size; + } else if (*row_block_size != Eigen::Dynamic && + *row_block_size != row.block.size) { + VLOG(2) << "Dynamic row block size because the block size changed from " + << *row_block_size << " to " + << row.block.size; + *row_block_size = Eigen::Dynamic; + } + + // Detect fixed or dynamic e-block size. + const int e_block_id = row.cells.front().block_id; + if (*e_block_size == 0) { + *e_block_size = bs.cols[e_block_id].size; + } else if (*e_block_size != Eigen::Dynamic && + *e_block_size != bs.cols[e_block_id].size) { + VLOG(2) << "Dynamic e block size because the block size changed from " + << *e_block_size << " to " + << bs.cols[e_block_id].size; + *e_block_size = Eigen::Dynamic; + } + + // Detect fixed or dynamic f-block size. We are only interested in + // rows with e-blocks, and the e-block is always the first block, + // so only rows of size greater than 1 are of interest. + if (row.cells.size() > 1) { + if (*f_block_size == 0) { + const int f_block_id = row.cells[1].block_id; + *f_block_size = bs.cols[f_block_id].size; + } + + for (int c = 1; + (c < row.cells.size()) && (*f_block_size != Eigen::Dynamic); + ++c) { + const int f_block_id = row.cells[c].block_id; + if (*f_block_size != bs.cols[f_block_id].size) { + VLOG(2) << "Dynamic f block size because the block size " + << "changed from " << *f_block_size << " to " + << bs.cols[f_block_id].size; + *f_block_size = Eigen::Dynamic; + } + } + } + + const bool is_everything_dynamic = (*row_block_size == Eigen::Dynamic && + *e_block_size == Eigen::Dynamic && + *f_block_size == Eigen::Dynamic); + if (is_everything_dynamic) { + break; + } + } + + CHECK_NE(*row_block_size, 0) << "No rows found"; + CHECK_NE(*e_block_size, 0) << "No e type blocks found"; + VLOG(1) << "Schur complement static structure <" + << *row_block_size << "," + << *e_block_size << "," + << *f_block_size << ">."; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/detect_structure.h b/internal/ceres/detect_structure.h new file mode 100644 index 0000000..602581c --- /dev/null +++ b/internal/ceres/detect_structure.h @@ -0,0 +1,67 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_DETECT_STRUCTURE_H_ +#define CERES_INTERNAL_DETECT_STRUCTURE_H_ + +#include "ceres/block_structure.h" + +namespace ceres { +namespace internal { + +// Detect static blocks in the problem sparsity. For rows containing +// e_blocks, we are interested in detecting if the size of the row +// blocks, e_blocks and the f_blocks remain constant. If they do, then +// we can use template specialization to improve the performance of +// the block level linear algebra operations used by the +// SchurEliminator. +// +// If a block size is not constant, we return Eigen::Dynamic as the +// value. This just means that the eliminator uses dynamically sized +// linear algebra operations rather than static operations whose size +// is known as compile time. +// +// For more details about e_blocks and f_blocks, see +// schur_eliminator.h. This information is used to initialized an +// appropriate template specialization of SchurEliminator. +// +// Note: The structure of rows without any e-blocks has no effect on +// the values returned by this function. It is entirely possible that +// the f_block_size and row_blocks_size is not constant in such rows. +void DetectStructure(const CompressedRowBlockStructure& bs, + const int num_eliminate_blocks, + int* row_block_size, + int* e_block_size, + int* f_block_size); + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DETECT_STRUCTURE_H_ diff --git a/internal/ceres/detect_structure_test.cc b/internal/ceres/detect_structure_test.cc new file mode 100644 index 0000000..a701a19 --- /dev/null +++ b/internal/ceres/detect_structure_test.cc @@ -0,0 +1,294 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "Eigen/Core" +#include "glog/logging.h" +#include "gtest/gtest.h" +#include "ceres/block_structure.h" +#include "ceres/detect_structure.h" + +namespace ceres { +namespace internal { + +TEST(DetectStructure, EverythingStatic) { + const int expected_row_block_size = 2; + const int expected_e_block_size = 3; + const int expected_f_block_size = 4; + + CompressedRowBlockStructure bs; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 0; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 3; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 7; + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 0; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(1, 0)); + } + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 2; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(2, 0)); + } + + int row_block_size = 0; + int e_block_size = 0; + int f_block_size = 0; + const int num_eliminate_blocks = 1; + DetectStructure(bs, + num_eliminate_blocks, + &row_block_size, + &e_block_size, + &f_block_size); + + EXPECT_EQ(row_block_size, expected_row_block_size); + EXPECT_EQ(e_block_size, expected_e_block_size); + EXPECT_EQ(f_block_size, expected_f_block_size); +} + +TEST(DetectStructure, DynamicRow) { + const int expected_row_block_size = Eigen::Dynamic; + const int expected_e_block_size = 3; + const int expected_f_block_size = 4; + + CompressedRowBlockStructure bs; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 0; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 3; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 7; + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 0; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(1, 0)); + } + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 1; + row.block.position = 2; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(2, 0)); + } + + int row_block_size = 0; + int e_block_size = 0; + int f_block_size = 0; + const int num_eliminate_blocks = 1; + DetectStructure(bs, + num_eliminate_blocks, + &row_block_size, + &e_block_size, + &f_block_size); + + EXPECT_EQ(row_block_size, expected_row_block_size); + EXPECT_EQ(e_block_size, expected_e_block_size); + EXPECT_EQ(f_block_size, expected_f_block_size); +} + +TEST(DetectStructure, DynamicFBlockDifferentRows) { + const int expected_row_block_size = 2; + const int expected_e_block_size = 3; + const int expected_f_block_size = Eigen::Dynamic; + + + CompressedRowBlockStructure bs; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 0; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 3; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 7; + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 0; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(1, 0)); + } + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 2; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(2, 0)); + } + + int row_block_size = 0; + int e_block_size = 0; + int f_block_size = 0; + const int num_eliminate_blocks = 1; + DetectStructure(bs, + num_eliminate_blocks, + &row_block_size, + &e_block_size, + &f_block_size); + + EXPECT_EQ(row_block_size, expected_row_block_size); + EXPECT_EQ(e_block_size, expected_e_block_size); + EXPECT_EQ(f_block_size, expected_f_block_size); +} + +TEST(DetectStructure, DynamicEBlock) { + const int expected_row_block_size = 2; + const int expected_e_block_size = Eigen::Dynamic; + const int expected_f_block_size = 3; + + CompressedRowBlockStructure bs; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 0; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 3; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 7; + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 0; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(2, 0)); + } + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 2; + row.cells.push_back(Cell(1, 0)); + row.cells.push_back(Cell(2, 0)); + } + + int row_block_size = 0; + int e_block_size = 0; + int f_block_size = 0; + const int num_eliminate_blocks = 2; + DetectStructure(bs, + num_eliminate_blocks, + &row_block_size, + &e_block_size, + &f_block_size); + + EXPECT_EQ(row_block_size, expected_row_block_size); + EXPECT_EQ(e_block_size, expected_e_block_size); + EXPECT_EQ(f_block_size, expected_f_block_size); +} + +TEST(DetectStructure, DynamicFBlockSameRow) { + const int expected_row_block_size = 2; + const int expected_e_block_size = 3; + const int expected_f_block_size = Eigen::Dynamic; + + CompressedRowBlockStructure bs; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 0; + + bs.cols.push_back(Block()); + bs.cols.back().size = 4; + bs.cols.back().position = 3; + + bs.cols.push_back(Block()); + bs.cols.back().size = 3; + bs.cols.back().position = 7; + + { + bs.rows.push_back(CompressedRow()); + CompressedRow& row = bs.rows.back(); + row.block.size = 2; + row.block.position = 0; + row.cells.push_back(Cell(0, 0)); + row.cells.push_back(Cell(1, 0)); + row.cells.push_back(Cell(2, 0)); + } + + int row_block_size = 0; + int e_block_size = 0; + int f_block_size = 0; + const int num_eliminate_blocks = 1; + DetectStructure(bs, + num_eliminate_blocks, + &row_block_size, + &e_block_size, + &f_block_size); + + EXPECT_EQ(row_block_size, expected_row_block_size); + EXPECT_EQ(e_block_size, expected_e_block_size); + EXPECT_EQ(f_block_size, expected_f_block_size); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dogleg_strategy.cc b/internal/ceres/dogleg_strategy.cc new file mode 100644 index 0000000..839e181 --- /dev/null +++ b/internal/ceres/dogleg_strategy.cc @@ -0,0 +1,718 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/dogleg_strategy.h" + +#include +#include "Eigen/Dense" +#include "ceres/array_utils.h" +#include "ceres/internal/eigen.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/linear_solver.h" +#include "ceres/polynomial.h" +#include "ceres/sparse_matrix.h" +#include "ceres/trust_region_strategy.h" +#include "ceres/types.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { +namespace { +const double kMaxMu = 1.0; +const double kMinMu = 1e-8; +} + +DoglegStrategy::DoglegStrategy(const TrustRegionStrategy::Options& options) + : linear_solver_(options.linear_solver), + radius_(options.initial_radius), + max_radius_(options.max_radius), + min_diagonal_(options.min_lm_diagonal), + max_diagonal_(options.max_lm_diagonal), + mu_(kMinMu), + min_mu_(kMinMu), + max_mu_(kMaxMu), + mu_increase_factor_(10.0), + increase_threshold_(0.75), + decrease_threshold_(0.25), + dogleg_step_norm_(0.0), + reuse_(false), + dogleg_type_(options.dogleg_type) { + CHECK_NOTNULL(linear_solver_); + CHECK_GT(min_diagonal_, 0.0); + CHECK_LE(min_diagonal_, max_diagonal_); + CHECK_GT(max_radius_, 0.0); +} + +// If the reuse_ flag is not set, then the Cauchy point (scaled +// gradient) and the new Gauss-Newton step are computed from +// scratch. The Dogleg step is then computed as interpolation of these +// two vectors. +TrustRegionStrategy::Summary DoglegStrategy::ComputeStep( + const TrustRegionStrategy::PerSolveOptions& per_solve_options, + SparseMatrix* jacobian, + const double* residuals, + double* step) { + CHECK_NOTNULL(jacobian); + CHECK_NOTNULL(residuals); + CHECK_NOTNULL(step); + + const int n = jacobian->num_cols(); + if (reuse_) { + // Gauss-Newton and gradient vectors are always available, only a + // new interpolant need to be computed. For the subspace case, + // the subspace and the two-dimensional model are also still valid. + switch (dogleg_type_) { + case TRADITIONAL_DOGLEG: + ComputeTraditionalDoglegStep(step); + break; + + case SUBSPACE_DOGLEG: + ComputeSubspaceDoglegStep(step); + break; + } + TrustRegionStrategy::Summary summary; + summary.num_iterations = 0; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + return summary; + } + + reuse_ = true; + // Check that we have the storage needed to hold the various + // temporary vectors. + if (diagonal_.rows() != n) { + diagonal_.resize(n, 1); + gradient_.resize(n, 1); + gauss_newton_step_.resize(n, 1); + } + + // Vector used to form the diagonal matrix that is used to + // regularize the Gauss-Newton solve and that defines the + // elliptical trust region + // + // || D * step || <= radius_ . + // + jacobian->SquaredColumnNorm(diagonal_.data()); + for (int i = 0; i < n; ++i) { + diagonal_[i] = std::min(std::max(diagonal_[i], min_diagonal_), + max_diagonal_); + } + diagonal_ = diagonal_.array().sqrt(); + + ComputeGradient(jacobian, residuals); + ComputeCauchyPoint(jacobian); + + LinearSolver::Summary linear_solver_summary = + ComputeGaussNewtonStep(per_solve_options, jacobian, residuals); + + TrustRegionStrategy::Summary summary; + summary.residual_norm = linear_solver_summary.residual_norm; + summary.num_iterations = linear_solver_summary.num_iterations; + summary.termination_type = linear_solver_summary.termination_type; + + if (linear_solver_summary.termination_type == LINEAR_SOLVER_FATAL_ERROR) { + return summary; + } + + if (linear_solver_summary.termination_type != LINEAR_SOLVER_FAILURE) { + switch (dogleg_type_) { + // Interpolate the Cauchy point and the Gauss-Newton step. + case TRADITIONAL_DOGLEG: + ComputeTraditionalDoglegStep(step); + break; + + // Find the minimum in the subspace defined by the + // Cauchy point and the (Gauss-)Newton step. + case SUBSPACE_DOGLEG: + if (!ComputeSubspaceModel(jacobian)) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + break; + } + ComputeSubspaceDoglegStep(step); + break; + } + } + + return summary; +} + +// The trust region is assumed to be elliptical with the +// diagonal scaling matrix D defined by sqrt(diagonal_). +// It is implemented by substituting step' = D * step. +// The trust region for step' is spherical. +// The gradient, the Gauss-Newton step, the Cauchy point, +// and all calculations involving the Jacobian have to +// be adjusted accordingly. +void DoglegStrategy::ComputeGradient( + SparseMatrix* jacobian, + const double* residuals) { + gradient_.setZero(); + jacobian->LeftMultiply(residuals, gradient_.data()); + gradient_.array() /= diagonal_.array(); +} + +// The Cauchy point is the global minimizer of the quadratic model +// along the one-dimensional subspace spanned by the gradient. +void DoglegStrategy::ComputeCauchyPoint(SparseMatrix* jacobian) { + // alpha * -gradient is the Cauchy point. + Vector Jg(jacobian->num_rows()); + Jg.setZero(); + // The Jacobian is scaled implicitly by computing J * (D^-1 * (D^-1 * g)) + // instead of (J * D^-1) * (D^-1 * g). + Vector scaled_gradient = + (gradient_.array() / diagonal_.array()).matrix(); + jacobian->RightMultiply(scaled_gradient.data(), Jg.data()); + alpha_ = gradient_.squaredNorm() / Jg.squaredNorm(); +} + +// The dogleg step is defined as the intersection of the trust region +// boundary with the piecewise linear path from the origin to the Cauchy +// point and then from there to the Gauss-Newton point (global minimizer +// of the model function). The Gauss-Newton point is taken if it lies +// within the trust region. +void DoglegStrategy::ComputeTraditionalDoglegStep(double* dogleg) { + VectorRef dogleg_step(dogleg, gradient_.rows()); + + // Case 1. The Gauss-Newton step lies inside the trust region, and + // is therefore the optimal solution to the trust-region problem. + const double gradient_norm = gradient_.norm(); + const double gauss_newton_norm = gauss_newton_step_.norm(); + if (gauss_newton_norm <= radius_) { + dogleg_step = gauss_newton_step_; + dogleg_step_norm_ = gauss_newton_norm; + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "GaussNewton step size: " << dogleg_step_norm_ + << " radius: " << radius_; + return; + } + + // Case 2. The Cauchy point and the Gauss-Newton steps lie outside + // the trust region. Rescale the Cauchy point to the trust region + // and return. + if (gradient_norm * alpha_ >= radius_) { + dogleg_step = -(radius_ / gradient_norm) * gradient_; + dogleg_step_norm_ = radius_; + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "Cauchy step size: " << dogleg_step_norm_ + << " radius: " << radius_; + return; + } + + // Case 3. The Cauchy point is inside the trust region and the + // Gauss-Newton step is outside. Compute the line joining the two + // points and the point on it which intersects the trust region + // boundary. + + // a = alpha * -gradient + // b = gauss_newton_step + const double b_dot_a = -alpha_ * gradient_.dot(gauss_newton_step_); + const double a_squared_norm = pow(alpha_ * gradient_norm, 2.0); + const double b_minus_a_squared_norm = + a_squared_norm - 2 * b_dot_a + pow(gauss_newton_norm, 2); + + // c = a' (b - a) + // = alpha * -gradient' gauss_newton_step - alpha^2 |gradient|^2 + const double c = b_dot_a - a_squared_norm; + const double d = sqrt(c * c + b_minus_a_squared_norm * + (pow(radius_, 2.0) - a_squared_norm)); + + double beta = + (c <= 0) + ? (d - c) / b_minus_a_squared_norm + : (radius_ * radius_ - a_squared_norm) / (d + c); + dogleg_step = (-alpha_ * (1.0 - beta)) * gradient_ + + beta * gauss_newton_step_; + dogleg_step_norm_ = dogleg_step.norm(); + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "Dogleg step size: " << dogleg_step_norm_ + << " radius: " << radius_; +} + +// The subspace method finds the minimum of the two-dimensional problem +// +// min. 1/2 x' B' H B x + g' B x +// s.t. || B x ||^2 <= r^2 +// +// where r is the trust region radius and B is the matrix with unit columns +// spanning the subspace defined by the steepest descent and Newton direction. +// This subspace by definition includes the Gauss-Newton point, which is +// therefore taken if it lies within the trust region. +void DoglegStrategy::ComputeSubspaceDoglegStep(double* dogleg) { + VectorRef dogleg_step(dogleg, gradient_.rows()); + + // The Gauss-Newton point is inside the trust region if |GN| <= radius_. + // This test is valid even though radius_ is a length in the two-dimensional + // subspace while gauss_newton_step_ is expressed in the (scaled) + // higher dimensional original space. This is because + // + // 1. gauss_newton_step_ by definition lies in the subspace, and + // 2. the subspace basis is orthonormal. + // + // As a consequence, the norm of the gauss_newton_step_ in the subspace is + // the same as its norm in the original space. + const double gauss_newton_norm = gauss_newton_step_.norm(); + if (gauss_newton_norm <= radius_) { + dogleg_step = gauss_newton_step_; + dogleg_step_norm_ = gauss_newton_norm; + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "GaussNewton step size: " << dogleg_step_norm_ + << " radius: " << radius_; + return; + } + + // The optimum lies on the boundary of the trust region. The above problem + // therefore becomes + // + // min. 1/2 x^T B^T H B x + g^T B x + // s.t. || B x ||^2 = r^2 + // + // Notice the equality in the constraint. + // + // This can be solved by forming the Lagrangian, solving for x(y), where + // y is the Lagrange multiplier, using the gradient of the objective, and + // putting x(y) back into the constraint. This results in a fourth order + // polynomial in y, which can be solved using e.g. the companion matrix. + // See the description of MakePolynomialForBoundaryConstrainedProblem for + // details. The result is up to four real roots y*, not all of which + // correspond to feasible points. The feasible points x(y*) have to be + // tested for optimality. + + if (subspace_is_one_dimensional_) { + // The subspace is one-dimensional, so both the gradient and + // the Gauss-Newton step point towards the same direction. + // In this case, we move along the gradient until we reach the trust + // region boundary. + dogleg_step = -(radius_ / gradient_.norm()) * gradient_; + dogleg_step_norm_ = radius_; + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "Dogleg subspace step size (1D): " << dogleg_step_norm_ + << " radius: " << radius_; + return; + } + + Vector2d minimum(0.0, 0.0); + if (!FindMinimumOnTrustRegionBoundary(&minimum)) { + // For the positive semi-definite case, a traditional dogleg step + // is taken in this case. + LOG(WARNING) << "Failed to compute polynomial roots. " + << "Taking traditional dogleg step instead."; + ComputeTraditionalDoglegStep(dogleg); + return; + } + + // Test first order optimality at the minimum. + // The first order KKT conditions state that the minimum x* + // has to satisfy either || x* ||^2 < r^2 (i.e. has to lie within + // the trust region), or + // + // (B x* + g) + y x* = 0 + // + // for some positive scalar y. + // Here, as it is already known that the minimum lies on the boundary, the + // latter condition is tested. To allow for small imprecisions, we test if + // the angle between (B x* + g) and -x* is smaller than acos(0.99). + // The exact value of the cosine is arbitrary but should be close to 1. + // + // This condition should not be violated. If it is, the minimum was not + // correctly determined. + const double kCosineThreshold = 0.99; + const Vector2d grad_minimum = subspace_B_ * minimum + subspace_g_; + const double cosine_angle = -minimum.dot(grad_minimum) / + (minimum.norm() * grad_minimum.norm()); + if (cosine_angle < kCosineThreshold) { + LOG(WARNING) << "First order optimality seems to be violated " + << "in the subspace method!\n" + << "Cosine of angle between x and B x + g is " + << cosine_angle << ".\n" + << "Taking a regular dogleg step instead.\n" + << "Please consider filing a bug report if this " + << "happens frequently or consistently.\n"; + ComputeTraditionalDoglegStep(dogleg); + return; + } + + // Create the full step from the optimal 2d solution. + dogleg_step = subspace_basis_ * minimum; + dogleg_step_norm_ = radius_; + dogleg_step.array() /= diagonal_.array(); + VLOG(3) << "Dogleg subspace step size: " << dogleg_step_norm_ + << " radius: " << radius_; +} + +// Build the polynomial that defines the optimal Lagrange multipliers. +// Let the Lagrangian be +// +// L(x, y) = 0.5 x^T B x + x^T g + y (0.5 x^T x - 0.5 r^2). (1) +// +// Stationary points of the Lagrangian are given by +// +// 0 = d L(x, y) / dx = Bx + g + y x (2) +// 0 = d L(x, y) / dy = 0.5 x^T x - 0.5 r^2 (3) +// +// For any given y, we can solve (2) for x as +// +// x(y) = -(B + y I)^-1 g . (4) +// +// As B + y I is 2x2, we form the inverse explicitly: +// +// (B + y I)^-1 = (1 / det(B + y I)) adj(B + y I) (5) +// +// where adj() denotes adjugation. This should be safe, as B is positive +// semi-definite and y is necessarily positive, so (B + y I) is indeed +// invertible. +// Plugging (5) into (4) and the result into (3), then dividing by 0.5 we +// obtain +// +// 0 = (1 / det(B + y I))^2 g^T adj(B + y I)^T adj(B + y I) g - r^2 +// (6) +// +// or +// +// det(B + y I)^2 r^2 = g^T adj(B + y I)^T adj(B + y I) g (7a) +// = g^T adj(B)^T adj(B) g +// + 2 y g^T adj(B)^T g + y^2 g^T g (7b) +// +// as +// +// adj(B + y I) = adj(B) + y I = adj(B)^T + y I . (8) +// +// The left hand side can be expressed explicitly using +// +// det(B + y I) = det(B) + y tr(B) + y^2 . (9) +// +// So (7) is a polynomial in y of degree four. +// Bringing everything back to the left hand side, the coefficients can +// be read off as +// +// y^4 r^2 +// + y^3 2 r^2 tr(B) +// + y^2 (r^2 tr(B)^2 + 2 r^2 det(B) - g^T g) +// + y^1 (2 r^2 det(B) tr(B) - 2 g^T adj(B)^T g) +// + y^0 (r^2 det(B)^2 - g^T adj(B)^T adj(B) g) +// +Vector DoglegStrategy::MakePolynomialForBoundaryConstrainedProblem() const { + const double detB = subspace_B_.determinant(); + const double trB = subspace_B_.trace(); + const double r2 = radius_ * radius_; + Matrix2d B_adj; + B_adj << subspace_B_(1, 1) , -subspace_B_(0, 1), + -subspace_B_(1, 0) , subspace_B_(0, 0); + + Vector polynomial(5); + polynomial(0) = r2; + polynomial(1) = 2.0 * r2 * trB; + polynomial(2) = r2 * (trB * trB + 2.0 * detB) - subspace_g_.squaredNorm(); + polynomial(3) = -2.0 * (subspace_g_.transpose() * B_adj * subspace_g_ + - r2 * detB * trB); + polynomial(4) = r2 * detB * detB - (B_adj * subspace_g_).squaredNorm(); + + return polynomial; +} + +// Given a Lagrange multiplier y that corresponds to a stationary point +// of the Lagrangian L(x, y), compute the corresponding x from the +// equation +// +// 0 = d L(x, y) / dx +// = B * x + g + y * x +// = (B + y * I) * x + g +// +DoglegStrategy::Vector2d DoglegStrategy::ComputeSubspaceStepFromRoot( + double y) const { + const Matrix2d B_i = subspace_B_ + y * Matrix2d::Identity(); + return -B_i.partialPivLu().solve(subspace_g_); +} + +// This function evaluates the quadratic model at a point x in the +// subspace spanned by subspace_basis_. +double DoglegStrategy::EvaluateSubspaceModel(const Vector2d& x) const { + return 0.5 * x.dot(subspace_B_ * x) + subspace_g_.dot(x); +} + +// This function attempts to solve the boundary-constrained subspace problem +// +// min. 1/2 x^T B^T H B x + g^T B x +// s.t. || B x ||^2 = r^2 +// +// where B is an orthonormal subspace basis and r is the trust-region radius. +// +// This is done by finding the roots of a fourth degree polynomial. If the +// root finding fails, the function returns false and minimum will be set +// to (0, 0). If it succeeds, true is returned. +// +// In the failure case, another step should be taken, such as the traditional +// dogleg step. +bool DoglegStrategy::FindMinimumOnTrustRegionBoundary(Vector2d* minimum) const { + CHECK_NOTNULL(minimum); + + // Return (0, 0) in all error cases. + minimum->setZero(); + + // Create the fourth-degree polynomial that is a necessary condition for + // optimality. + const Vector polynomial = MakePolynomialForBoundaryConstrainedProblem(); + + // Find the real parts y_i of its roots (not only the real roots). + Vector roots_real; + if (!FindPolynomialRoots(polynomial, &roots_real, NULL)) { + // Failed to find the roots of the polynomial, i.e. the candidate + // solutions of the constrained problem. Report this back to the caller. + return false; + } + + // For each root y, compute B x(y) and check for feasibility. + // Notice that there should always be four roots, as the leading term of + // the polynomial is r^2 and therefore non-zero. However, as some roots + // may be complex, the real parts are not necessarily unique. + double minimum_value = std::numeric_limits::max(); + bool valid_root_found = false; + for (int i = 0; i < roots_real.size(); ++i) { + const Vector2d x_i = ComputeSubspaceStepFromRoot(roots_real(i)); + + // Not all roots correspond to points on the trust region boundary. + // There are at most four candidate solutions. As we are interested + // in the minimum, it is safe to consider all of them after projecting + // them onto the trust region boundary. + if (x_i.norm() > 0) { + const double f_i = EvaluateSubspaceModel((radius_ / x_i.norm()) * x_i); + valid_root_found = true; + if (f_i < minimum_value) { + minimum_value = f_i; + *minimum = x_i; + } + } + } + + return valid_root_found; +} + +LinearSolver::Summary DoglegStrategy::ComputeGaussNewtonStep( + const PerSolveOptions& per_solve_options, + SparseMatrix* jacobian, + const double* residuals) { + const int n = jacobian->num_cols(); + LinearSolver::Summary linear_solver_summary; + linear_solver_summary.termination_type = LINEAR_SOLVER_FAILURE; + + // The Jacobian matrix is often quite poorly conditioned. Thus it is + // necessary to add a diagonal matrix at the bottom to prevent the + // linear solver from failing. + // + // We do this by computing the same diagonal matrix as the one used + // by Levenberg-Marquardt (other choices are possible), and scaling + // it by a small constant (independent of the trust region radius). + // + // If the solve fails, the multiplier to the diagonal is increased + // up to max_mu_ by a factor of mu_increase_factor_ every time. If + // the linear solver is still not successful, the strategy returns + // with LINEAR_SOLVER_FAILURE. + // + // Next time when a new Gauss-Newton step is requested, the + // multiplier starts out from the last successful solve. + // + // When a step is declared successful, the multiplier is decreased + // by half of mu_increase_factor_. + + while (mu_ < max_mu_) { + // Dogleg, as far as I (sameeragarwal) understand it, requires a + // reasonably good estimate of the Gauss-Newton step. This means + // that we need to solve the normal equations more or less + // exactly. This is reflected in the values of the tolerances set + // below. + // + // For now, this strategy should only be used with exact + // factorization based solvers, for which these tolerances are + // automatically satisfied. + // + // The right way to combine inexact solves with trust region + // methods is to use Stiehaug's method. + LinearSolver::PerSolveOptions solve_options; + solve_options.q_tolerance = 0.0; + solve_options.r_tolerance = 0.0; + + lm_diagonal_ = diagonal_ * std::sqrt(mu_); + solve_options.D = lm_diagonal_.data(); + + // As in the LevenbergMarquardtStrategy, solve Jy = r instead + // of Jx = -r and later set x = -y to avoid having to modify + // either jacobian or residuals. + InvalidateArray(n, gauss_newton_step_.data()); + linear_solver_summary = linear_solver_->Solve(jacobian, + residuals, + solve_options, + gauss_newton_step_.data()); + + if (per_solve_options.dump_format_type == CONSOLE || + (per_solve_options.dump_format_type != CONSOLE && + !per_solve_options.dump_filename_base.empty())) { + if (!DumpLinearLeastSquaresProblem(per_solve_options.dump_filename_base, + per_solve_options.dump_format_type, + jacobian, + solve_options.D, + residuals, + gauss_newton_step_.data(), + 0)) { + LOG(ERROR) << "Unable to dump trust region problem." + << " Filename base: " + << per_solve_options.dump_filename_base; + } + } + + if (linear_solver_summary.termination_type == LINEAR_SOLVER_FATAL_ERROR) { + return linear_solver_summary; + } + + if (linear_solver_summary.termination_type == LINEAR_SOLVER_FAILURE || + !IsArrayValid(n, gauss_newton_step_.data())) { + mu_ *= mu_increase_factor_; + VLOG(2) << "Increasing mu " << mu_; + linear_solver_summary.termination_type = LINEAR_SOLVER_FAILURE; + continue; + } + break; + } + + if (linear_solver_summary.termination_type != LINEAR_SOLVER_FAILURE) { + // The scaled Gauss-Newton step is D * GN: + // + // - (D^-1 J^T J D^-1)^-1 (D^-1 g) + // = - D (J^T J)^-1 D D^-1 g + // = D -(J^T J)^-1 g + // + gauss_newton_step_.array() *= -diagonal_.array(); + } + + return linear_solver_summary; +} + +void DoglegStrategy::StepAccepted(double step_quality) { + CHECK_GT(step_quality, 0.0); + + if (step_quality < decrease_threshold_) { + radius_ *= 0.5; + } + + if (step_quality > increase_threshold_) { + radius_ = std::max(radius_, 3.0 * dogleg_step_norm_); + } + + // Reduce the regularization multiplier, in the hope that whatever + // was causing the rank deficiency has gone away and we can return + // to doing a pure Gauss-Newton solve. + mu_ = std::max(min_mu_, 2.0 * mu_ / mu_increase_factor_); + reuse_ = false; +} + +void DoglegStrategy::StepRejected(double step_quality) { + radius_ *= 0.5; + reuse_ = true; +} + +void DoglegStrategy::StepIsInvalid() { + mu_ *= mu_increase_factor_; + reuse_ = false; +} + +double DoglegStrategy::Radius() const { + return radius_; +} + +bool DoglegStrategy::ComputeSubspaceModel(SparseMatrix* jacobian) { + // Compute an orthogonal basis for the subspace using QR decomposition. + Matrix basis_vectors(jacobian->num_cols(), 2); + basis_vectors.col(0) = gradient_; + basis_vectors.col(1) = gauss_newton_step_; + Eigen::ColPivHouseholderQR basis_qr(basis_vectors); + + switch (basis_qr.rank()) { + case 0: + // This should never happen, as it implies that both the gradient + // and the Gauss-Newton step are zero. In this case, the minimizer should + // have stopped due to the gradient being too small. + LOG(ERROR) << "Rank of subspace basis is 0. " + << "This means that the gradient at the current iterate is " + << "zero but the optimization has not been terminated. " + << "You may have found a bug in Ceres."; + return false; + + case 1: + // Gradient and Gauss-Newton step coincide, so we lie on one of the + // major axes of the quadratic problem. In this case, we simply move + // along the gradient until we reach the trust region boundary. + subspace_is_one_dimensional_ = true; + return true; + + case 2: + subspace_is_one_dimensional_ = false; + break; + + default: + LOG(ERROR) << "Rank of the subspace basis matrix is reported to be " + << "greater than 2. As the matrix contains only two " + << "columns this cannot be true and is indicative of " + << "a bug."; + return false; + } + + // The subspace is two-dimensional, so compute the subspace model. + // Given the basis U, this is + // + // subspace_g_ = g_scaled^T U + // + // and + // + // subspace_B_ = U^T (J_scaled^T J_scaled) U + // + // As J_scaled = J * D^-1, the latter becomes + // + // subspace_B_ = ((U^T D^-1) J^T) (J (D^-1 U)) + // = (J (D^-1 U))^T (J (D^-1 U)) + + subspace_basis_ = + basis_qr.householderQ() * Matrix::Identity(jacobian->num_cols(), 2); + + subspace_g_ = subspace_basis_.transpose() * gradient_; + + Eigen::Matrix + Jb(2, jacobian->num_rows()); + Jb.setZero(); + + Vector tmp; + tmp = (subspace_basis_.col(0).array() / diagonal_.array()).matrix(); + jacobian->RightMultiply(tmp.data(), Jb.row(0).data()); + tmp = (subspace_basis_.col(1).array() / diagonal_.array()).matrix(); + jacobian->RightMultiply(tmp.data(), Jb.row(1).data()); + + subspace_B_ = Jb * Jb.transpose(); + + return true; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dogleg_strategy.h b/internal/ceres/dogleg_strategy.h new file mode 100644 index 0000000..046b9d8 --- /dev/null +++ b/internal/ceres/dogleg_strategy.h @@ -0,0 +1,165 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_DOGLEG_STRATEGY_H_ +#define CERES_INTERNAL_DOGLEG_STRATEGY_H_ + +#include "ceres/linear_solver.h" +#include "ceres/trust_region_strategy.h" + +namespace ceres { +namespace internal { + +// Dogleg step computation and trust region sizing strategy based on +// on "Methods for Nonlinear Least Squares" by K. Madsen, H.B. Nielsen +// and O. Tingleff. Available to download from +// +// http://www2.imm.dtu.dk/pubdb/views/edoc_download.php/3215/pdf/imm3215.pdf +// +// One minor modification is that instead of computing the pure +// Gauss-Newton step, we compute a regularized version of it. This is +// because the Jacobian is often rank-deficient and in such cases +// using a direct solver leads to numerical failure. +// +// If SUBSPACE is passed as the type argument to the constructor, the +// DoglegStrategy follows the approach by Shultz, Schnabel, Byrd. +// This finds the exact optimum over the two-dimensional subspace +// spanned by the two Dogleg vectors. +class DoglegStrategy : public TrustRegionStrategy { + public: + explicit DoglegStrategy(const TrustRegionStrategy::Options& options); + virtual ~DoglegStrategy() {} + + // TrustRegionStrategy interface + virtual Summary ComputeStep(const PerSolveOptions& per_solve_options, + SparseMatrix* jacobian, + const double* residuals, + double* step); + virtual void StepAccepted(double step_quality); + virtual void StepRejected(double step_quality); + virtual void StepIsInvalid(); + + virtual double Radius() const; + + // These functions are predominantly for testing. + Vector gradient() const { return gradient_; } + Vector gauss_newton_step() const { return gauss_newton_step_; } + Matrix subspace_basis() const { return subspace_basis_; } + Vector subspace_g() const { return subspace_g_; } + Matrix subspace_B() const { return subspace_B_; } + + private: + typedef Eigen::Matrix Vector2d; + typedef Eigen::Matrix Matrix2d; + + LinearSolver::Summary ComputeGaussNewtonStep( + const PerSolveOptions& per_solve_options, + SparseMatrix* jacobian, + const double* residuals); + void ComputeCauchyPoint(SparseMatrix* jacobian); + void ComputeGradient(SparseMatrix* jacobian, const double* residuals); + void ComputeTraditionalDoglegStep(double* step); + bool ComputeSubspaceModel(SparseMatrix* jacobian); + void ComputeSubspaceDoglegStep(double* step); + + bool FindMinimumOnTrustRegionBoundary(Vector2d* minimum) const; + Vector MakePolynomialForBoundaryConstrainedProblem() const; + Vector2d ComputeSubspaceStepFromRoot(double lambda) const; + double EvaluateSubspaceModel(const Vector2d& x) const; + + LinearSolver* linear_solver_; + double radius_; + const double max_radius_; + + const double min_diagonal_; + const double max_diagonal_; + + // mu is used to scale the diagonal matrix used to make the + // Gauss-Newton solve full rank. In each solve, the strategy starts + // out with mu = min_mu, and tries values upto max_mu. If the user + // reports an invalid step, the value of mu_ is increased so that + // the next solve starts with a stronger regularization. + // + // If a successful step is reported, then the value of mu_ is + // decreased with a lower bound of min_mu_. + double mu_; + const double min_mu_; + const double max_mu_; + const double mu_increase_factor_; + const double increase_threshold_; + const double decrease_threshold_; + + Vector diagonal_; // sqrt(diag(J^T J)) + Vector lm_diagonal_; + + Vector gradient_; + Vector gauss_newton_step_; + + // cauchy_step = alpha * gradient + double alpha_; + double dogleg_step_norm_; + + // When, ComputeStep is called, reuse_ indicates whether the + // Gauss-Newton and Cauchy steps from the last call to ComputeStep + // can be reused or not. + // + // If the user called StepAccepted, then it is expected that the + // user has recomputed the Jacobian matrix and new Gauss-Newton + // solve is needed and reuse is set to false. + // + // If the user called StepRejected, then it is expected that the + // user wants to solve the trust region problem with the same matrix + // but a different trust region radius and the Gauss-Newton and + // Cauchy steps can be reused to compute the Dogleg, thus reuse is + // set to true. + // + // If the user called StepIsInvalid, then there was a numerical + // problem with the step computed in the last call to ComputeStep, + // and the regularization used to do the Gauss-Newton solve is + // increased and a new solve should be done when ComputeStep is + // called again, thus reuse is set to false. + bool reuse_; + + // The dogleg type determines how the minimum of the local + // quadratic model is found. + DoglegType dogleg_type_; + + // If the type is SUBSPACE_DOGLEG, the two-dimensional + // model 1/2 x^T B x + g^T x has to be computed and stored. + bool subspace_is_one_dimensional_; + Matrix subspace_basis_; + Vector2d subspace_g_; + Matrix2d subspace_B_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DOGLEG_STRATEGY_H_ diff --git a/internal/ceres/dogleg_strategy_test.cc b/internal/ceres/dogleg_strategy_test.cc new file mode 100644 index 0000000..f1fe05a --- /dev/null +++ b/internal/ceres/dogleg_strategy_test.cc @@ -0,0 +1,287 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: moll.markus@arcor.de (Markus Moll) + +#include +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/dense_qr_solver.h" +#include "ceres/dogleg_strategy.h" +#include "ceres/linear_solver.h" +#include "ceres/trust_region_strategy.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { +namespace { + +class Fixture : public testing::Test { + protected: + scoped_ptr jacobian_; + Vector residual_; + Vector x_; + TrustRegionStrategy::Options options_; +}; + +// A test problem where +// +// J^T J = Q diag([1 2 4 8 16 32]) Q^T +// +// where Q is a randomly chosen orthonormal basis of R^6. +// The residual is chosen so that the minimum of the quadratic function is +// at (1, 1, 1, 1, 1, 1). It is therefore at a distance of sqrt(6) ~ 2.45 +// from the origin. +class DoglegStrategyFixtureEllipse : public Fixture { + protected: + virtual void SetUp() { + Matrix basis(6, 6); + // The following lines exceed 80 characters for better readability. + basis << -0.1046920933796121, -0.7449367449921986, -0.4190744502875876, -0.4480450716142566, 0.2375351607929440, -0.0363053418882862, // NOLINT + 0.4064975684355914, 0.2681113508511354, -0.7463625494601520, -0.0803264850508117, -0.4463149623021321, 0.0130224954867195, // NOLINT + -0.5514387729089798, 0.1026621026168657, -0.5008316122125011, 0.5738122212666414, 0.2974664724007106, 0.1296020877535158, // NOLINT + 0.5037835370947156, 0.2668479925183712, -0.1051754618492798, -0.0272739396578799, 0.7947481647088278, -0.1776623363955670, // NOLINT + -0.4005458426625444, 0.2939330589634109, -0.0682629380550051, -0.2895448882503687, -0.0457239396341685, -0.8139899477847840, // NOLINT + -0.3247764582762654, 0.4528151365941945, -0.0276683863102816, -0.6155994592510784, 0.1489240599972848, 0.5362574892189350; // NOLINT + + Vector Ddiag(6); + Ddiag << 1.0, 2.0, 4.0, 8.0, 16.0, 32.0; + + Matrix sqrtD = Ddiag.array().sqrt().matrix().asDiagonal(); + Matrix jacobian = sqrtD * basis; + jacobian_.reset(new DenseSparseMatrix(jacobian)); + + Vector minimum(6); + minimum << 1.0, 1.0, 1.0, 1.0, 1.0, 1.0; + residual_ = -jacobian * minimum; + + x_.resize(6); + x_.setZero(); + + options_.min_lm_diagonal = 1.0; + options_.max_lm_diagonal = 1.0; + } +}; + +// A test problem where +// +// J^T J = diag([1 2 4 8 16 32]) . +// +// The residual is chosen so that the minimum of the quadratic function is +// at (0, 0, 1, 0, 0, 0). It is therefore at a distance of 1 from the origin. +// The gradient at the origin points towards the global minimum. +class DoglegStrategyFixtureValley : public Fixture { + protected: + virtual void SetUp() { + Vector Ddiag(6); + Ddiag << 1.0, 2.0, 4.0, 8.0, 16.0, 32.0; + + Matrix jacobian = Ddiag.asDiagonal(); + jacobian_.reset(new DenseSparseMatrix(jacobian)); + + Vector minimum(6); + minimum << 0.0, 0.0, 1.0, 0.0, 0.0, 0.0; + residual_ = -jacobian * minimum; + + x_.resize(6); + x_.setZero(); + + options_.min_lm_diagonal = 1.0; + options_.max_lm_diagonal = 1.0; + } +}; + +const double kTolerance = 1e-14; +const double kToleranceLoose = 1e-5; +const double kEpsilon = std::numeric_limits::epsilon(); + +} // namespace + +// The DoglegStrategy must never return a step that is longer than the current +// trust region radius. +TEST_F(DoglegStrategyFixtureEllipse, TrustRegionObeyedTraditional) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + // The global minimum is at (1, 1, ..., 1), so the distance to it is + // sqrt(6.0). By restricting the trust region to a radius of 2.0, + // we test if the trust region is actually obeyed. + options_.dogleg_type = TRADITIONAL_DOGLEG; + options_.initial_radius = 2.0; + options_.max_radius = 2.0; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + TrustRegionStrategy::Summary summary = strategy.ComputeStep(pso, + jacobian_.get(), + residual_.data(), + x_.data()); + + EXPECT_NE(summary.termination_type, LINEAR_SOLVER_FAILURE); + EXPECT_LE(x_.norm(), options_.initial_radius * (1.0 + 4.0 * kEpsilon)); +} + +TEST_F(DoglegStrategyFixtureEllipse, TrustRegionObeyedSubspace) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + options_.dogleg_type = SUBSPACE_DOGLEG; + options_.initial_radius = 2.0; + options_.max_radius = 2.0; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + TrustRegionStrategy::Summary summary = strategy.ComputeStep(pso, + jacobian_.get(), + residual_.data(), + x_.data()); + + EXPECT_NE(summary.termination_type, LINEAR_SOLVER_FAILURE); + EXPECT_LE(x_.norm(), options_.initial_radius * (1.0 + 4.0 * kEpsilon)); +} + +TEST_F(DoglegStrategyFixtureEllipse, CorrectGaussNewtonStep) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + options_.dogleg_type = SUBSPACE_DOGLEG; + options_.initial_radius = 10.0; + options_.max_radius = 10.0; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + TrustRegionStrategy::Summary summary = strategy.ComputeStep(pso, + jacobian_.get(), + residual_.data(), + x_.data()); + + EXPECT_NE(summary.termination_type, LINEAR_SOLVER_FAILURE); + EXPECT_NEAR(x_(0), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(1), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(2), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(3), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(4), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(5), 1.0, kToleranceLoose); +} + +// Test if the subspace basis is a valid orthonormal basis of the space spanned +// by the gradient and the Gauss-Newton point. +TEST_F(DoglegStrategyFixtureEllipse, ValidSubspaceBasis) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + options_.dogleg_type = SUBSPACE_DOGLEG; + options_.initial_radius = 2.0; + options_.max_radius = 2.0; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + strategy.ComputeStep(pso, jacobian_.get(), residual_.data(), x_.data()); + + // Check if the basis is orthonormal. + const Matrix basis = strategy.subspace_basis(); + EXPECT_NEAR(basis.col(0).norm(), 1.0, kTolerance); + EXPECT_NEAR(basis.col(1).norm(), 1.0, kTolerance); + EXPECT_NEAR(basis.col(0).dot(basis.col(1)), 0.0, kTolerance); + + // Check if the gradient projects onto itself. + const Vector gradient = strategy.gradient(); + EXPECT_NEAR((gradient - basis*(basis.transpose()*gradient)).norm(), + 0.0, + kTolerance); + + // Check if the Gauss-Newton point projects onto itself. + const Vector gn = strategy.gauss_newton_step(); + EXPECT_NEAR((gn - basis*(basis.transpose()*gn)).norm(), + 0.0, + kTolerance); +} + +// Test if the step is correct if the gradient and the Gauss-Newton step point +// in the same direction and the Gauss-Newton step is outside the trust region, +// i.e. the trust region is active. +TEST_F(DoglegStrategyFixtureValley, CorrectStepLocalOptimumAlongGradient) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + options_.dogleg_type = SUBSPACE_DOGLEG; + options_.initial_radius = 0.25; + options_.max_radius = 0.25; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + TrustRegionStrategy::Summary summary = strategy.ComputeStep(pso, + jacobian_.get(), + residual_.data(), + x_.data()); + + EXPECT_NE(summary.termination_type, LINEAR_SOLVER_FAILURE); + EXPECT_NEAR(x_(0), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(1), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(2), options_.initial_radius, kToleranceLoose); + EXPECT_NEAR(x_(3), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(4), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(5), 0.0, kToleranceLoose); +} + +// Test if the step is correct if the gradient and the Gauss-Newton step point +// in the same direction and the Gauss-Newton step is inside the trust region, +// i.e. the trust region is inactive. +TEST_F(DoglegStrategyFixtureValley, CorrectStepGlobalOptimumAlongGradient) { + scoped_ptr linear_solver( + new DenseQRSolver(LinearSolver::Options())); + options_.linear_solver = linear_solver.get(); + options_.dogleg_type = SUBSPACE_DOGLEG; + options_.initial_radius = 2.0; + options_.max_radius = 2.0; + + DoglegStrategy strategy(options_); + TrustRegionStrategy::PerSolveOptions pso; + + TrustRegionStrategy::Summary summary = strategy.ComputeStep(pso, + jacobian_.get(), + residual_.data(), + x_.data()); + + EXPECT_NE(summary.termination_type, LINEAR_SOLVER_FAILURE); + EXPECT_NEAR(x_(0), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(1), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(2), 1.0, kToleranceLoose); + EXPECT_NEAR(x_(3), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(4), 0.0, kToleranceLoose); + EXPECT_NEAR(x_(5), 0.0, kToleranceLoose); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_autodiff_cost_function_test.cc b/internal/ceres/dynamic_autodiff_cost_function_test.cc new file mode 100644 index 0000000..ea51c2d --- /dev/null +++ b/internal/ceres/dynamic_autodiff_cost_function_test.cc @@ -0,0 +1,775 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: thadh@gmail.com (Thad Hughes) +// mierle@gmail.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) + +#include + +#include "ceres/dynamic_autodiff_cost_function.h" +#include "ceres/internal/scoped_ptr.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::vector; + +// Takes 2 parameter blocks: +// parameters[0] is size 10. +// parameters[1] is size 5. +// Emits 21 residuals: +// A: i - parameters[0][i], for i in [0,10) -- this is 10 residuals +// B: parameters[0][i] - i, for i in [0,10) -- this is another 10. +// C: sum(parameters[0][i]^2 - 8*parameters[0][i]) + sum(parameters[1][i]) +class MyCostFunctor { + public: + template + bool operator()(T const* const* parameters, T* residuals) const { + const T* params0 = parameters[0]; + int r = 0; + for (int i = 0; i < 10; ++i) { + residuals[r++] = T(i) - params0[i]; + residuals[r++] = params0[i] - T(i); + } + + T c_residual(0.0); + for (int i = 0; i < 10; ++i) { + c_residual += pow(params0[i], 2) - T(8) * params0[i]; + } + + const T* params1 = parameters[1]; + for (int i = 0; i < 5; ++i) { + c_residual += params1[i]; + } + residuals[r++] = c_residual; + return true; + } +}; + +TEST(DynamicAutodiffCostFunctionTest, TestResiduals) { + vector param_block_0(10, 0.0); + vector param_block_1(5, 0.0); + DynamicAutoDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Test residual computation. + vector residuals(21, -100000); + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + EXPECT_TRUE(cost_function.Evaluate(¶meter_blocks[0], + residuals.data(), + NULL)); + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(-1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(0, residuals.at(20)); +} + +TEST(DynamicAutodiffCostFunctionTest, TestJacobian) { + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicAutoDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(jacobian_vect[0].data()); + jacobian.push_back(jacobian_vect[1].data()); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + for (int p = 0; p < 10; ++p) { + // Check "A" Jacobian. + EXPECT_EQ(-1.0, jacobian_vect[0][2*p * 10 + p]); + // Check "B" Jacobian. + EXPECT_EQ(+1.0, jacobian_vect[0][(2*p+1) * 10 + p]); + jacobian_vect[0][2*p * 10 + p] = 0.0; + jacobian_vect[0][(2*p+1) * 10 + p] = 0.0; + } + + // Check "C" Jacobian for first parameter block. + for (int p = 0; p < 10; ++p) { + EXPECT_EQ(4 * p - 8, jacobian_vect[0][20 * 10 + p]); + jacobian_vect[0][20 * 10 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[0].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[0][i]); + } + + // Check "C" Jacobian for second parameter block. + for (int p = 0; p < 5; ++p) { + EXPECT_EQ(1.0, jacobian_vect[1][20 * 5 + p]); + jacobian_vect[1][20 * 5 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[1].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[1][i]); + } +} + +TEST(DynamicAutodiffCostFunctionTest, JacobianWithFirstParameterBlockConstant) { + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicAutoDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect[1].data()); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + + // Check "C" Jacobian for second parameter block. + for (int p = 0; p < 5; ++p) { + EXPECT_EQ(1.0, jacobian_vect[1][20 * 5 + p]); + jacobian_vect[1][20 * 5 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[1].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[1][i]); + } +} + +TEST(DynamicAutodiffCostFunctionTest, JacobianWithSecondParameterBlockConstant) { // NOLINT + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicAutoDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(jacobian_vect[0].data()); + jacobian.push_back(NULL); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + for (int p = 0; p < 10; ++p) { + // Check "A" Jacobian. + EXPECT_EQ(-1.0, jacobian_vect[0][2*p * 10 + p]); + // Check "B" Jacobian. + EXPECT_EQ(+1.0, jacobian_vect[0][(2*p+1) * 10 + p]); + jacobian_vect[0][2*p * 10 + p] = 0.0; + jacobian_vect[0][(2*p+1) * 10 + p] = 0.0; + } + + // Check "C" Jacobian for first parameter block. + for (int p = 0; p < 10; ++p) { + EXPECT_EQ(4 * p - 8, jacobian_vect[0][20 * 10 + p]); + jacobian_vect[0][20 * 10 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[0].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[0][i]); + } +} + +// Takes 3 parameter blocks: +// parameters[0] (x) is size 1. +// parameters[1] (y) is size 2. +// parameters[2] (z) is size 3. +// Emits 7 residuals: +// A: x[0] (= sum_x) +// B: y[0] + 2.0 * y[1] (= sum_y) +// C: z[0] + 3.0 * z[1] + 6.0 * z[2] (= sum_z) +// D: sum_x * sum_y +// E: sum_y * sum_z +// F: sum_x * sum_z +// G: sum_x * sum_y * sum_z +class MyThreeParameterCostFunctor { + public: + template + bool operator()(T const* const* parameters, T* residuals) const { + const T* x = parameters[0]; + const T* y = parameters[1]; + const T* z = parameters[2]; + + T sum_x = x[0]; + T sum_y = y[0] + 2.0 * y[1]; + T sum_z = z[0] + 3.0 * z[1] + 6.0 * z[2]; + + residuals[0] = sum_x; + residuals[1] = sum_y; + residuals[2] = sum_z; + residuals[3] = sum_x * sum_y; + residuals[4] = sum_y * sum_z; + residuals[5] = sum_x * sum_z; + residuals[6] = sum_x * sum_y * sum_z; + return true; + } +}; + +class ThreeParameterCostFunctorTest : public ::testing::Test { + protected: + virtual void SetUp() { + // Prepare the parameters. + x_.resize(1); + x_[0] = 0.0; + + y_.resize(2); + y_[0] = 1.0; + y_[1] = 3.0; + + z_.resize(3); + z_[0] = 2.0; + z_[1] = 4.0; + z_[2] = 6.0; + + parameter_blocks_.resize(3); + parameter_blocks_[0] = &x_[0]; + parameter_blocks_[1] = &y_[0]; + parameter_blocks_[2] = &z_[0]; + + // Prepare the cost function. + typedef DynamicAutoDiffCostFunction + DynamicMyThreeParameterCostFunction; + DynamicMyThreeParameterCostFunction * cost_function = + new DynamicMyThreeParameterCostFunction( + new MyThreeParameterCostFunctor()); + cost_function->AddParameterBlock(1); + cost_function->AddParameterBlock(2); + cost_function->AddParameterBlock(3); + cost_function->SetNumResiduals(7); + + cost_function_.reset(cost_function); + + // Setup jacobian data. + jacobian_vect_.resize(3); + jacobian_vect_[0].resize(7 * x_.size(), -100000); + jacobian_vect_[1].resize(7 * y_.size(), -100000); + jacobian_vect_[2].resize(7 * z_.size(), -100000); + + // Prepare the expected residuals. + const double sum_x = x_[0]; + const double sum_y = y_[0] + 2.0 * y_[1]; + const double sum_z = z_[0] + 3.0 * z_[1] + 6.0 * z_[2]; + + expected_residuals_.resize(7); + expected_residuals_[0] = sum_x; + expected_residuals_[1] = sum_y; + expected_residuals_[2] = sum_z; + expected_residuals_[3] = sum_x * sum_y; + expected_residuals_[4] = sum_y * sum_z; + expected_residuals_[5] = sum_x * sum_z; + expected_residuals_[6] = sum_x * sum_y * sum_z; + + // Prepare the expected jacobian entries. + expected_jacobian_x_.resize(7); + expected_jacobian_x_[0] = 1.0; + expected_jacobian_x_[1] = 0.0; + expected_jacobian_x_[2] = 0.0; + expected_jacobian_x_[3] = sum_y; + expected_jacobian_x_[4] = 0.0; + expected_jacobian_x_[5] = sum_z; + expected_jacobian_x_[6] = sum_y * sum_z; + + expected_jacobian_y_.resize(14); + expected_jacobian_y_[0] = 0.0; + expected_jacobian_y_[1] = 0.0; + expected_jacobian_y_[2] = 1.0; + expected_jacobian_y_[3] = 2.0; + expected_jacobian_y_[4] = 0.0; + expected_jacobian_y_[5] = 0.0; + expected_jacobian_y_[6] = sum_x; + expected_jacobian_y_[7] = 2.0 * sum_x; + expected_jacobian_y_[8] = sum_z; + expected_jacobian_y_[9] = 2.0 * sum_z; + expected_jacobian_y_[10] = 0.0; + expected_jacobian_y_[11] = 0.0; + expected_jacobian_y_[12] = sum_x * sum_z; + expected_jacobian_y_[13] = 2.0 * sum_x * sum_z; + + expected_jacobian_z_.resize(21); + expected_jacobian_z_[0] = 0.0; + expected_jacobian_z_[1] = 0.0; + expected_jacobian_z_[2] = 0.0; + expected_jacobian_z_[3] = 0.0; + expected_jacobian_z_[4] = 0.0; + expected_jacobian_z_[5] = 0.0; + expected_jacobian_z_[6] = 1.0; + expected_jacobian_z_[7] = 3.0; + expected_jacobian_z_[8] = 6.0; + expected_jacobian_z_[9] = 0.0; + expected_jacobian_z_[10] = 0.0; + expected_jacobian_z_[11] = 0.0; + expected_jacobian_z_[12] = sum_y; + expected_jacobian_z_[13] = 3.0 * sum_y; + expected_jacobian_z_[14] = 6.0 * sum_y; + expected_jacobian_z_[15] = sum_x; + expected_jacobian_z_[16] = 3.0 * sum_x; + expected_jacobian_z_[17] = 6.0 * sum_x; + expected_jacobian_z_[18] = sum_x * sum_y; + expected_jacobian_z_[19] = 3.0 * sum_x * sum_y; + expected_jacobian_z_[20] = 6.0 * sum_x * sum_y; + } + + protected: + vector x_; + vector y_; + vector z_; + + vector parameter_blocks_; + + scoped_ptr cost_function_; + + vector > jacobian_vect_; + + vector expected_residuals_; + + vector expected_jacobian_x_; + vector expected_jacobian_y_; + vector expected_jacobian_z_; +}; + +TEST_F(ThreeParameterCostFunctorTest, TestThreeParameterResiduals) { + vector residuals(7, -100000); + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + NULL)); + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } +} + +TEST_F(ThreeParameterCostFunctorTest, TestThreeParameterJacobian) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(jacobian_vect_[2].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_jacobian_x_[i], jacobian[0][i]); + } + + for (int i = 0; i < 14; ++i) { + EXPECT_EQ(expected_jacobian_y_[i], jacobian[1][i]); + } + + for (int i = 0; i < 21; ++i) { + EXPECT_EQ(expected_jacobian_z_[i], jacobian[2][i]); + } +} + +TEST_F(ThreeParameterCostFunctorTest, + ThreeParameterJacobianWithFirstAndLastParameterBlockConstant) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(NULL); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 14; ++i) { + EXPECT_EQ(expected_jacobian_y_[i], jacobian[1][i]); + } +} + +TEST_F(ThreeParameterCostFunctorTest, + ThreeParameterJacobianWithSecondParameterBlockConstant) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[2].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_jacobian_x_[i], jacobian[0][i]); + } + + for (int i = 0; i < 21; ++i) { + EXPECT_EQ(expected_jacobian_z_[i], jacobian[2][i]); + } +} + +// Takes 6 parameter blocks all of size 1: +// x0, y0, y1, z0, z1, z2 +// Same 7 residuals as MyThreeParameterCostFunctor. +// Naming convention for tests is (V)ariable and (C)onstant. +class MySixParameterCostFunctor { + public: + template + bool operator()(T const* const* parameters, T* residuals) const { + const T* x0 = parameters[0]; + const T* y0 = parameters[1]; + const T* y1 = parameters[2]; + const T* z0 = parameters[3]; + const T* z1 = parameters[4]; + const T* z2 = parameters[5]; + + T sum_x = x0[0]; + T sum_y = y0[0] + 2.0 * y1[0]; + T sum_z = z0[0] + 3.0 * z1[0] + 6.0 * z2[0]; + + residuals[0] = sum_x; + residuals[1] = sum_y; + residuals[2] = sum_z; + residuals[3] = sum_x * sum_y; + residuals[4] = sum_y * sum_z; + residuals[5] = sum_x * sum_z; + residuals[6] = sum_x * sum_y * sum_z; + return true; + } +}; + +class SixParameterCostFunctorTest : public ::testing::Test { + protected: + virtual void SetUp() { + // Prepare the parameters. + x0_ = 0.0; + y0_ = 1.0; + y1_ = 3.0; + z0_ = 2.0; + z1_ = 4.0; + z2_ = 6.0; + + parameter_blocks_.resize(6); + parameter_blocks_[0] = &x0_; + parameter_blocks_[1] = &y0_; + parameter_blocks_[2] = &y1_; + parameter_blocks_[3] = &z0_; + parameter_blocks_[4] = &z1_; + parameter_blocks_[5] = &z2_; + + // Prepare the cost function. + typedef DynamicAutoDiffCostFunction + DynamicMySixParameterCostFunction; + DynamicMySixParameterCostFunction * cost_function = + new DynamicMySixParameterCostFunction( + new MySixParameterCostFunctor()); + for (int i = 0; i < 6; ++i) { + cost_function->AddParameterBlock(1); + } + cost_function->SetNumResiduals(7); + + cost_function_.reset(cost_function); + + // Setup jacobian data. + jacobian_vect_.resize(6); + for (int i = 0; i < 6; ++i) { + jacobian_vect_[i].resize(7, -100000); + } + + // Prepare the expected residuals. + const double sum_x = x0_; + const double sum_y = y0_ + 2.0 * y1_; + const double sum_z = z0_ + 3.0 * z1_ + 6.0 * z2_; + + expected_residuals_.resize(7); + expected_residuals_[0] = sum_x; + expected_residuals_[1] = sum_y; + expected_residuals_[2] = sum_z; + expected_residuals_[3] = sum_x * sum_y; + expected_residuals_[4] = sum_y * sum_z; + expected_residuals_[5] = sum_x * sum_z; + expected_residuals_[6] = sum_x * sum_y * sum_z; + + // Prepare the expected jacobian entries. + expected_jacobians_.resize(6); + expected_jacobians_[0].resize(7); + expected_jacobians_[0][0] = 1.0; + expected_jacobians_[0][1] = 0.0; + expected_jacobians_[0][2] = 0.0; + expected_jacobians_[0][3] = sum_y; + expected_jacobians_[0][4] = 0.0; + expected_jacobians_[0][5] = sum_z; + expected_jacobians_[0][6] = sum_y * sum_z; + + expected_jacobians_[1].resize(7); + expected_jacobians_[1][0] = 0.0; + expected_jacobians_[1][1] = 1.0; + expected_jacobians_[1][2] = 0.0; + expected_jacobians_[1][3] = sum_x; + expected_jacobians_[1][4] = sum_z; + expected_jacobians_[1][5] = 0.0; + expected_jacobians_[1][6] = sum_x * sum_z; + + expected_jacobians_[2].resize(7); + expected_jacobians_[2][0] = 0.0; + expected_jacobians_[2][1] = 2.0; + expected_jacobians_[2][2] = 0.0; + expected_jacobians_[2][3] = 2.0 * sum_x; + expected_jacobians_[2][4] = 2.0 * sum_z; + expected_jacobians_[2][5] = 0.0; + expected_jacobians_[2][6] = 2.0 * sum_x * sum_z; + + expected_jacobians_[3].resize(7); + expected_jacobians_[3][0] = 0.0; + expected_jacobians_[3][1] = 0.0; + expected_jacobians_[3][2] = 1.0; + expected_jacobians_[3][3] = 0.0; + expected_jacobians_[3][4] = sum_y; + expected_jacobians_[3][5] = sum_x; + expected_jacobians_[3][6] = sum_x * sum_y; + + expected_jacobians_[4].resize(7); + expected_jacobians_[4][0] = 0.0; + expected_jacobians_[4][1] = 0.0; + expected_jacobians_[4][2] = 3.0; + expected_jacobians_[4][3] = 0.0; + expected_jacobians_[4][4] = 3.0 * sum_y; + expected_jacobians_[4][5] = 3.0 * sum_x; + expected_jacobians_[4][6] = 3.0 * sum_x * sum_y; + + expected_jacobians_[5].resize(7); + expected_jacobians_[5][0] = 0.0; + expected_jacobians_[5][1] = 0.0; + expected_jacobians_[5][2] = 6.0; + expected_jacobians_[5][3] = 0.0; + expected_jacobians_[5][4] = 6.0 * sum_y; + expected_jacobians_[5][5] = 6.0 * sum_x; + expected_jacobians_[5][6] = 6.0 * sum_x * sum_y; + } + + protected: + double x0_; + double y0_; + double y1_; + double z0_; + double z1_; + double z2_; + + vector parameter_blocks_; + + scoped_ptr cost_function_; + + vector > jacobian_vect_; + + vector expected_residuals_; + vector > expected_jacobians_; +}; + +TEST_F(SixParameterCostFunctorTest, TestSixParameterResiduals) { + vector residuals(7, -100000); + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + NULL)); + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } +} + +TEST_F(SixParameterCostFunctorTest, TestSixParameterJacobian) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(jacobian_vect_[2].data()); + jacobian.push_back(jacobian_vect_[3].data()); + jacobian.push_back(jacobian_vect_[4].data()); + jacobian.push_back(jacobian_vect_[5].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 6; ++i) { + for (int j = 0; j < 7; ++j) { + EXPECT_EQ(expected_jacobians_[i][j], jacobian[i][j]); + } + } +} + +TEST_F(SixParameterCostFunctorTest, TestSixParameterJacobianVVCVVC) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[3].data()); + jacobian.push_back(jacobian_vect_[4].data()); + jacobian.push_back(NULL); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 6; ++i) { + // Skip the constant variables. + if (i == 2 || i == 5) { + continue; + } + + for (int j = 0; j < 7; ++j) { + EXPECT_EQ(expected_jacobians_[i][j], jacobian[i][j]); + } + } +} + +TEST_F(SixParameterCostFunctorTest, TestSixParameterJacobianVCCVCV) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(NULL); + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[3].data()); + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[5].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 6; ++i) { + // Skip the constant variables. + if (i == 1 || i == 2 || i == 4) { + continue; + } + + for (int j = 0; j < 7; ++j) { + EXPECT_EQ(expected_jacobians_[i][j], jacobian[i][j]); + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_compressed_row_finalizer.h b/internal/ceres/dynamic_compressed_row_finalizer.h new file mode 100644 index 0000000..a25a308 --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_finalizer.h @@ -0,0 +1,51 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) + +#ifndef CERES_INTERNAL_DYNAMIC_COMPRESED_ROW_FINALIZER_H_ +#define CERES_INTERNAL_DYNAMIC_COMPRESED_ROW_FINALIZER_H_ + +#include "ceres/casts.h" +#include "ceres/dynamic_compressed_row_sparse_matrix.h" + +namespace ceres { +namespace internal { + +struct DynamicCompressedRowJacobianFinalizer { + void operator()(SparseMatrix* base_jacobian, int num_parameters) { + DynamicCompressedRowSparseMatrix* jacobian = + down_cast(base_jacobian); + jacobian->Finalize(num_parameters); + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DYNAMIC_COMPRESED_ROW_FINALISER_H_ diff --git a/internal/ceres/dynamic_compressed_row_jacobian_writer.cc b/internal/ceres/dynamic_compressed_row_jacobian_writer.cc new file mode 100644 index 0000000..4f89145 --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_jacobian_writer.cc @@ -0,0 +1,102 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) + +#include "ceres/dynamic_compressed_row_jacobian_writer.h" +#include "ceres/casts.h" +#include "ceres/compressed_row_jacobian_writer.h" +#include "ceres/dynamic_compressed_row_sparse_matrix.h" +#include "ceres/parameter_block.h" +#include "ceres/program.h" +#include "ceres/residual_block.h" + +namespace ceres { +namespace internal { + +using std::pair; +using std::vector; + +ScratchEvaluatePreparer* +DynamicCompressedRowJacobianWriter::CreateEvaluatePreparers(int num_threads) { + return ScratchEvaluatePreparer::Create(*program_, num_threads); +} + +SparseMatrix* DynamicCompressedRowJacobianWriter::CreateJacobian() const { + DynamicCompressedRowSparseMatrix* jacobian = + new DynamicCompressedRowSparseMatrix(program_->NumResiduals(), + program_->NumEffectiveParameters(), + 0 /* max_num_nonzeros */); + return jacobian; +} + +void DynamicCompressedRowJacobianWriter::Write(int residual_id, + int residual_offset, + double** jacobians, + SparseMatrix* base_jacobian) { + DynamicCompressedRowSparseMatrix* jacobian = + down_cast(base_jacobian); + + // Get the `residual_block` of interest. + const ResidualBlock* residual_block = + program_->residual_blocks()[residual_id]; + const int num_residuals = residual_block->NumResiduals(); + + vector > evaluated_jacobian_blocks; + CompressedRowJacobianWriter::GetOrderedParameterBlocks( + program_, residual_id, &evaluated_jacobian_blocks); + + // `residual_offset` is the residual row in the global jacobian. + // Empty the jacobian rows. + jacobian->ClearRows(residual_offset, num_residuals); + + // Iterate over each parameter block. + for (int i = 0; i < evaluated_jacobian_blocks.size(); ++i) { + const ParameterBlock* parameter_block = + program_->parameter_blocks()[evaluated_jacobian_blocks[i].first]; + const int parameter_block_jacobian_index = + evaluated_jacobian_blocks[i].second; + const int parameter_block_size = parameter_block->LocalSize(); + + // For each parameter block only insert its non-zero entries. + for (int r = 0; r < num_residuals; ++r) { + for (int c = 0; c < parameter_block_size; ++c) { + const double& v = jacobians[parameter_block_jacobian_index] + [r * parameter_block_size + c]; + // Only insert non-zero entries. + if (v != 0.0) { + jacobian->InsertEntry( + residual_offset + r, parameter_block->delta_offset() + c, v); + } + } + } + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_compressed_row_jacobian_writer.h b/internal/ceres/dynamic_compressed_row_jacobian_writer.h new file mode 100644 index 0000000..6e5ac38 --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_jacobian_writer.h @@ -0,0 +1,83 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) +// +// A jacobian writer that directly writes to dynamic compressed row sparse +// matrices. + +#ifndef CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_JACOBIAN_WRITER_H_ +#define CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_JACOBIAN_WRITER_H_ + +#include "ceres/evaluator.h" +#include "ceres/scratch_evaluate_preparer.h" + +namespace ceres { +namespace internal { + +class Program; +class SparseMatrix; + +class DynamicCompressedRowJacobianWriter { + public: + DynamicCompressedRowJacobianWriter(Evaluator::Options /* ignored */, + Program* program) + : program_(program) { + } + + // JacobianWriter interface. + + // The compressed row matrix has different layout than that assumed by + // the cost functions. The scratch space is therefore used to store + // the jacobians (including zeros) temporarily before only the non-zero + // entries are copied over to the larger jacobian in `Write`. + ScratchEvaluatePreparer* CreateEvaluatePreparers(int num_threads); + + // Return a `DynamicCompressedRowSparseMatrix` which is filled by + // `Write`. Note that `Finalize` must be called to make the + // `CompressedRowSparseMatrix` interface valid. + SparseMatrix* CreateJacobian() const; + + // Write only the non-zero jacobian entries for a residual block + // (specified by `residual_id`) into `base_jacobian`, starting at the row + // specifed by `residual_offset`. + // + // This method is thread-safe over residual blocks (each `residual_id`). + void Write(int residual_id, + int residual_offset, + double **jacobians, + SparseMatrix* base_jacobian); + + private: + Program* program_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_JACOBIAN_WRITER_H_ diff --git a/internal/ceres/dynamic_compressed_row_sparse_matrix.cc b/internal/ceres/dynamic_compressed_row_sparse_matrix.cc new file mode 100644 index 0000000..f020768 --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_sparse_matrix.cc @@ -0,0 +1,107 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) + +#include +#include "ceres/dynamic_compressed_row_sparse_matrix.h" + +namespace ceres { +namespace internal { + +DynamicCompressedRowSparseMatrix::DynamicCompressedRowSparseMatrix( + int num_rows, + int num_cols, + int initial_max_num_nonzeros) + : CompressedRowSparseMatrix(num_rows, + num_cols, + initial_max_num_nonzeros) { + dynamic_cols_.resize(num_rows); + dynamic_values_.resize(num_rows); + } + +void DynamicCompressedRowSparseMatrix::InsertEntry(int row, + int col, + const double& value) { + CHECK_GE(row, 0); + CHECK_LT(row, num_rows()); + CHECK_GE(col, 0); + CHECK_LT(col, num_cols()); + dynamic_cols_[row].push_back(col); + dynamic_values_[row].push_back(value); +} + +void DynamicCompressedRowSparseMatrix::ClearRows(int row_start, + int num_rows) { + for (int r = 0; r < num_rows; ++r) { + const int i = row_start + r; + CHECK_GE(i, 0); + CHECK_LT(i, this->num_rows()); + dynamic_cols_[i].resize(0); + dynamic_values_[i].resize(0); + } +} + +void DynamicCompressedRowSparseMatrix::Finalize(int num_additional_elements) { + // `num_additional_elements` is provided as an argument so that additional + // storage can be reserved when it is known by the finalizer. + CHECK_GE(num_additional_elements, 0); + + // Count the number of non-zeros and resize `cols_` and `values_`. + int num_jacobian_nonzeros = 0; + for (int i = 0; i < dynamic_cols_.size(); ++i) { + num_jacobian_nonzeros += dynamic_cols_[i].size(); + } + + SetMaxNumNonZeros(num_jacobian_nonzeros + num_additional_elements); + + // Flatten `dynamic_cols_` into `cols_` and `dynamic_values_` + // into `values_`. + int index_into_values_and_cols = 0; + for (int i = 0; i < num_rows(); ++i) { + mutable_rows()[i] = index_into_values_and_cols; + const int num_nonzero_columns = dynamic_cols_[i].size(); + if (num_nonzero_columns > 0) { + memcpy(mutable_cols() + index_into_values_and_cols, + &dynamic_cols_[i][0], + dynamic_cols_[i].size() * sizeof(dynamic_cols_[0][0])); + memcpy(mutable_values() + index_into_values_and_cols, + &dynamic_values_[i][0], + dynamic_values_[i].size() * sizeof(dynamic_values_[0][0])); + index_into_values_and_cols += dynamic_cols_[i].size(); + } + } + mutable_rows()[num_rows()] = index_into_values_and_cols; + + CHECK_EQ(index_into_values_and_cols, num_jacobian_nonzeros) + << "Ceres bug: final index into values_ and cols_ should be equal to " + << "the number of jacobian nonzeros. Please contact the developers!"; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_compressed_row_sparse_matrix.h b/internal/ceres/dynamic_compressed_row_sparse_matrix.h new file mode 100644 index 0000000..cab860b --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_sparse_matrix.h @@ -0,0 +1,101 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) +// +// A compressed row sparse matrix that provides an extended interface to +// allow dynamic insertion of entries. This is provided for the use case +// where the sparsity structure and number of non-zero entries is dynamic. +// This flexibility is achieved by using an (internal) scratch space that +// allows independent insertion of entries into each row (thread-safe). +// Once insertion is complete, the `Finalize` method must be called to ensure +// that the underlying `CompressedRowSparseMatrix` is consistent. +// +// This should only be used if you really do need a dynamic sparsity pattern. + +#ifndef CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_SPARSE_MATRIX_H_ +#define CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_SPARSE_MATRIX_H_ + +#include + +#include "ceres/compressed_row_sparse_matrix.h" + +namespace ceres { +namespace internal { + +class DynamicCompressedRowSparseMatrix : public CompressedRowSparseMatrix { + public: + // Set the number of rows and columns for the underlyig + // `CompressedRowSparseMatrix` and set the initial number of maximum non-zero + // entries. Note that following the insertion of entries, when `Finalize` + // is called the number of non-zeros is determined and all internal + // structures are adjusted as required. If you know the upper limit on the + // number of non-zeros, then passing this value here can prevent future + // memory reallocations which may improve performance. Otherwise, if no + // upper limit is available a value of 0 is sufficient. + // + // Typical usage of this class is to define a new instance with a given + // number of rows, columns and maximum number of non-zero elements + // (if available). Next, entries are inserted at row and column positions + // using `InsertEntry`. Finally, once all elements have been inserted, + // `Finalize` must be called to make the underlying + // `CompressedRowSparseMatrix` consistent. + DynamicCompressedRowSparseMatrix(int num_rows, + int num_cols, + int initial_max_num_nonzeros); + + // Insert an entry at a given row and column position. This method is + // thread-safe across rows i.e. different threads can insert values + // simultaneously into different rows. It should be emphasised that this + // method always inserts a new entry and does not check for existing + // entries at the specified row and column position. Duplicate entries + // for a given row and column position will result in undefined + // behavior. + void InsertEntry(int row, int col, const double& value); + + // Clear all entries for rows, starting from row index `row_start` + // and proceeding for `num_rows`. + void ClearRows(int row_start, int num_rows); + + // Make the underlying internal `CompressedRowSparseMatrix` data structures + // consistent. Additional space for non-zero entries in the + // `CompressedRowSparseMatrix` can be reserved by specifying + // `num_additional_elements`. This is useful when it is known that rows will + // be appended to the `CompressedRowSparseMatrix` (e.g. appending a diagonal + // matrix to the jacobian) as it prevents need for future reallocation. + void Finalize(int num_additional_elements); + + private: + std::vector > dynamic_cols_; + std::vector > dynamic_values_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DYNAMIC_COMPRESSED_ROW_SPARSE_MATRIX_H_ diff --git a/internal/ceres/dynamic_compressed_row_sparse_matrix_test.cc b/internal/ceres/dynamic_compressed_row_sparse_matrix_test.cc new file mode 100644 index 0000000..4030142 --- /dev/null +++ b/internal/ceres/dynamic_compressed_row_sparse_matrix_test.cc @@ -0,0 +1,219 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) + +#include "ceres/dynamic_compressed_row_sparse_matrix.h" + +#include "ceres/casts.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/triplet_sparse_matrix.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::copy; +using std::vector; + +class DynamicCompressedRowSparseMatrixTest : public ::testing::Test { + protected: + virtual void SetUp() { + num_rows = 7; + num_cols = 4; + + // The number of additional elements reserved when `Finalize` is called + // should have no effect on the number of rows, columns or nonzeros. + // Set this to some nonzero value to be sure. + num_additional_elements = 13; + + expected_num_nonzeros = num_rows * num_cols - std::min(num_rows, num_cols); + + InitialiseDenseReference(); + InitialiseSparseMatrixReferences(); + + dcrsm.reset(new DynamicCompressedRowSparseMatrix(num_rows, + num_cols, + 0)); + } + + void Finalize() { + dcrsm->Finalize(num_additional_elements); + } + + void InitialiseDenseReference() { + dense.resize(num_rows, num_cols); + dense.setZero(); + int num_nonzeros = 0; + for (int i = 0; i < (num_rows * num_cols); ++i) { + const int r = i / num_cols, c = i % num_cols; + if (r != c) { + dense(r, c) = i + 1; + ++num_nonzeros; + } + } + ASSERT_EQ(num_nonzeros, expected_num_nonzeros); + } + + void InitialiseSparseMatrixReferences() { + vector rows, cols; + vector values; + for (int i = 0; i < (num_rows * num_cols); ++i) { + const int r = i / num_cols, c = i % num_cols; + if (r != c) { + rows.push_back(r); + cols.push_back(c); + values.push_back(i + 1); + } + } + ASSERT_EQ(values.size(), expected_num_nonzeros); + + tsm.reset(new TripletSparseMatrix(num_rows, + num_cols, + expected_num_nonzeros)); + copy(rows.begin(), rows.end(), tsm->mutable_rows()); + copy(cols.begin(), cols.end(), tsm->mutable_cols()); + copy(values.begin(), values.end(), tsm->mutable_values()); + tsm->set_num_nonzeros(values.size()); + + Matrix dense_from_tsm; + tsm->ToDenseMatrix(&dense_from_tsm); + ASSERT_TRUE((dense.array() == dense_from_tsm.array()).all()); + + crsm.reset(CompressedRowSparseMatrix::FromTripletSparseMatrix(*tsm)); + Matrix dense_from_crsm; + crsm->ToDenseMatrix(&dense_from_crsm); + ASSERT_TRUE((dense.array() == dense_from_crsm.array()).all()); + } + + void InsertNonZeroEntriesFromDenseReference() { + for (int r = 0; r < num_rows; ++r) { + for (int c = 0; c < num_cols; ++c) { + const double& v = dense(r, c); + if (v != 0.0) { + dcrsm->InsertEntry(r, c, v); + } + } + } + } + + void ExpectEmpty() { + EXPECT_EQ(dcrsm->num_rows(), num_rows); + EXPECT_EQ(dcrsm->num_cols(), num_cols); + EXPECT_EQ(dcrsm->num_nonzeros(), 0); + + Matrix dense_from_dcrsm; + dcrsm->ToDenseMatrix(&dense_from_dcrsm); + EXPECT_EQ(dense_from_dcrsm.rows(), num_rows); + EXPECT_EQ(dense_from_dcrsm.cols(), num_cols); + EXPECT_TRUE((dense_from_dcrsm.array() == 0.0).all()); + } + + void ExpectEqualToDenseReference() { + Matrix dense_from_dcrsm; + dcrsm->ToDenseMatrix(&dense_from_dcrsm); + EXPECT_TRUE((dense.array() == dense_from_dcrsm.array()).all()); + } + + void ExpectEqualToCompressedRowSparseMatrixReference() { + typedef Eigen::Map ConstIntVectorRef; + + ConstIntVectorRef crsm_rows(crsm->rows(), crsm->num_rows() + 1); + ConstIntVectorRef dcrsm_rows(dcrsm->rows(), dcrsm->num_rows() + 1); + EXPECT_TRUE((crsm_rows.array() == dcrsm_rows.array()).all()); + + ConstIntVectorRef crsm_cols(crsm->cols(), crsm->num_nonzeros()); + ConstIntVectorRef dcrsm_cols(dcrsm->cols(), dcrsm->num_nonzeros()); + EXPECT_TRUE((crsm_cols.array() == dcrsm_cols.array()).all()); + + ConstVectorRef crsm_values(crsm->values(), crsm->num_nonzeros()); + ConstVectorRef dcrsm_values(dcrsm->values(), dcrsm->num_nonzeros()); + EXPECT_TRUE((crsm_values.array() == dcrsm_values.array()).all()); + } + + int num_rows; + int num_cols; + + int num_additional_elements; + + int expected_num_nonzeros; + + Matrix dense; + scoped_ptr tsm; + scoped_ptr crsm; + + scoped_ptr dcrsm; +}; + +TEST_F(DynamicCompressedRowSparseMatrixTest, Initialization) { + ExpectEmpty(); + + Finalize(); + ExpectEmpty(); +} + +TEST_F(DynamicCompressedRowSparseMatrixTest, InsertEntryAndFinalize) { + InsertNonZeroEntriesFromDenseReference(); + ExpectEmpty(); + + Finalize(); + ExpectEqualToDenseReference(); + ExpectEqualToCompressedRowSparseMatrixReference(); +} + +TEST_F(DynamicCompressedRowSparseMatrixTest, ClearRows) { + InsertNonZeroEntriesFromDenseReference(); + Finalize(); + ExpectEqualToDenseReference(); + ExpectEqualToCompressedRowSparseMatrixReference(); + + dcrsm->ClearRows(0, 0); + Finalize(); + ExpectEqualToDenseReference(); + ExpectEqualToCompressedRowSparseMatrixReference(); + + dcrsm->ClearRows(0, num_rows); + ExpectEqualToCompressedRowSparseMatrixReference(); + + Finalize(); + ExpectEmpty(); + + InsertNonZeroEntriesFromDenseReference(); + dcrsm->ClearRows(1, 2); + Finalize(); + dense.block(1, 0, 2, num_cols).setZero(); + ExpectEqualToDenseReference(); + + InitialiseDenseReference(); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_numeric_diff_cost_function_test.cc b/internal/ceres/dynamic_numeric_diff_cost_function_test.cc new file mode 100644 index 0000000..760fdeb --- /dev/null +++ b/internal/ceres/dynamic_numeric_diff_cost_function_test.cc @@ -0,0 +1,521 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// mierle@gmail.com (Keir Mierle) + +#include + +#include "ceres/dynamic_numeric_diff_cost_function.h" +#include "ceres/internal/scoped_ptr.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::vector; + +const double kTolerance = 1e-6; + +// Takes 2 parameter blocks: +// parameters[0] is size 10. +// parameters[1] is size 5. +// Emits 21 residuals: +// A: i - parameters[0][i], for i in [0,10) -- this is 10 residuals +// B: parameters[0][i] - i, for i in [0,10) -- this is another 10. +// C: sum(parameters[0][i]^2 - 8*parameters[0][i]) + sum(parameters[1][i]) +class MyCostFunctor { + public: + bool operator()(double const* const* parameters, double* residuals) const { + const double* params0 = parameters[0]; + int r = 0; + for (int i = 0; i < 10; ++i) { + residuals[r++] = i - params0[i]; + residuals[r++] = params0[i] - i; + } + + double c_residual = 0.0; + for (int i = 0; i < 10; ++i) { + c_residual += pow(params0[i], 2) - 8.0 * params0[i]; + } + + const double* params1 = parameters[1]; + for (int i = 0; i < 5; ++i) { + c_residual += params1[i]; + } + residuals[r++] = c_residual; + return true; + } +}; + +TEST(DynamicNumericdiffCostFunctionTest, TestResiduals) { + vector param_block_0(10, 0.0); + vector param_block_1(5, 0.0); + DynamicNumericDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Test residual computation. + vector residuals(21, -100000); + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + EXPECT_TRUE(cost_function.Evaluate(¶meter_blocks[0], + residuals.data(), + NULL)); + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(-1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(0, residuals.at(20)); +} + + +TEST(DynamicNumericdiffCostFunctionTest, TestJacobian) { + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicNumericDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(jacobian_vect[0].data()); + jacobian.push_back(jacobian_vect[1].data()); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + for (int p = 0; p < 10; ++p) { + // Check "A" Jacobian. + EXPECT_NEAR(-1.0, jacobian_vect[0][2*p * 10 + p], kTolerance); + // Check "B" Jacobian. + EXPECT_NEAR(+1.0, jacobian_vect[0][(2*p+1) * 10 + p], kTolerance); + jacobian_vect[0][2*p * 10 + p] = 0.0; + jacobian_vect[0][(2*p+1) * 10 + p] = 0.0; + } + + // Check "C" Jacobian for first parameter block. + for (int p = 0; p < 10; ++p) { + EXPECT_NEAR(4 * p - 8, jacobian_vect[0][20 * 10 + p], kTolerance); + jacobian_vect[0][20 * 10 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[0].size(); ++i) { + EXPECT_NEAR(0.0, jacobian_vect[0][i], kTolerance); + } + + // Check "C" Jacobian for second parameter block. + for (int p = 0; p < 5; ++p) { + EXPECT_NEAR(1.0, jacobian_vect[1][20 * 5 + p], kTolerance); + jacobian_vect[1][20 * 5 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[1].size(); ++i) { + EXPECT_NEAR(0.0, jacobian_vect[1][i], kTolerance); + } +} + +TEST(DynamicNumericdiffCostFunctionTest, JacobianWithFirstParameterBlockConstant) { // NOLINT + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicNumericDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect[1].data()); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + + // Check "C" Jacobian for second parameter block. + for (int p = 0; p < 5; ++p) { + EXPECT_NEAR(1.0, jacobian_vect[1][20 * 5 + p], kTolerance); + jacobian_vect[1][20 * 5 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[1].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[1][i]); + } +} + +TEST(DynamicNumericdiffCostFunctionTest, JacobianWithSecondParameterBlockConstant) { // NOLINT + // Test the residual counting. + vector param_block_0(10, 0.0); + for (int i = 0; i < 10; ++i) { + param_block_0[i] = 2 * i; + } + vector param_block_1(5, 0.0); + DynamicNumericDiffCostFunction cost_function( + new MyCostFunctor()); + cost_function.AddParameterBlock(param_block_0.size()); + cost_function.AddParameterBlock(param_block_1.size()); + cost_function.SetNumResiduals(21); + + // Prepare the residuals. + vector residuals(21, -100000); + + // Prepare the parameters. + vector parameter_blocks(2); + parameter_blocks[0] = ¶m_block_0[0]; + parameter_blocks[1] = ¶m_block_1[0]; + + // Prepare the jacobian. + vector > jacobian_vect(2); + jacobian_vect[0].resize(21 * 10, -100000); + jacobian_vect[1].resize(21 * 5, -100000); + vector jacobian; + jacobian.push_back(jacobian_vect[0].data()); + jacobian.push_back(NULL); + + // Test jacobian computation. + EXPECT_TRUE(cost_function.Evaluate(parameter_blocks.data(), + residuals.data(), + jacobian.data())); + + for (int r = 0; r < 10; ++r) { + EXPECT_EQ(-1.0 * r, residuals.at(r * 2)); + EXPECT_EQ(+1.0 * r, residuals.at(r * 2 + 1)); + } + EXPECT_EQ(420, residuals.at(20)); + for (int p = 0; p < 10; ++p) { + // Check "A" Jacobian. + EXPECT_NEAR(-1.0, jacobian_vect[0][2*p * 10 + p], kTolerance); + // Check "B" Jacobian. + EXPECT_NEAR(+1.0, jacobian_vect[0][(2*p+1) * 10 + p], kTolerance); + jacobian_vect[0][2*p * 10 + p] = 0.0; + jacobian_vect[0][(2*p+1) * 10 + p] = 0.0; + } + + // Check "C" Jacobian for first parameter block. + for (int p = 0; p < 10; ++p) { + EXPECT_NEAR(4 * p - 8, jacobian_vect[0][20 * 10 + p], kTolerance); + jacobian_vect[0][20 * 10 + p] = 0.0; + } + for (int i = 0; i < jacobian_vect[0].size(); ++i) { + EXPECT_EQ(0.0, jacobian_vect[0][i]); + } +} + +// Takes 3 parameter blocks: +// parameters[0] (x) is size 1. +// parameters[1] (y) is size 2. +// parameters[2] (z) is size 3. +// Emits 7 residuals: +// A: x[0] (= sum_x) +// B: y[0] + 2.0 * y[1] (= sum_y) +// C: z[0] + 3.0 * z[1] + 6.0 * z[2] (= sum_z) +// D: sum_x * sum_y +// E: sum_y * sum_z +// F: sum_x * sum_z +// G: sum_x * sum_y * sum_z +class MyThreeParameterCostFunctor { + public: + template + bool operator()(T const* const* parameters, T* residuals) const { + const T* x = parameters[0]; + const T* y = parameters[1]; + const T* z = parameters[2]; + + T sum_x = x[0]; + T sum_y = y[0] + 2.0 * y[1]; + T sum_z = z[0] + 3.0 * z[1] + 6.0 * z[2]; + + residuals[0] = sum_x; + residuals[1] = sum_y; + residuals[2] = sum_z; + residuals[3] = sum_x * sum_y; + residuals[4] = sum_y * sum_z; + residuals[5] = sum_x * sum_z; + residuals[6] = sum_x * sum_y * sum_z; + return true; + } +}; + +class ThreeParameterCostFunctorTest : public ::testing::Test { + protected: + virtual void SetUp() { + // Prepare the parameters. + x_.resize(1); + x_[0] = 0.0; + + y_.resize(2); + y_[0] = 1.0; + y_[1] = 3.0; + + z_.resize(3); + z_[0] = 2.0; + z_[1] = 4.0; + z_[2] = 6.0; + + parameter_blocks_.resize(3); + parameter_blocks_[0] = &x_[0]; + parameter_blocks_[1] = &y_[0]; + parameter_blocks_[2] = &z_[0]; + + // Prepare the cost function. + typedef DynamicNumericDiffCostFunction + DynamicMyThreeParameterCostFunction; + DynamicMyThreeParameterCostFunction * cost_function = + new DynamicMyThreeParameterCostFunction( + new MyThreeParameterCostFunctor()); + cost_function->AddParameterBlock(1); + cost_function->AddParameterBlock(2); + cost_function->AddParameterBlock(3); + cost_function->SetNumResiduals(7); + + cost_function_.reset(cost_function); + + // Setup jacobian data. + jacobian_vect_.resize(3); + jacobian_vect_[0].resize(7 * x_.size(), -100000); + jacobian_vect_[1].resize(7 * y_.size(), -100000); + jacobian_vect_[2].resize(7 * z_.size(), -100000); + + // Prepare the expected residuals. + const double sum_x = x_[0]; + const double sum_y = y_[0] + 2.0 * y_[1]; + const double sum_z = z_[0] + 3.0 * z_[1] + 6.0 * z_[2]; + + expected_residuals_.resize(7); + expected_residuals_[0] = sum_x; + expected_residuals_[1] = sum_y; + expected_residuals_[2] = sum_z; + expected_residuals_[3] = sum_x * sum_y; + expected_residuals_[4] = sum_y * sum_z; + expected_residuals_[5] = sum_x * sum_z; + expected_residuals_[6] = sum_x * sum_y * sum_z; + + // Prepare the expected jacobian entries. + expected_jacobian_x_.resize(7); + expected_jacobian_x_[0] = 1.0; + expected_jacobian_x_[1] = 0.0; + expected_jacobian_x_[2] = 0.0; + expected_jacobian_x_[3] = sum_y; + expected_jacobian_x_[4] = 0.0; + expected_jacobian_x_[5] = sum_z; + expected_jacobian_x_[6] = sum_y * sum_z; + + expected_jacobian_y_.resize(14); + expected_jacobian_y_[0] = 0.0; + expected_jacobian_y_[1] = 0.0; + expected_jacobian_y_[2] = 1.0; + expected_jacobian_y_[3] = 2.0; + expected_jacobian_y_[4] = 0.0; + expected_jacobian_y_[5] = 0.0; + expected_jacobian_y_[6] = sum_x; + expected_jacobian_y_[7] = 2.0 * sum_x; + expected_jacobian_y_[8] = sum_z; + expected_jacobian_y_[9] = 2.0 * sum_z; + expected_jacobian_y_[10] = 0.0; + expected_jacobian_y_[11] = 0.0; + expected_jacobian_y_[12] = sum_x * sum_z; + expected_jacobian_y_[13] = 2.0 * sum_x * sum_z; + + expected_jacobian_z_.resize(21); + expected_jacobian_z_[0] = 0.0; + expected_jacobian_z_[1] = 0.0; + expected_jacobian_z_[2] = 0.0; + expected_jacobian_z_[3] = 0.0; + expected_jacobian_z_[4] = 0.0; + expected_jacobian_z_[5] = 0.0; + expected_jacobian_z_[6] = 1.0; + expected_jacobian_z_[7] = 3.0; + expected_jacobian_z_[8] = 6.0; + expected_jacobian_z_[9] = 0.0; + expected_jacobian_z_[10] = 0.0; + expected_jacobian_z_[11] = 0.0; + expected_jacobian_z_[12] = sum_y; + expected_jacobian_z_[13] = 3.0 * sum_y; + expected_jacobian_z_[14] = 6.0 * sum_y; + expected_jacobian_z_[15] = sum_x; + expected_jacobian_z_[16] = 3.0 * sum_x; + expected_jacobian_z_[17] = 6.0 * sum_x; + expected_jacobian_z_[18] = sum_x * sum_y; + expected_jacobian_z_[19] = 3.0 * sum_x * sum_y; + expected_jacobian_z_[20] = 6.0 * sum_x * sum_y; + } + + protected: + vector x_; + vector y_; + vector z_; + + vector parameter_blocks_; + + scoped_ptr cost_function_; + + vector > jacobian_vect_; + + vector expected_residuals_; + + vector expected_jacobian_x_; + vector expected_jacobian_y_; + vector expected_jacobian_z_; +}; + +TEST_F(ThreeParameterCostFunctorTest, TestThreeParameterResiduals) { + vector residuals(7, -100000); + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + NULL)); + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } +} + +TEST_F(ThreeParameterCostFunctorTest, TestThreeParameterJacobian) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(jacobian_vect_[2].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 7; ++i) { + EXPECT_NEAR(expected_jacobian_x_[i], jacobian[0][i], kTolerance); + } + + for (int i = 0; i < 14; ++i) { + EXPECT_NEAR(expected_jacobian_y_[i], jacobian[1][i], kTolerance); + } + + for (int i = 0; i < 21; ++i) { + EXPECT_NEAR(expected_jacobian_z_[i], jacobian[2][i], kTolerance); + } +} + +TEST_F(ThreeParameterCostFunctorTest, + ThreeParameterJacobianWithFirstAndLastParameterBlockConstant) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[1].data()); + jacobian.push_back(NULL); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 14; ++i) { + EXPECT_NEAR(expected_jacobian_y_[i], jacobian[1][i], kTolerance); + } +} + +TEST_F(ThreeParameterCostFunctorTest, + ThreeParameterJacobianWithSecondParameterBlockConstant) { + vector residuals(7, -100000); + + vector jacobian; + jacobian.push_back(jacobian_vect_[0].data()); + jacobian.push_back(NULL); + jacobian.push_back(jacobian_vect_[2].data()); + + EXPECT_TRUE(cost_function_->Evaluate(parameter_blocks_.data(), + residuals.data(), + jacobian.data())); + + for (int i = 0; i < 7; ++i) { + EXPECT_EQ(expected_residuals_[i], residuals[i]); + } + + for (int i = 0; i < 7; ++i) { + EXPECT_NEAR(expected_jacobian_x_[i], jacobian[0][i], kTolerance); + } + + for (int i = 0; i < 21; ++i) { + EXPECT_NEAR(expected_jacobian_z_[i], jacobian[2][i], kTolerance); + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_sparse_normal_cholesky_solver.cc b/internal/ceres/dynamic_sparse_normal_cholesky_solver.cc new file mode 100644 index 0000000..6d39616 --- /dev/null +++ b/internal/ceres/dynamic_sparse_normal_cholesky_solver.cc @@ -0,0 +1,285 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/dynamic_sparse_normal_cholesky_solver.h" + +#include +#include +#include +#include + +#include "Eigen/SparseCore" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/cxsparse.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_solver.h" +#include "ceres/suitesparse.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/types.h" +#include "ceres/wall_time.h" + +#ifdef CERES_USE_EIGEN_SPARSE +#include "Eigen/SparseCholesky" +#endif + +namespace ceres { +namespace internal { + +DynamicSparseNormalCholeskySolver::DynamicSparseNormalCholeskySolver( + const LinearSolver::Options& options) + : options_(options) {} + +LinearSolver::Summary DynamicSparseNormalCholeskySolver::SolveImpl( + CompressedRowSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& per_solve_options, + double* x) { + const int num_cols = A->num_cols(); + VectorRef(x, num_cols).setZero(); + A->LeftMultiply(b, x); + + if (per_solve_options.D != NULL) { + // Temporarily append a diagonal block to the A matrix, but undo + // it before returning the matrix to the user. + scoped_ptr regularizer; + if (!A->col_blocks().empty()) { + regularizer.reset(CompressedRowSparseMatrix::CreateBlockDiagonalMatrix( + per_solve_options.D, A->col_blocks())); + } else { + regularizer.reset( + new CompressedRowSparseMatrix(per_solve_options.D, num_cols)); + } + A->AppendRows(*regularizer); + } + + LinearSolver::Summary summary; + switch (options_.sparse_linear_algebra_library_type) { + case SUITE_SPARSE: + summary = SolveImplUsingSuiteSparse(A, x); + break; + case CX_SPARSE: + summary = SolveImplUsingCXSparse(A, x); + break; + case EIGEN_SPARSE: + summary = SolveImplUsingEigen(A, x); + break; + default: + LOG(FATAL) << "Unknown sparse linear algebra library : " + << options_.sparse_linear_algebra_library_type; + } + + if (per_solve_options.D != NULL) { + A->DeleteRows(num_cols); + } + + return summary; +} + +LinearSolver::Summary DynamicSparseNormalCholeskySolver::SolveImplUsingEigen( + CompressedRowSparseMatrix* A, double* rhs_and_solution) { +#ifndef CERES_USE_EIGEN_SPARSE + + LinearSolver::Summary summary; + summary.num_iterations = 0; + summary.termination_type = LINEAR_SOLVER_FATAL_ERROR; + summary.message = + "SPARSE_NORMAL_CHOLESKY cannot be used with EIGEN_SPARSE " + "because Ceres was not built with support for " + "Eigen's SimplicialLDLT decomposition. " + "This requires enabling building with -DEIGENSPARSE=ON."; + return summary; + +#else + + EventLogger event_logger("DynamicSparseNormalCholeskySolver::Eigen::Solve"); + + Eigen::MappedSparseMatrix a(A->num_rows(), + A->num_cols(), + A->num_nonzeros(), + A->mutable_rows(), + A->mutable_cols(), + A->mutable_values()); + + Eigen::SparseMatrix lhs = a.transpose() * a; + Eigen::SimplicialLDLT > solver; + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = "Success."; + + solver.analyzePattern(lhs); + if (VLOG_IS_ON(2)) { + std::stringstream ss; + solver.dumpMemory(ss); + VLOG(2) << "Symbolic Analysis\n" << ss.str(); + } + + event_logger.AddEvent("Analyze"); + if (solver.info() != Eigen::Success) { + summary.termination_type = LINEAR_SOLVER_FATAL_ERROR; + summary.message = "Eigen failure. Unable to find symbolic factorization."; + return summary; + } + + solver.factorize(lhs); + event_logger.AddEvent("Factorize"); + if (solver.info() != Eigen::Success) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = "Eigen failure. Unable to find numeric factorization."; + return summary; + } + + const Vector rhs = VectorRef(rhs_and_solution, lhs.cols()); + VectorRef(rhs_and_solution, lhs.cols()) = solver.solve(rhs); + event_logger.AddEvent("Solve"); + if (solver.info() != Eigen::Success) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = "Eigen failure. Unable to do triangular solve."; + return summary; + } + + return summary; +#endif // CERES_USE_EIGEN_SPARSE +} + +LinearSolver::Summary DynamicSparseNormalCholeskySolver::SolveImplUsingCXSparse( + CompressedRowSparseMatrix* A, double* rhs_and_solution) { +#ifdef CERES_NO_CXSPARSE + + LinearSolver::Summary summary; + summary.num_iterations = 0; + summary.termination_type = LINEAR_SOLVER_FATAL_ERROR; + summary.message = + "SPARSE_NORMAL_CHOLESKY cannot be used with CX_SPARSE " + "because Ceres was not built with support for CXSparse. " + "This requires enabling building with -DCXSPARSE=ON."; + + return summary; + +#else + EventLogger event_logger( + "DynamicSparseNormalCholeskySolver::CXSparse::Solve"); + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.message = "Success."; + + CXSparse cxsparse; + + // Wrap the augmented Jacobian in a compressed sparse column matrix. + cs_di a_transpose = cxsparse.CreateSparseMatrixTransposeView(A); + + // Compute the normal equations. J'J delta = J'f and solve them + // using a sparse Cholesky factorization. Notice that when compared + // to SuiteSparse we have to explicitly compute the transpose of Jt, + // and then the normal equations before they can be + // factorized. CHOLMOD/SuiteSparse on the other hand can just work + // off of Jt to compute the Cholesky factorization of the normal + // equations. + cs_di* a = cxsparse.TransposeMatrix(&a_transpose); + cs_di* lhs = cxsparse.MatrixMatrixMultiply(&a_transpose, a); + cxsparse.Free(a); + event_logger.AddEvent("NormalEquations"); + + if (!cxsparse.SolveCholesky(lhs, rhs_and_solution)) { + summary.termination_type = LINEAR_SOLVER_FAILURE; + summary.message = "CXSparse::SolveCholesky failed"; + } + event_logger.AddEvent("Solve"); + + cxsparse.Free(lhs); + event_logger.AddEvent("TearDown"); + return summary; +#endif +} + +LinearSolver::Summary +DynamicSparseNormalCholeskySolver::SolveImplUsingSuiteSparse( + CompressedRowSparseMatrix* A, double* rhs_and_solution) { +#ifdef CERES_NO_SUITESPARSE + + LinearSolver::Summary summary; + summary.num_iterations = 0; + summary.termination_type = LINEAR_SOLVER_FATAL_ERROR; + summary.message = + "SPARSE_NORMAL_CHOLESKY cannot be used with SUITE_SPARSE " + "because Ceres was not built with support for SuiteSparse. " + "This requires enabling building with -DSUITESPARSE=ON."; + return summary; + +#else + + EventLogger event_logger( + "DynamicSparseNormalCholeskySolver::SuiteSparse::Solve"); + LinearSolver::Summary summary; + summary.termination_type = LINEAR_SOLVER_SUCCESS; + summary.num_iterations = 1; + summary.message = "Success."; + + SuiteSparse ss; + const int num_cols = A->num_cols(); + cholmod_sparse lhs = ss.CreateSparseMatrixTransposeView(A); + event_logger.AddEvent("Setup"); + cholmod_factor* factor = ss.AnalyzeCholesky(&lhs, &summary.message); + event_logger.AddEvent("Analysis"); + + if (factor == NULL) { + summary.termination_type = LINEAR_SOLVER_FATAL_ERROR; + return summary; + } + + summary.termination_type = ss.Cholesky(&lhs, factor, &summary.message); + if (summary.termination_type == LINEAR_SOLVER_SUCCESS) { + cholmod_dense* rhs = + ss.CreateDenseVector(rhs_and_solution, num_cols, num_cols); + cholmod_dense* solution = ss.Solve(factor, rhs, &summary.message); + event_logger.AddEvent("Solve"); + ss.Free(rhs); + if (solution != NULL) { + memcpy( + rhs_and_solution, solution->x, num_cols * sizeof(*rhs_and_solution)); + ss.Free(solution); + } else { + summary.termination_type = LINEAR_SOLVER_FAILURE; + } + } + + ss.Free(factor); + event_logger.AddEvent("Teardown"); + return summary; + +#endif +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_sparse_normal_cholesky_solver.h b/internal/ceres/dynamic_sparse_normal_cholesky_solver.h new file mode 100644 index 0000000..9861f6b --- /dev/null +++ b/internal/ceres/dynamic_sparse_normal_cholesky_solver.h @@ -0,0 +1,85 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// A solver for sparse linear least squares problem based on solving +// the normal equations via a sparse cholesky factorization. + +#ifndef CERES_INTERNAL_DYNAMIC_SPARSE_NORMAL_CHOLESKY_SOLVER_H_ +#define CERES_INTERNAL_DYNAMIC_SPARSE_NORMAL_CHOLESKY_SOLVER_H_ + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#include "ceres/internal/macros.h" +#include "ceres/linear_solver.h" + +namespace ceres { +namespace internal { + +class CompressedRowSparseMatrix; + +// A variant of SparseNormalCholeskySolver in the case where matrix +// sparsity is not constant across calls to Solve. This means that +// there is no benefit to symbolically factorizing the matrix and +// caching this factorization. +class DynamicSparseNormalCholeskySolver + : public CompressedRowSparseMatrixSolver { + public: + explicit DynamicSparseNormalCholeskySolver( + const LinearSolver::Options& options); + virtual ~DynamicSparseNormalCholeskySolver() {} + + private: + virtual LinearSolver::Summary SolveImpl( + CompressedRowSparseMatrix* A, + const double* b, + const LinearSolver::PerSolveOptions& options, + double* x); + + LinearSolver::Summary SolveImplUsingSuiteSparse( + CompressedRowSparseMatrix* A, + double* rhs_and_solution); + + LinearSolver::Summary SolveImplUsingCXSparse( + CompressedRowSparseMatrix* A, + double* rhs_and_solution); + + LinearSolver::Summary SolveImplUsingEigen( + CompressedRowSparseMatrix* A, + double* rhs_and_solution); + + const LinearSolver::Options options_; + CERES_DISALLOW_COPY_AND_ASSIGN(DynamicSparseNormalCholeskySolver); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_DYNAMIC_SPARSE_NORMAL_CHOLESKY_SOLVER_H_ diff --git a/internal/ceres/dynamic_sparse_normal_cholesky_solver_test.cc b/internal/ceres/dynamic_sparse_normal_cholesky_solver_test.cc new file mode 100644 index 0000000..3fdf6a1 --- /dev/null +++ b/internal/ceres/dynamic_sparse_normal_cholesky_solver_test.cc @@ -0,0 +1,128 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/casts.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/linear_least_squares_problems.h" +#include "ceres/linear_solver.h" +#include "ceres/triplet_sparse_matrix.h" +#include "ceres/types.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +#include "Eigen/Cholesky" + +namespace ceres { +namespace internal { + +// TODO(sameeragarwal): These tests needs to be re-written to be more +// thorough, they do not really test the dynamic nature of the +// sparsity. +class DynamicSparseNormalCholeskySolverTest : public ::testing::Test { + protected: + virtual void SetUp() { + scoped_ptr problem( + CreateLinearLeastSquaresProblemFromId(1)); + A_.reset(CompressedRowSparseMatrix::FromTripletSparseMatrix( + *down_cast(problem->A.get()))); + b_.reset(problem->b.release()); + D_.reset(problem->D.release()); + } + + void TestSolver(const LinearSolver::Options& options, double* D) { + Matrix dense_A; + A_->ToDenseMatrix(&dense_A); + Matrix lhs = dense_A.transpose() * dense_A; + if (D != NULL) { + lhs += (ConstVectorRef(D, A_->num_cols()).array() * + ConstVectorRef(D, A_->num_cols()).array()) + .matrix() + .asDiagonal(); + } + + Vector rhs(A_->num_cols()); + rhs.setZero(); + A_->LeftMultiply(b_.get(), rhs.data()); + Vector expected_solution = lhs.llt().solve(rhs); + + scoped_ptr solver(LinearSolver::Create(options)); + LinearSolver::PerSolveOptions per_solve_options; + per_solve_options.D = D; + Vector actual_solution(A_->num_cols()); + LinearSolver::Summary summary; + summary = solver->Solve( + A_.get(), b_.get(), per_solve_options, actual_solution.data()); + + EXPECT_EQ(summary.termination_type, LINEAR_SOLVER_SUCCESS); + + for (int i = 0; i < A_->num_cols(); ++i) { + EXPECT_NEAR(expected_solution(i), actual_solution(i), 1e-8) + << "\nExpected: " << expected_solution.transpose() + << "\nActual: " << actual_solution.transpose(); + } + } + + void TestSolver( + const SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type) { + LinearSolver::Options options; + options.type = SPARSE_NORMAL_CHOLESKY; + options.dynamic_sparsity = true; + options.sparse_linear_algebra_library_type = + sparse_linear_algebra_library_type; + TestSolver(options, NULL); + TestSolver(options, D_.get()); + } + + scoped_ptr A_; + scoped_array b_; + scoped_array D_; +}; + +#ifndef CERES_NO_SUITESPARSE +TEST_F(DynamicSparseNormalCholeskySolverTest, SuiteSparse) { + TestSolver(SUITE_SPARSE); +} +#endif + +#ifndef CERES_NO_CXSPARSE +TEST_F(DynamicSparseNormalCholeskySolverTest, CXSparse) { + TestSolver(CX_SPARSE); +} +#endif + +#ifdef CERES_USE_EIGEN_SPARSE +TEST_F(DynamicSparseNormalCholeskySolverTest, Eigen) { + TestSolver(EIGEN_SPARSE); +} +#endif // CERES_USE_EIGEN_SPARSE + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/dynamic_sparsity_test.cc b/internal/ceres/dynamic_sparsity_test.cc new file mode 100644 index 0000000..5fe60f4 --- /dev/null +++ b/internal/ceres/dynamic_sparsity_test.cc @@ -0,0 +1,449 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: richie.stebbing@gmail.com (Richard Stebbing) +// sameeragarwal@google.com (Sameer Agarwal) +// +// Based on examples/ellipse_approximation.cc + +#include +#include +#include "ceres/ceres.h" +#include "glog/logging.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +// Data generated with the following Python code. +// import numpy as np +// np.random.seed(1337) +// t = np.linspace(0.0, 2.0 * np.pi, 212, endpoint=False) +// t += 2.0 * np.pi * 0.01 * np.random.randn(t.size) +// theta = np.deg2rad(15) +// a, b = np.cos(theta), np.sin(theta) +// R = np.array([[a, -b], +// [b, a]]) +// Y = np.dot(np.c_[4.0 * np.cos(t), np.sin(t)], R.T) + +const int kYRows = 212; +const int kYCols = 2; +const double kYData[kYRows * kYCols] = { + +3.871364e+00, +9.916027e-01, + +3.864003e+00, +1.034148e+00, + +3.850651e+00, +1.072202e+00, + +3.868350e+00, +1.014408e+00, + +3.796381e+00, +1.153021e+00, + +3.857138e+00, +1.056102e+00, + +3.787532e+00, +1.162215e+00, + +3.704477e+00, +1.227272e+00, + +3.564711e+00, +1.294959e+00, + +3.754363e+00, +1.191948e+00, + +3.482098e+00, +1.322725e+00, + +3.602777e+00, +1.279658e+00, + +3.585433e+00, +1.286858e+00, + +3.347505e+00, +1.356415e+00, + +3.220855e+00, +1.378914e+00, + +3.558808e+00, +1.297174e+00, + +3.403618e+00, +1.343809e+00, + +3.179828e+00, +1.384721e+00, + +3.054789e+00, +1.398759e+00, + +3.294153e+00, +1.366808e+00, + +3.247312e+00, +1.374813e+00, + +2.988547e+00, +1.404247e+00, + +3.114508e+00, +1.392698e+00, + +2.899226e+00, +1.409802e+00, + +2.533256e+00, +1.414778e+00, + +2.654773e+00, +1.415909e+00, + +2.565100e+00, +1.415313e+00, + +2.976456e+00, +1.405118e+00, + +2.484200e+00, +1.413640e+00, + +2.324751e+00, +1.407476e+00, + +1.930468e+00, +1.378221e+00, + +2.329017e+00, +1.407688e+00, + +1.760640e+00, +1.360319e+00, + +2.147375e+00, +1.396603e+00, + +1.741989e+00, +1.358178e+00, + +1.743859e+00, +1.358394e+00, + +1.557372e+00, +1.335208e+00, + +1.280551e+00, +1.295087e+00, + +1.429880e+00, +1.317546e+00, + +1.213485e+00, +1.284400e+00, + +9.168172e-01, +1.232870e+00, + +1.311141e+00, +1.299839e+00, + +1.231969e+00, +1.287382e+00, + +7.453773e-01, +1.200049e+00, + +6.151587e-01, +1.173683e+00, + +5.935666e-01, +1.169193e+00, + +2.538707e-01, +1.094227e+00, + +6.806136e-01, +1.187089e+00, + +2.805447e-01, +1.100405e+00, + +6.184807e-01, +1.174371e+00, + +1.170550e-01, +1.061762e+00, + +2.890507e-01, +1.102365e+00, + +3.834234e-01, +1.123772e+00, + +3.980161e-04, +1.033061e+00, + -3.651680e-01, +9.370367e-01, + -8.386351e-01, +7.987201e-01, + -8.105704e-01, +8.073702e-01, + -8.735139e-01, +7.878886e-01, + -9.913836e-01, +7.506100e-01, + -8.784011e-01, +7.863636e-01, + -1.181440e+00, +6.882566e-01, + -1.229556e+00, +6.720191e-01, + -1.035839e+00, +7.362765e-01, + -8.031520e-01, +8.096470e-01, + -1.539136e+00, +5.629549e-01, + -1.755423e+00, +4.817306e-01, + -1.337589e+00, +6.348763e-01, + -1.836966e+00, +4.499485e-01, + -1.913367e+00, +4.195617e-01, + -2.126467e+00, +3.314900e-01, + -1.927625e+00, +4.138238e-01, + -2.339862e+00, +2.379074e-01, + -1.881736e+00, +4.322152e-01, + -2.116753e+00, +3.356163e-01, + -2.255733e+00, +2.754930e-01, + -2.555834e+00, +1.368473e-01, + -2.770277e+00, +2.895711e-02, + -2.563376e+00, +1.331890e-01, + -2.826715e+00, -9.000818e-04, + -2.978191e+00, -8.457804e-02, + -3.115855e+00, -1.658786e-01, + -2.982049e+00, -8.678322e-02, + -3.307892e+00, -2.902083e-01, + -3.038346e+00, -1.194222e-01, + -3.190057e+00, -2.122060e-01, + -3.279086e+00, -2.705777e-01, + -3.322028e+00, -2.999889e-01, + -3.122576e+00, -1.699965e-01, + -3.551973e+00, -4.768674e-01, + -3.581866e+00, -5.032175e-01, + -3.497799e+00, -4.315203e-01, + -3.565384e+00, -4.885602e-01, + -3.699493e+00, -6.199815e-01, + -3.585166e+00, -5.061925e-01, + -3.758914e+00, -6.918275e-01, + -3.741104e+00, -6.689131e-01, + -3.688331e+00, -6.077239e-01, + -3.810425e+00, -7.689015e-01, + -3.791829e+00, -7.386911e-01, + -3.789951e+00, -7.358189e-01, + -3.823100e+00, -7.918398e-01, + -3.857021e+00, -8.727074e-01, + -3.858250e+00, -8.767645e-01, + -3.872100e+00, -9.563174e-01, + -3.864397e+00, -1.032630e+00, + -3.846230e+00, -1.081669e+00, + -3.834799e+00, -1.102536e+00, + -3.866684e+00, -1.022901e+00, + -3.808643e+00, -1.139084e+00, + -3.868840e+00, -1.011569e+00, + -3.791071e+00, -1.158615e+00, + -3.797999e+00, -1.151267e+00, + -3.696278e+00, -1.232314e+00, + -3.779007e+00, -1.170504e+00, + -3.622855e+00, -1.270793e+00, + -3.647249e+00, -1.259166e+00, + -3.655412e+00, -1.255042e+00, + -3.573218e+00, -1.291696e+00, + -3.638019e+00, -1.263684e+00, + -3.498409e+00, -1.317750e+00, + -3.304143e+00, -1.364970e+00, + -3.183001e+00, -1.384295e+00, + -3.202456e+00, -1.381599e+00, + -3.244063e+00, -1.375332e+00, + -3.233308e+00, -1.377019e+00, + -3.060112e+00, -1.398264e+00, + -3.078187e+00, -1.396517e+00, + -2.689594e+00, -1.415761e+00, + -2.947662e+00, -1.407039e+00, + -2.854490e+00, -1.411860e+00, + -2.660499e+00, -1.415900e+00, + -2.875955e+00, -1.410930e+00, + -2.675385e+00, -1.415848e+00, + -2.813155e+00, -1.413363e+00, + -2.417673e+00, -1.411512e+00, + -2.725461e+00, -1.415373e+00, + -2.148334e+00, -1.396672e+00, + -2.108972e+00, -1.393738e+00, + -2.029905e+00, -1.387302e+00, + -2.046214e+00, -1.388687e+00, + -2.057402e+00, -1.389621e+00, + -1.650250e+00, -1.347160e+00, + -1.806764e+00, -1.365469e+00, + -1.206973e+00, -1.283343e+00, + -8.029259e-01, -1.211308e+00, + -1.229551e+00, -1.286993e+00, + -1.101507e+00, -1.265754e+00, + -9.110645e-01, -1.231804e+00, + -1.110046e+00, -1.267211e+00, + -8.465274e-01, -1.219677e+00, + -7.594163e-01, -1.202818e+00, + -8.023823e-01, -1.211203e+00, + -3.732519e-01, -1.121494e+00, + -1.918373e-01, -1.079668e+00, + -4.671988e-01, -1.142253e+00, + -4.033645e-01, -1.128215e+00, + -1.920740e-01, -1.079724e+00, + -3.022157e-01, -1.105389e+00, + -1.652831e-01, -1.073354e+00, + +4.671625e-01, -9.085886e-01, + +5.940178e-01, -8.721832e-01, + +3.147557e-01, -9.508290e-01, + +6.383631e-01, -8.591867e-01, + +9.888923e-01, -7.514088e-01, + +7.076339e-01, -8.386023e-01, + +1.326682e+00, -6.386698e-01, + +1.149834e+00, -6.988221e-01, + +1.257742e+00, -6.624207e-01, + +1.492352e+00, -5.799632e-01, + +1.595574e+00, -5.421766e-01, + +1.240173e+00, -6.684113e-01, + +1.706612e+00, -5.004442e-01, + +1.873984e+00, -4.353002e-01, + +1.985633e+00, -3.902561e-01, + +1.722880e+00, -4.942329e-01, + +2.095182e+00, -3.447402e-01, + +2.018118e+00, -3.768991e-01, + +2.422702e+00, -1.999563e-01, + +2.370611e+00, -2.239326e-01, + +2.152154e+00, -3.205250e-01, + +2.525121e+00, -1.516499e-01, + +2.422116e+00, -2.002280e-01, + +2.842806e+00, +9.536372e-03, + +3.030128e+00, +1.146027e-01, + +2.888424e+00, +3.433444e-02, + +2.991609e+00, +9.226409e-02, + +2.924807e+00, +5.445844e-02, + +3.007772e+00, +1.015875e-01, + +2.781973e+00, -2.282382e-02, + +3.164737e+00, +1.961781e-01, + +3.237671e+00, +2.430139e-01, + +3.046123e+00, +1.240014e-01, + +3.414834e+00, +3.669060e-01, + +3.436591e+00, +3.833600e-01, + +3.626207e+00, +5.444311e-01, + +3.223325e+00, +2.336361e-01, + +3.511963e+00, +4.431060e-01, + +3.698380e+00, +6.187442e-01, + +3.670244e+00, +5.884943e-01, + +3.558833e+00, +4.828230e-01, + +3.661807e+00, +5.797689e-01, + +3.767261e+00, +7.030893e-01, + +3.801065e+00, +7.532650e-01, + +3.828523e+00, +8.024454e-01, + +3.840719e+00, +8.287032e-01, + +3.848748e+00, +8.485921e-01, + +3.865801e+00, +9.066551e-01, + +3.870983e+00, +9.404873e-01, + +3.870263e+00, +1.001884e+00, + +3.864462e+00, +1.032374e+00, + +3.870542e+00, +9.996121e-01, + +3.865424e+00, +1.028474e+00 +}; + +ConstMatrixRef kY(kYData, kYRows, kYCols); + +class PointToLineSegmentContourCostFunction : public CostFunction { + public: + PointToLineSegmentContourCostFunction(const int num_segments, + const Eigen::Vector2d& y) + : num_segments_(num_segments), y_(y) { + // The first parameter is the preimage position. + mutable_parameter_block_sizes()->push_back(1); + // The next parameters are the control points for the line segment contour. + for (int i = 0; i < num_segments_; ++i) { + mutable_parameter_block_sizes()->push_back(2); + } + set_num_residuals(2); + } + + virtual bool Evaluate(const double* const* x, + double* residuals, + double** jacobians) const { + // Convert the preimage position `t` into a segment index `i0` and the + // line segment interpolation parameter `u`. `i1` is the index of the next + // control point. + const double t = ModuloNumSegments(*x[0]); + CHECK_GE(t, 0.0); + CHECK_LT(t, num_segments_); + const int i0 = floor(t), i1 = (i0 + 1) % num_segments_; + const double u = t - i0; + + // Linearly interpolate between control points `i0` and `i1`. + residuals[0] = y_[0] - ((1.0 - u) * x[1 + i0][0] + u * x[1 + i1][0]); + residuals[1] = y_[1] - ((1.0 - u) * x[1 + i0][1] + u * x[1 + i1][1]); + + if (jacobians == NULL) { + return true; + } + + if (jacobians[0] != NULL) { + jacobians[0][0] = x[1 + i0][0] - x[1 + i1][0]; + jacobians[0][1] = x[1 + i0][1] - x[1 + i1][1]; + } + for (int i = 0; i < num_segments_; ++i) { + if (jacobians[i + 1] != NULL) { + MatrixRef(jacobians[i + 1], 2, 2).setZero(); + if (i == i0) { + jacobians[i + 1][0] = -(1.0 - u); + jacobians[i + 1][3] = -(1.0 - u); + } else if (i == i1) { + jacobians[i + 1][0] = -u; + jacobians[i + 1][3] = -u; + } + } + } + return true; + } + + static CostFunction* Create(const int num_segments, const Eigen::Vector2d& y) { + return new PointToLineSegmentContourCostFunction(num_segments, y); + } + + private: + inline double ModuloNumSegments(const double t) const { + return t - num_segments_ * floor(t / num_segments_); + } + + const int num_segments_; + const Eigen::Vector2d y_; +}; + +class EuclideanDistanceFunctor { + public: + explicit EuclideanDistanceFunctor(const double sqrt_weight) + : sqrt_weight_(sqrt_weight) {} + + template + bool operator()(const T* x0, const T* x1, T* residuals) const { + residuals[0] = sqrt_weight_ * (x0[0] - x1[0]); + residuals[1] = sqrt_weight_ * (x0[1] - x1[1]); + return true; + } + + static CostFunction* Create(const double sqrt_weight) { + return new AutoDiffCostFunction( + new EuclideanDistanceFunctor(sqrt_weight)); + } + + private: + const double sqrt_weight_; +}; + +TEST(DynamicSparsity, StaticAndDynamicSparsityProduceSameSolution) { + // Skip test if there is no sparse linear algebra library. + if (!IsSparseLinearAlgebraLibraryTypeAvailable(SUITE_SPARSE) && + !IsSparseLinearAlgebraLibraryTypeAvailable(CX_SPARSE) && + !IsSparseLinearAlgebraLibraryTypeAvailable(EIGEN_SPARSE)) { + return; + } + + // Problem configuration. + const int num_segments = 151; + const double regularization_weight = 1e-2; + + // `X` is the matrix of control points which make up the contour of line + // segments. The number of control points is equal to the number of line + // segments because the contour is closed. + // + // Initialize `X` to points on the unit circle. + Vector w(num_segments + 1); + w.setLinSpaced(num_segments + 1, 0.0, 2.0 * M_PI); + w.conservativeResize(num_segments); + Matrix X(num_segments, 2); + X.col(0) = w.array().cos(); + X.col(1) = w.array().sin(); + + // Each data point has an associated preimage position on the line segment + // contour. For each data point we initialize the preimage positions to + // the index of the closest control point. + const int num_observations = kY.rows(); + Vector t(num_observations); + for (int i = 0; i < num_observations; ++i) { + (X.rowwise() - kY.row(i)).rowwise().squaredNorm().minCoeff(&t[i]); + } + + Problem problem; + + // For each data point add a residual which measures its distance to its + // corresponding position on the line segment contour. + std::vector parameter_blocks(1 + num_segments); + parameter_blocks[0] = NULL; + for (int i = 0; i < num_segments; ++i) { + parameter_blocks[i + 1] = X.data() + 2 * i; + } + for (int i = 0; i < num_observations; ++i) { + parameter_blocks[0] = &t[i]; + problem.AddResidualBlock( + PointToLineSegmentContourCostFunction::Create(num_segments, kY.row(i)), + NULL, + parameter_blocks); + } + + // Add regularization to minimize the length of the line segment contour. + for (int i = 0; i < num_segments; ++i) { + problem.AddResidualBlock( + EuclideanDistanceFunctor::Create(sqrt(regularization_weight)), + NULL, + X.data() + 2 * i, + X.data() + 2 * ((i + 1) % num_segments)); + } + + Solver::Options options; + options.max_num_iterations = 100; + options.linear_solver_type = SPARSE_NORMAL_CHOLESKY; + + // First, solve `X` and `t` jointly with dynamic_sparsity = true. + Matrix X0 = X; + Vector t0 = t; + options.dynamic_sparsity = false; + Solver::Summary static_summary; + Solve(options, &problem, &static_summary); + EXPECT_EQ(static_summary.termination_type, CONVERGENCE) + << static_summary.FullReport(); + + X = X0; + t = t0; + options.dynamic_sparsity = true; + Solver::Summary dynamic_summary; + Solve(options, &problem, &dynamic_summary); + EXPECT_EQ(dynamic_summary.termination_type, CONVERGENCE) + << dynamic_summary.FullReport(); + + EXPECT_NEAR(static_summary.final_cost, + dynamic_summary.final_cost, + std::numeric_limits::epsilon()) + << "Static: \n" + << static_summary.FullReport() << "\nDynamic: \n" + << dynamic_summary.FullReport(); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/eigensparse.cc b/internal/ceres/eigensparse.cc new file mode 100644 index 0000000..aa6b6a9 --- /dev/null +++ b/internal/ceres/eigensparse.cc @@ -0,0 +1,143 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/eigensparse.h" + +#ifdef CERES_USE_EIGEN_SPARSE + +#include +#include "Eigen/SparseCholesky" +#include "Eigen/SparseCore" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/linear_solver.h" + +namespace ceres { +namespace internal { + +template +class EigenSparseCholeskyTemplate : public EigenSparseCholesky { + public: + EigenSparseCholeskyTemplate() : analyzed_(false) {} + virtual ~EigenSparseCholeskyTemplate() {} + virtual CompressedRowSparseMatrix::StorageType StorageType() const { + return CompressedRowSparseMatrix::LOWER_TRIANGULAR; + } + + virtual LinearSolverTerminationType Factorize( + const Eigen::SparseMatrix& lhs, std::string* message) { + if (!analyzed_) { + solver_.analyzePattern(lhs); + + if (VLOG_IS_ON(2)) { + std::stringstream ss; + solver_.dumpMemory(ss); + VLOG(2) << "Symbolic Analysis\n" << ss.str(); + } + + if (solver_.info() != Eigen::Success) { + *message = "Eigen failure. Unable to find symbolic factorization."; + return LINEAR_SOLVER_FATAL_ERROR; + } + + analyzed_ = true; + } + + solver_.factorize(lhs); + if (solver_.info() != Eigen::Success) { + *message = "Eigen failure. Unable to find numeric factorization."; + return LINEAR_SOLVER_FAILURE; + } + return LINEAR_SOLVER_SUCCESS; + } + + virtual LinearSolverTerminationType Solve(const double* rhs, + double* solution, + std::string* message) { + CHECK(analyzed_) << "Solve called without a call to Factorize first."; + + VectorRef(solution, solver_.cols()) = + solver_.solve(ConstVectorRef(rhs, solver_.cols())); + if (solver_.info() != Eigen::Success) { + *message = "Eigen failure. Unable to do triangular solve."; + return LINEAR_SOLVER_FAILURE; + } + return LINEAR_SOLVER_SUCCESS; + } + + virtual LinearSolverTerminationType Factorize(CompressedRowSparseMatrix* lhs, + std::string* message) { + CHECK_EQ(lhs->storage_type(), StorageType()); + Eigen::MappedSparseMatrix eigen_lhs( + lhs->num_rows(), + lhs->num_rows(), + lhs->num_nonzeros(), + lhs->mutable_rows(), + lhs->mutable_cols(), + lhs->mutable_values()); + return Factorize(eigen_lhs, message); + } + + private: + bool analyzed_; + Solver solver_; +}; + +EigenSparseCholesky* EigenSparseCholesky::Create( + const OrderingType ordering_type) { + // The preprocessor gymnastics here are dealing with the fact that + // before version 3.2.2, Eigen did not support a third template + // parameter to specify the ordering and it always defaults to AMD. +#if EIGEN_VERSION_AT_LEAST(3, 2, 2) + typedef Eigen::SimplicialLDLT, + Eigen::Upper, + Eigen::AMDOrdering > + WithAMDOrdering; + typedef Eigen::SimplicialLDLT, + Eigen::Upper, + Eigen::NaturalOrdering > + WithNaturalOrdering; + if (ordering_type == AMD) { + return new EigenSparseCholeskyTemplate(); + } else { + return new EigenSparseCholeskyTemplate(); + } +#else + typedef Eigen::SimplicialLDLT, Eigen::Upper> + WithAMDOrdering; + return new EigenSparseCholeskyTemplate(); +#endif +} + +EigenSparseCholesky::~EigenSparseCholesky() {} + +} // namespace internal +} // namespace ceres + +#endif // CERES_USE_EIGEN_SPARSE diff --git a/internal/ceres/eigensparse.h b/internal/ceres/eigensparse.h new file mode 100644 index 0000000..402bb5c --- /dev/null +++ b/internal/ceres/eigensparse.h @@ -0,0 +1,69 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// A simple C++ interface to the Eigen's Sparse Cholesky routines. + +#ifndef CERES_INTERNAL_EIGENSPARSE_H_ +#define CERES_INTERNAL_EIGENSPARSE_H_ + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifdef CERES_USE_EIGEN_SPARSE + +#include +#include "Eigen/SparseCore" +#include "ceres/linear_solver.h" +#include "ceres/sparse_cholesky.h" + +namespace ceres { +namespace internal { + +class EigenSparseCholesky : public SparseCholesky { + public: + // Factory + static EigenSparseCholesky* Create(const OrderingType ordering_type); + + // SparseCholesky interface. + virtual ~EigenSparseCholesky(); + virtual CompressedRowSparseMatrix::StorageType StorageType() const = 0; + virtual LinearSolverTerminationType Factorize( + const Eigen::SparseMatrix& lhs, std::string* message) = 0; + virtual LinearSolverTerminationType Solve(const double* rhs, + double* solution, + std::string* message) = 0; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_USE_EIGEN_SPARSE + +#endif // CERES_INTERNAL_EIGENSPARSE_H_ diff --git a/internal/ceres/evaluator.cc b/internal/ceres/evaluator.cc new file mode 100644 index 0000000..6193ae8 --- /dev/null +++ b/internal/ceres/evaluator.cc @@ -0,0 +1,86 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) + +#include +#include "ceres/block_evaluate_preparer.h" +#include "ceres/block_jacobian_writer.h" +#include "ceres/compressed_row_jacobian_writer.h" +#include "ceres/compressed_row_sparse_matrix.h" +#include "ceres/crs_matrix.h" +#include "ceres/dense_jacobian_writer.h" +#include "ceres/dynamic_compressed_row_finalizer.h" +#include "ceres/dynamic_compressed_row_jacobian_writer.h" +#include "ceres/evaluator.h" +#include "ceres/internal/port.h" +#include "ceres/program_evaluator.h" +#include "ceres/scratch_evaluate_preparer.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +Evaluator::~Evaluator() {} + +Evaluator* Evaluator::Create(const Evaluator::Options& options, + Program* program, + std::string* error) { + switch (options.linear_solver_type) { + case DENSE_QR: + case DENSE_NORMAL_CHOLESKY: + return new ProgramEvaluator(options, + program); + case DENSE_SCHUR: + case SPARSE_SCHUR: + case ITERATIVE_SCHUR: + case CGNR: + return new ProgramEvaluator(options, + program); + case SPARSE_NORMAL_CHOLESKY: + if (options.dynamic_sparsity) { + return new ProgramEvaluator( + options, program); + } else { + return new ProgramEvaluator(options, + program); + } + + default: + *error = "Invalid Linear Solver Type. Unable to create evaluator."; + return NULL; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/evaluator.h b/internal/ceres/evaluator.h new file mode 100644 index 0000000..fea3079 --- /dev/null +++ b/internal/ceres/evaluator.h @@ -0,0 +1,205 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// keir@google.com (Keir Mierle) + +#ifndef CERES_INTERNAL_EVALUATOR_H_ +#define CERES_INTERNAL_EVALUATOR_H_ + +#include +#include +#include + +#include "ceres/execution_summary.h" +#include "ceres/internal/port.h" +#include "ceres/types.h" + +namespace ceres { + +struct CRSMatrix; + +namespace internal { + +class Program; +class SparseMatrix; + +// The Evaluator interface offers a way to interact with a least squares cost +// function that is useful for an optimizer that wants to minimize the least +// squares objective. This insulates the optimizer from issues like Jacobian +// storage, parameterization, etc. +class Evaluator { + public: + virtual ~Evaluator(); + + struct Options { + Options() + : num_threads(1), + num_eliminate_blocks(-1), + linear_solver_type(DENSE_QR), + dynamic_sparsity(false) {} + + int num_threads; + int num_eliminate_blocks; + LinearSolverType linear_solver_type; + bool dynamic_sparsity; + }; + + static Evaluator* Create(const Options& options, + Program* program, + std::string* error); + + // This is used for computing the cost, residual and Jacobian for + // returning to the user. For actually solving the optimization + // problem, the optimization algorithm uses the ProgramEvaluator + // objects directly. + // + // The residual, gradients and jacobian pointers can be NULL, in + // which case they will not be evaluated. cost cannot be NULL. + // + // The parallelism of the evaluator is controlled by num_threads; it + // should be at least 1. + // + // Note: That this function does not take a parameter vector as + // input. The parameter blocks are evaluated on the values contained + // in the arrays pointed to by their user_state pointers. + // + // Also worth noting is that this function mutates program by + // calling Program::SetParameterOffsetsAndIndex() on it so that an + // evaluator object can be constructed. + static bool Evaluate(Program* program, + int num_threads, + double* cost, + std::vector* residuals, + std::vector* gradient, + CRSMatrix* jacobian); + + // Build and return a sparse matrix for storing and working with the Jacobian + // of the objective function. The jacobian has dimensions + // NumEffectiveParameters() by NumParameters(), and is typically extremely + // sparse. Since the sparsity pattern of the Jacobian remains constant over + // the lifetime of the optimization problem, this method is used to + // instantiate a SparseMatrix object with the appropriate sparsity structure + // (which can be an expensive operation) and then reused by the optimization + // algorithm and the various linear solvers. + // + // It is expected that the classes implementing this interface will be aware + // of their client's requirements for the kind of sparse matrix storage and + // layout that is needed for an efficient implementation. For example + // CompressedRowOptimizationProblem creates a compressed row representation of + // the jacobian for use with CHOLMOD, where as BlockOptimizationProblem + // creates a BlockSparseMatrix representation of the jacobian for use in the + // Schur complement based methods. + virtual SparseMatrix* CreateJacobian() const = 0; + + + // Options struct to control Evaluator::Evaluate; + struct EvaluateOptions { + EvaluateOptions() + : apply_loss_function(true) { + } + + // If false, the loss function correction is not applied to the + // residual blocks. + bool apply_loss_function; + }; + + // Evaluate the cost function for the given state. Returns the cost, + // residuals, and jacobian in the corresponding arguments. Both residuals and + // jacobian are optional; to avoid computing them, pass NULL. + // + // If non-NULL, the Jacobian must have a suitable sparsity pattern; only the + // values array of the jacobian is modified. + // + // state is an array of size NumParameters(), cost is a pointer to a single + // double, and residuals is an array of doubles of size NumResiduals(). + virtual bool Evaluate(const EvaluateOptions& evaluate_options, + const double* state, + double* cost, + double* residuals, + double* gradient, + SparseMatrix* jacobian) = 0; + + // Variant of Evaluator::Evaluate where the user wishes to use the + // default EvaluateOptions struct. This is mostly here as a + // convenience method. + bool Evaluate(const double* state, + double* cost, + double* residuals, + double* gradient, + SparseMatrix* jacobian) { + return Evaluate(EvaluateOptions(), + state, + cost, + residuals, + gradient, + jacobian); + } + + // Make a change delta (of size NumEffectiveParameters()) to state (of size + // NumParameters()) and store the result in state_plus_delta. + // + // In the case that there are no parameterizations used, this is equivalent to + // + // state_plus_delta[i] = state[i] + delta[i] ; + // + // however, the mapping is more complicated in the case of parameterizations + // like quaternions. This is the same as the "Plus()" operation in + // local_parameterization.h, but operating over the entire state vector for a + // problem. + virtual bool Plus(const double* state, + const double* delta, + double* state_plus_delta) const = 0; + + // The number of parameters in the optimization problem. + virtual int NumParameters() const = 0; + + // This is the effective number of parameters that the optimizer may adjust. + // This applies when there are parameterizations on some of the parameters. + virtual int NumEffectiveParameters() const = 0; + + // The number of residuals in the optimization problem. + virtual int NumResiduals() const = 0; + + // The following two methods return copies instead of references so + // that the base class implementation does not have to worry about + // life time issues. Further, these calls are not expected to be + // frequent or performance sensitive. + virtual std::map CallStatistics() const { + return std::map(); + } + + virtual std::map TimeStatistics() const { + return std::map(); + } +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_EVALUATOR_H_ diff --git a/internal/ceres/evaluator_test.cc b/internal/ceres/evaluator_test.cc new file mode 100644 index 0000000..48dc78a --- /dev/null +++ b/internal/ceres/evaluator_test.cc @@ -0,0 +1,668 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Tests shared across evaluators. The tests try all combinations of linear +// solver and num_eliminate_blocks (for schur-based solvers). + +#include "ceres/evaluator.h" + +#include "ceres/casts.h" +#include "ceres/cost_function.h" +#include "ceres/crs_matrix.h" +#include "ceres/evaluator_test_utils.h" +#include "ceres/internal/eigen.h" +#include "ceres/internal/scoped_ptr.h" +#include "ceres/local_parameterization.h" +#include "ceres/problem_impl.h" +#include "ceres/program.h" +#include "ceres/sized_cost_function.h" +#include "ceres/sparse_matrix.h" +#include "ceres/stringprintf.h" +#include "ceres/types.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +using std::string; +using std::vector; + +// TODO(keir): Consider pushing this into a common test utils file. +template +class ParameterIgnoringCostFunction + : public SizedCostFunction { + typedef SizedCostFunction Base; + public: + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + for (int i = 0; i < Base::num_residuals(); ++i) { + residuals[i] = i + 1; + } + if (jacobians) { + for (int k = 0; k < Base::parameter_block_sizes().size(); ++k) { + // The jacobians here are full sized, but they are transformed in the + // evaluator into the "local" jacobian. In the tests, the "subset + // constant" parameterization is used, which should pick out columns + // from these jacobians. Put values in the jacobian that make this + // obvious; in particular, make the jacobians like this: + // + // 1 2 3 4 ... + // 1 2 3 4 ... .* kFactor + // 1 2 3 4 ... + // + // where the multiplication by kFactor makes it easier to distinguish + // between Jacobians of different residuals for the same parameter. + if (jacobians[k] != NULL) { + MatrixRef jacobian(jacobians[k], + Base::num_residuals(), + Base::parameter_block_sizes()[k]); + for (int j = 0; j < Base::parameter_block_sizes()[k]; ++j) { + jacobian.col(j).setConstant(kFactor * (j + 1)); + } + } + } + } + return kSucceeds; + } +}; + +struct EvaluatorTestOptions { + EvaluatorTestOptions(LinearSolverType linear_solver_type, + int num_eliminate_blocks, + bool dynamic_sparsity = false) + : linear_solver_type(linear_solver_type), + num_eliminate_blocks(num_eliminate_blocks), + dynamic_sparsity(dynamic_sparsity) {} + + LinearSolverType linear_solver_type; + int num_eliminate_blocks; + bool dynamic_sparsity; +}; + +struct EvaluatorTest + : public ::testing::TestWithParam { + Evaluator* CreateEvaluator(Program* program) { + // This program is straight from the ProblemImpl, and so has no index/offset + // yet; compute it here as required by the evalutor implementations. + program->SetParameterOffsetsAndIndex(); + + if (VLOG_IS_ON(1)) { + string report; + StringAppendF(&report, "Creating evaluator with type: %d", + GetParam().linear_solver_type); + if (GetParam().linear_solver_type == SPARSE_NORMAL_CHOLESKY) { + StringAppendF(&report, ", dynamic_sparsity: %d", + GetParam().dynamic_sparsity); + } + StringAppendF(&report, " and num_eliminate_blocks: %d", + GetParam().num_eliminate_blocks); + VLOG(1) << report; + } + Evaluator::Options options; + options.linear_solver_type = GetParam().linear_solver_type; + options.num_eliminate_blocks = GetParam().num_eliminate_blocks; + options.dynamic_sparsity = GetParam().dynamic_sparsity; + string error; + return Evaluator::Create(options, program, &error); + } + + void EvaluateAndCompare(ProblemImpl *problem, + int expected_num_rows, + int expected_num_cols, + double expected_cost, + const double* expected_residuals, + const double* expected_gradient, + const double* expected_jacobian) { + scoped_ptr evaluator( + CreateEvaluator(problem->mutable_program())); + int num_residuals = expected_num_rows; + int num_parameters = expected_num_cols; + + double cost = -1; + + Vector residuals(num_residuals); + residuals.setConstant(-2000); + + Vector gradient(num_parameters); + gradient.setConstant(-3000); + + scoped_ptr jacobian(evaluator->CreateJacobian()); + + ASSERT_EQ(expected_num_rows, evaluator->NumResiduals()); + ASSERT_EQ(expected_num_cols, evaluator->NumEffectiveParameters()); + ASSERT_EQ(expected_num_rows, jacobian->num_rows()); + ASSERT_EQ(expected_num_cols, jacobian->num_cols()); + + vector state(evaluator->NumParameters()); + + ASSERT_TRUE(evaluator->Evaluate( + &state[0], + &cost, + expected_residuals != NULL ? &residuals[0] : NULL, + expected_gradient != NULL ? &gradient[0] : NULL, + expected_jacobian != NULL ? jacobian.get() : NULL)); + + Matrix actual_jacobian; + if (expected_jacobian != NULL) { + jacobian->ToDenseMatrix(&actual_jacobian); + } + + CompareEvaluations(expected_num_rows, + expected_num_cols, + expected_cost, + expected_residuals, + expected_gradient, + expected_jacobian, + cost, + &residuals[0], + &gradient[0], + actual_jacobian.data()); + } + + // Try all combinations of parameters for the evaluator. + void CheckAllEvaluationCombinations(const ExpectedEvaluation &expected) { + for (int i = 0; i < 8; ++i) { + EvaluateAndCompare(&problem, + expected.num_rows, + expected.num_cols, + expected.cost, + (i & 1) ? expected.residuals : NULL, + (i & 2) ? expected.gradient : NULL, + (i & 4) ? expected.jacobian : NULL); + } + } + + // The values are ignored completely by the cost function. + double x[2]; + double y[3]; + double z[4]; + + ProblemImpl problem; +}; + +void SetSparseMatrixConstant(SparseMatrix* sparse_matrix, double value) { + VectorRef(sparse_matrix->mutable_values(), + sparse_matrix->num_nonzeros()).setConstant(value); +} + +TEST_P(EvaluatorTest, SingleResidualProblem) { + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 3, 2, 3, 4>, + NULL, + x, y, z); + + ExpectedEvaluation expected = { + // Rows/columns + 3, 9, + // Cost + 7.0, + // Residuals + { 1.0, 2.0, 3.0 }, + // Gradient + { 6.0, 12.0, // x + 6.0, 12.0, 18.0, // y + 6.0, 12.0, 18.0, 24.0, // z + }, + // Jacobian + // x y z + { 1, 2, 1, 2, 3, 1, 2, 3, 4, + 1, 2, 1, 2, 3, 1, 2, 3, 4, + 1, 2, 1, 2, 3, 1, 2, 3, 4 + } + }; + CheckAllEvaluationCombinations(expected); +} + +TEST_P(EvaluatorTest, SingleResidualProblemWithPermutedParameters) { + // Add the parameters in explicit order to force the ordering in the program. + problem.AddParameterBlock(x, 2); + problem.AddParameterBlock(y, 3); + problem.AddParameterBlock(z, 4); + + // Then use a cost function which is similar to the others, but swap around + // the ordering of the parameters to the cost function. This shouldn't affect + // the jacobian evaluation, but requires explicit handling in the evaluators. + // At one point the compressed row evaluator had a bug that went undetected + // for a long time, since by chance most users added parameters to the problem + // in the same order that they occurred as parameters to a cost function. + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 3, 4, 3, 2>, + NULL, + z, y, x); + + ExpectedEvaluation expected = { + // Rows/columns + 3, 9, + // Cost + 7.0, + // Residuals + { 1.0, 2.0, 3.0 }, + // Gradient + { 6.0, 12.0, // x + 6.0, 12.0, 18.0, // y + 6.0, 12.0, 18.0, 24.0, // z + }, + // Jacobian + // x y z + { 1, 2, 1, 2, 3, 1, 2, 3, 4, + 1, 2, 1, 2, 3, 1, 2, 3, 4, + 1, 2, 1, 2, 3, 1, 2, 3, 4 + } + }; + CheckAllEvaluationCombinations(expected); +} + +TEST_P(EvaluatorTest, SingleResidualProblemWithNuisanceParameters) { + // These parameters are not used. + double a[2]; + double b[1]; + double c[1]; + double d[3]; + + // Add the parameters in a mixed order so the Jacobian is "checkered" with the + // values from the other parameters. + problem.AddParameterBlock(a, 2); + problem.AddParameterBlock(x, 2); + problem.AddParameterBlock(b, 1); + problem.AddParameterBlock(y, 3); + problem.AddParameterBlock(c, 1); + problem.AddParameterBlock(z, 4); + problem.AddParameterBlock(d, 3); + + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 3, 2, 3, 4>, + NULL, + x, y, z); + + ExpectedEvaluation expected = { + // Rows/columns + 3, 16, + // Cost + 7.0, + // Residuals + { 1.0, 2.0, 3.0 }, + // Gradient + { 0.0, 0.0, // a + 6.0, 12.0, // x + 0.0, // b + 6.0, 12.0, 18.0, // y + 0.0, // c + 6.0, 12.0, 18.0, 24.0, // z + 0.0, 0.0, 0.0, // d + }, + // Jacobian + // a x b y c z d + { 0, 0, 1, 2, 0, 1, 2, 3, 0, 1, 2, 3, 4, 0, 0, 0, + 0, 0, 1, 2, 0, 1, 2, 3, 0, 1, 2, 3, 4, 0, 0, 0, + 0, 0, 1, 2, 0, 1, 2, 3, 0, 1, 2, 3, 4, 0, 0, 0 + } + }; + CheckAllEvaluationCombinations(expected); +} + +TEST_P(EvaluatorTest, MultipleResidualProblem) { + // Add the parameters in explicit order to force the ordering in the program. + problem.AddParameterBlock(x, 2); + problem.AddParameterBlock(y, 3); + problem.AddParameterBlock(z, 4); + + // f(x, y) in R^2 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 2, 2, 3>, + NULL, + x, y); + + // g(x, z) in R^3 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<2, 3, 2, 4>, + NULL, + x, z); + + // h(y, z) in R^4 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<3, 4, 3, 4>, + NULL, + y, z); + + ExpectedEvaluation expected = { + // Rows/columns + 9, 9, + // Cost + // f g h + ( 1 + 4 + 1 + 4 + 9 + 1 + 4 + 9 + 16) / 2.0, + // Residuals + { 1.0, 2.0, // f + 1.0, 2.0, 3.0, // g + 1.0, 2.0, 3.0, 4.0 // h + }, + // Gradient + { 15.0, 30.0, // x + 33.0, 66.0, 99.0, // y + 42.0, 84.0, 126.0, 168.0 // z + }, + // Jacobian + // x y z + { /* f(x, y) */ 1, 2, 1, 2, 3, 0, 0, 0, 0, + 1, 2, 1, 2, 3, 0, 0, 0, 0, + + /* g(x, z) */ 2, 4, 0, 0, 0, 2, 4, 6, 8, + 2, 4, 0, 0, 0, 2, 4, 6, 8, + 2, 4, 0, 0, 0, 2, 4, 6, 8, + + /* h(y, z) */ 0, 0, 3, 6, 9, 3, 6, 9, 12, + 0, 0, 3, 6, 9, 3, 6, 9, 12, + 0, 0, 3, 6, 9, 3, 6, 9, 12, + 0, 0, 3, 6, 9, 3, 6, 9, 12 + } + }; + CheckAllEvaluationCombinations(expected); +} + +TEST_P(EvaluatorTest, MultipleResidualsWithLocalParameterizations) { + // Add the parameters in explicit order to force the ordering in the program. + problem.AddParameterBlock(x, 2); + + // Fix y's first dimension. + vector y_fixed; + y_fixed.push_back(0); + problem.AddParameterBlock(y, 3, new SubsetParameterization(3, y_fixed)); + + // Fix z's second dimension. + vector z_fixed; + z_fixed.push_back(1); + problem.AddParameterBlock(z, 4, new SubsetParameterization(4, z_fixed)); + + // f(x, y) in R^2 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 2, 2, 3>, + NULL, + x, y); + + // g(x, z) in R^3 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<2, 3, 2, 4>, + NULL, + x, z); + + // h(y, z) in R^4 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<3, 4, 3, 4>, + NULL, + y, z); + + ExpectedEvaluation expected = { + // Rows/columns + 9, 7, + // Cost + // f g h + ( 1 + 4 + 1 + 4 + 9 + 1 + 4 + 9 + 16) / 2.0, + // Residuals + { 1.0, 2.0, // f + 1.0, 2.0, 3.0, // g + 1.0, 2.0, 3.0, 4.0 // h + }, + // Gradient + { 15.0, 30.0, // x + 66.0, 99.0, // y + 42.0, 126.0, 168.0 // z + }, + // Jacobian + // x y z + { /* f(x, y) */ 1, 2, 2, 3, 0, 0, 0, + 1, 2, 2, 3, 0, 0, 0, + + /* g(x, z) */ 2, 4, 0, 0, 2, 6, 8, + 2, 4, 0, 0, 2, 6, 8, + 2, 4, 0, 0, 2, 6, 8, + + /* h(y, z) */ 0, 0, 6, 9, 3, 9, 12, + 0, 0, 6, 9, 3, 9, 12, + 0, 0, 6, 9, 3, 9, 12, + 0, 0, 6, 9, 3, 9, 12 + } + }; + CheckAllEvaluationCombinations(expected); +} + +TEST_P(EvaluatorTest, MultipleResidualProblemWithSomeConstantParameters) { + // The values are ignored completely by the cost function. + double x[2]; + double y[3]; + double z[4]; + + // Add the parameters in explicit order to force the ordering in the program. + problem.AddParameterBlock(x, 2); + problem.AddParameterBlock(y, 3); + problem.AddParameterBlock(z, 4); + + // f(x, y) in R^2 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<1, 2, 2, 3>, + NULL, + x, y); + + // g(x, z) in R^3 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<2, 3, 2, 4>, + NULL, + x, z); + + // h(y, z) in R^4 + problem.AddResidualBlock(new ParameterIgnoringCostFunction<3, 4, 3, 4>, + NULL, + y, z); + + // For this test, "z" is constant. + problem.SetParameterBlockConstant(z); + + // Create the reduced program which is missing the fixed "z" variable. + // Normally, the preprocessing of the program that happens in solver_impl + // takes care of this, but we don't want to invoke the solver here. + Program reduced_program; + vector* parameter_blocks = + problem.mutable_program()->mutable_parameter_blocks(); + + // "z" is the last parameter; save it for later and pop it off temporarily. + // Note that "z" will still get read during evaluation, so it cannot be + // deleted at this point. + ParameterBlock* parameter_block_z = parameter_blocks->back(); + parameter_blocks->pop_back(); + + ExpectedEvaluation expected = { + // Rows/columns + 9, 5, + // Cost + // f g h + ( 1 + 4 + 1 + 4 + 9 + 1 + 4 + 9 + 16) / 2.0, + // Residuals + { 1.0, 2.0, // f + 1.0, 2.0, 3.0, // g + 1.0, 2.0, 3.0, 4.0 // h + }, + // Gradient + { 15.0, 30.0, // x + 33.0, 66.0, 99.0, // y + }, + // Jacobian + // x y + { /* f(x, y) */ 1, 2, 1, 2, 3, + 1, 2, 1, 2, 3, + + /* g(x, z) */ 2, 4, 0, 0, 0, + 2, 4, 0, 0, 0, + 2, 4, 0, 0, 0, + + /* h(y, z) */ 0, 0, 3, 6, 9, + 0, 0, 3, 6, 9, + 0, 0, 3, 6, 9, + 0, 0, 3, 6, 9 + } + }; + CheckAllEvaluationCombinations(expected); + + // Restore parameter block z, so it will get freed in a consistent way. + parameter_blocks->push_back(parameter_block_z); +} + +TEST_P(EvaluatorTest, EvaluatorAbortsForResidualsThatFailToEvaluate) { + // Switch the return value to failure. + problem.AddResidualBlock( + new ParameterIgnoringCostFunction<20, 3, 2, 3, 4, false>, NULL, x, y, z); + + // The values are ignored. + double state[9]; + + scoped_ptr evaluator(CreateEvaluator(problem.mutable_program())); + scoped_ptr jacobian(evaluator->CreateJacobian()); + double cost; + EXPECT_FALSE(evaluator->Evaluate(state, &cost, NULL, NULL, NULL)); +} + +// In the pairs, the first argument is the linear solver type, and the second +// argument is num_eliminate_blocks. Changing the num_eliminate_blocks only +// makes sense for the schur-based solvers. +// +// Try all values of num_eliminate_blocks that make sense given that in the +// tests a maximum of 4 parameter blocks are present. +INSTANTIATE_TEST_CASE_P( + LinearSolvers, + EvaluatorTest, + ::testing::Values( + EvaluatorTestOptions(DENSE_QR, 0), + EvaluatorTestOptions(DENSE_SCHUR, 0), + EvaluatorTestOptions(DENSE_SCHUR, 1), + EvaluatorTestOptions(DENSE_SCHUR, 2), + EvaluatorTestOptions(DENSE_SCHUR, 3), + EvaluatorTestOptions(DENSE_SCHUR, 4), + EvaluatorTestOptions(SPARSE_SCHUR, 0), + EvaluatorTestOptions(SPARSE_SCHUR, 1), + EvaluatorTestOptions(SPARSE_SCHUR, 2), + EvaluatorTestOptions(SPARSE_SCHUR, 3), + EvaluatorTestOptions(SPARSE_SCHUR, 4), + EvaluatorTestOptions(ITERATIVE_SCHUR, 0), + EvaluatorTestOptions(ITERATIVE_SCHUR, 1), + EvaluatorTestOptions(ITERATIVE_SCHUR, 2), + EvaluatorTestOptions(ITERATIVE_SCHUR, 3), + EvaluatorTestOptions(ITERATIVE_SCHUR, 4), + EvaluatorTestOptions(SPARSE_NORMAL_CHOLESKY, 0, false), + EvaluatorTestOptions(SPARSE_NORMAL_CHOLESKY, 0, true))); + +// Simple cost function used to check if the evaluator is sensitive to +// state changes. +class ParameterSensitiveCostFunction : public SizedCostFunction<2, 2> { + public: + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + double x1 = parameters[0][0]; + double x2 = parameters[0][1]; + residuals[0] = x1 * x1; + residuals[1] = x2 * x2; + + if (jacobians != NULL) { + double* jacobian = jacobians[0]; + if (jacobian != NULL) { + jacobian[0] = 2.0 * x1; + jacobian[1] = 0.0; + jacobian[2] = 0.0; + jacobian[3] = 2.0 * x2; + } + } + return true; + } +}; + +TEST(Evaluator, EvaluatorRespectsParameterChanges) { + ProblemImpl problem; + + double x[2]; + x[0] = 1.0; + x[1] = 1.0; + + problem.AddResidualBlock(new ParameterSensitiveCostFunction(), NULL, x); + Program* program = problem.mutable_program(); + program->SetParameterOffsetsAndIndex(); + + Evaluator::Options options; + options.linear_solver_type = DENSE_QR; + options.num_eliminate_blocks = 0; + string error; + scoped_ptr evaluator(Evaluator::Create(options, program, &error)); + scoped_ptr jacobian(evaluator->CreateJacobian()); + + ASSERT_EQ(2, jacobian->num_rows()); + ASSERT_EQ(2, jacobian->num_cols()); + + double state[2]; + state[0] = 2.0; + state[1] = 3.0; + + // The original state of a residual block comes from the user's + // state. So the original state is 1.0, 1.0, and the only way we get + // the 2.0, 3.0 results in the following tests is if it respects the + // values in the state vector. + + // Cost only; no residuals and no jacobian. + { + double cost = -1; + ASSERT_TRUE(evaluator->Evaluate(state, &cost, NULL, NULL, NULL)); + EXPECT_EQ(48.5, cost); + } + + // Cost and residuals, no jacobian. + { + double cost = -1; + double residuals[2] = { -2, -2 }; + ASSERT_TRUE(evaluator->Evaluate(state, &cost, residuals, NULL, NULL)); + EXPECT_EQ(48.5, cost); + EXPECT_EQ(4, residuals[0]); + EXPECT_EQ(9, residuals[1]); + } + + // Cost, residuals, and jacobian. + { + double cost = -1; + double residuals[2] = { -2, -2}; + SetSparseMatrixConstant(jacobian.get(), -1); + ASSERT_TRUE(evaluator->Evaluate(state, + &cost, + residuals, + NULL, + jacobian.get())); + EXPECT_EQ(48.5, cost); + EXPECT_EQ(4, residuals[0]); + EXPECT_EQ(9, residuals[1]); + Matrix actual_jacobian; + jacobian->ToDenseMatrix(&actual_jacobian); + + Matrix expected_jacobian(2, 2); + expected_jacobian + << 2 * state[0], 0, + 0, 2 * state[1]; + + EXPECT_TRUE((actual_jacobian.array() == expected_jacobian.array()).all()) + << "Actual:\n" << actual_jacobian + << "\nExpected:\n" << expected_jacobian; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/evaluator_test_utils.cc b/internal/ceres/evaluator_test_utils.cc new file mode 100644 index 0000000..36dc21c --- /dev/null +++ b/internal/ceres/evaluator_test_utils.cc @@ -0,0 +1,89 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/evaluator_test_utils.h" +#include "ceres/internal/eigen.h" +#include "gtest/gtest.h" + +namespace ceres { +namespace internal { + +void CompareEvaluations(int expected_num_rows, + int expected_num_cols, + double expected_cost, + const double* expected_residuals, + const double* expected_gradient, + const double* expected_jacobian, + const double actual_cost, + const double* actual_residuals, + const double* actual_gradient, + const double* actual_jacobian) { + EXPECT_EQ(expected_cost, actual_cost); + + if (expected_residuals != NULL) { + ConstVectorRef expected_residuals_vector(expected_residuals, + expected_num_rows); + ConstVectorRef actual_residuals_vector(actual_residuals, + expected_num_rows); + EXPECT_TRUE((actual_residuals_vector.array() == + expected_residuals_vector.array()).all()) + << "Actual:\n" << actual_residuals_vector + << "\nExpected:\n" << expected_residuals_vector; + } + + if (expected_gradient != NULL) { + ConstVectorRef expected_gradient_vector(expected_gradient, + expected_num_cols); + ConstVectorRef actual_gradient_vector(actual_gradient, + expected_num_cols); + + EXPECT_TRUE((actual_gradient_vector.array() == + expected_gradient_vector.array()).all()) + << "Actual:\n" << actual_gradient_vector.transpose() + << "\nExpected:\n" << expected_gradient_vector.transpose(); + } + + if (expected_jacobian != NULL) { + ConstMatrixRef expected_jacobian_matrix(expected_jacobian, + expected_num_rows, + expected_num_cols); + ConstMatrixRef actual_jacobian_matrix(actual_jacobian, + expected_num_rows, + expected_num_cols); + EXPECT_TRUE((actual_jacobian_matrix.array() == + expected_jacobian_matrix.array()).all()) + << "Actual:\n" << actual_jacobian_matrix + << "\nExpected:\n" << expected_jacobian_matrix; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/evaluator_test_utils.h b/internal/ceres/evaluator_test_utils.h new file mode 100644 index 0000000..7401f04 --- /dev/null +++ b/internal/ceres/evaluator_test_utils.h @@ -0,0 +1,60 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// sameeragarwal@google.com (Sameer Agarwal) +// +// Test utils used for evaluation testing. + +namespace ceres { +namespace internal { + +// Fixed sized struct for storing an evaluation. +struct ExpectedEvaluation { + int num_rows; + int num_cols; + double cost; + const double residuals[50]; + const double gradient[50]; + const double jacobian[200]; +}; + +// Compare two evaluations. +void CompareEvaluations(int expected_num_rows, + int expected_num_cols, + double expected_cost, + const double* expected_residuals, + const double* expected_gradient, + const double* expected_jacobian, + const double actual_cost, + const double* actual_residuals, + const double* actual_gradient, + const double* actual_jacobian); + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/execution_summary.h b/internal/ceres/execution_summary.h new file mode 100644 index 0000000..aa9929d --- /dev/null +++ b/internal/ceres/execution_summary.h @@ -0,0 +1,90 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_EXECUTION_SUMMARY_H_ +#define CERES_INTERNAL_EXECUTION_SUMMARY_H_ + +#include +#include + +#include "ceres/internal/port.h" +#include "ceres/wall_time.h" +#include "ceres/mutex.h" + +namespace ceres { +namespace internal { + +// Struct used by various objects to report statistics and other +// information about their execution. e.g., ExecutionSummary::times +// can be used for reporting times associated with various activities. +class ExecutionSummary { + public: + void IncrementTimeBy(const std::string& name, const double value) { + CeresMutexLock l(×_mutex_); + times_[name] += value; + } + + void IncrementCall(const std::string& name) { + CeresMutexLock l(&calls_mutex_); + calls_[name] += 1; + } + + const std::map& times() const { return times_; } + const std::map& calls() const { return calls_; } + + private: + Mutex times_mutex_; + std::map times_; + + Mutex calls_mutex_; + std::map calls_; +}; + +class ScopedExecutionTimer { + public: + ScopedExecutionTimer(const std::string& name, ExecutionSummary* summary) + : start_time_(WallTimeInSeconds()), + name_(name), + summary_(summary) {} + + ~ScopedExecutionTimer() { + summary_->IncrementTimeBy(name_, WallTimeInSeconds() - start_time_); + } + + private: + const double start_time_; + const std::string name_; + ExecutionSummary* summary_; +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_EXECUTION_SUMMARY_H_ diff --git a/internal/ceres/file.cc b/internal/ceres/file.cc new file mode 100644 index 0000000..c95a44d --- /dev/null +++ b/internal/ceres/file.cc @@ -0,0 +1,95 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Really simple file IO. + +#include "ceres/file.h" + +#include +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +using std::string; + +void WriteStringToFileOrDie(const string &data, const string &filename) { + FILE* file_descriptor = fopen(filename.c_str(), "wb"); + if (!file_descriptor) { + LOG(FATAL) << "Couldn't write to file: " << filename; + } + fwrite(data.c_str(), 1, data.size(), file_descriptor); + fclose(file_descriptor); +} + +void ReadFileToStringOrDie(const string &filename, string *data) { + FILE* file_descriptor = fopen(filename.c_str(), "r"); + + if (!file_descriptor) { + LOG(FATAL) << "Couldn't read file: " << filename; + } + + // Resize the input buffer appropriately. + fseek(file_descriptor, 0L, SEEK_END); + int num_bytes = ftell(file_descriptor); + data->resize(num_bytes); + + // Read the data. + fseek(file_descriptor, 0L, SEEK_SET); + int num_read = fread(&((*data)[0]), + sizeof((*data)[0]), + num_bytes, + file_descriptor); + if (num_read != num_bytes) { + LOG(FATAL) << "Couldn't read all of " << filename + << "expected bytes: " << num_bytes * sizeof((*data)[0]) + << "actual bytes: " << num_read; + } + fclose(file_descriptor); +} + +string JoinPath(const string& dirname, const string& basename) { +#ifdef _WIN32 + static const char separator = '\\'; +#else + static const char separator = '/'; +#endif // _WIN32 + + if ((!basename.empty() && basename[0] == separator) || dirname.empty()) { + return basename; + } else if (dirname[dirname.size() - 1] == separator) { + return dirname + basename; + } else { + return dirname + string(&separator, 1) + basename; + } +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/file.h b/internal/ceres/file.h new file mode 100644 index 0000000..219b459 --- /dev/null +++ b/internal/ceres/file.h @@ -0,0 +1,53 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: keir@google.com (Keir Mierle) +// +// Simple file IO support. This is a portability shim. + +#ifndef CERES_INTERNAL_FILE_H_ +#define CERES_INTERNAL_FILE_H_ + +#include +#include "ceres/internal/port.h" + +namespace ceres { +namespace internal { + +void WriteStringToFileOrDie(const std::string &data, + const std::string &filename); +void ReadFileToStringOrDie(const std::string &filename, std::string *data); + +// Join two path components, adding a slash if necessary. If basename is an +// absolute path then JoinPath ignores dirname and simply returns basename. +std::string JoinPath(const std::string& dirname, const std::string& basename); + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_FILE_H_ diff --git a/internal/ceres/function_sample.cc b/internal/ceres/function_sample.cc new file mode 100644 index 0000000..2fd3dbd --- /dev/null +++ b/internal/ceres/function_sample.cc @@ -0,0 +1,73 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2015 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#include "ceres/function_sample.h" +#include "ceres/stringprintf.h" + +namespace ceres { +namespace internal { + +FunctionSample::FunctionSample() + : x(0.0), + vector_x_is_valid(false), + value(0.0), + value_is_valid(false), + vector_gradient_is_valid(false), + gradient(0.0), + gradient_is_valid(false) {} + +FunctionSample::FunctionSample(const double x, const double value) + : x(x), + vector_x_is_valid(false), + value(value), + value_is_valid(true), + vector_gradient_is_valid(false), + gradient(0.0), + gradient_is_valid(false) {} + +FunctionSample::FunctionSample(const double x, + const double value, + const double gradient) + : x(x), + vector_x_is_valid(false), + value(value), + value_is_valid(true), + vector_gradient_is_valid(false), + gradient(gradient), + gradient_is_valid(true) {} + +std::string FunctionSample::ToDebugString() const { + return StringPrintf("[x: %.8e, value: %.8e, gradient: %.8e, " + "value_is_valid: %d, gradient_is_valid: %d]", + x, value, gradient, value_is_valid, gradient_is_valid); +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/function_sample.h b/internal/ceres/function_sample.h new file mode 100644 index 0000000..df79aef --- /dev/null +++ b/internal/ceres/function_sample.h @@ -0,0 +1,94 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) + +#ifndef CERES_INTERNAL_FUNCTION_SAMPLE_H_ +#define CERES_INTERNAL_FUNCTION_SAMPLE_H_ + +#include +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +// FunctionSample is used by the line search routines to store and +// communicate the value and (optionally) the gradient of the function +// being minimized. +// +// Since line search as the name implies happens along a certain +// line/direction. FunctionSample contains the information in two +// ways. Information in the ambient space and information along the +// direction of search. +struct FunctionSample { + FunctionSample(); + FunctionSample(double x, double value); + FunctionSample(double x, double value, double gradient); + + std::string ToDebugString() const; + + // x is the location of the sample along the search direction. + double x; + + // Let p be a point and d be the search direction then + // + // vector_x = p + x * d; + Vector vector_x; + // True if vector_x has been assigned a valid value. + bool vector_x_is_valid; + + // value = f(vector_x) + double value; + // True of the evaluation was successful and value is a finite + // number. + bool value_is_valid; + + // vector_gradient = Df(vector_position); + // + // D is the derivative operator. + Vector vector_gradient; + // True if the vector gradient was evaluated and the evaluation was + // successful (the value is a finite number). + bool vector_gradient_is_valid; + + // gradient = d.transpose() * vector_gradient + // + // where d is the search direction. + double gradient; + // True if the evaluation of the gradient was sucessful and the + // value is a finite number. + bool gradient_is_valid; +}; + + + + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_FUNCTION_SAMPLE_H_ diff --git a/internal/ceres/generate_template_specializations.py b/internal/ceres/generate_template_specializations.py new file mode 100644 index 0000000..a30c3f0 --- /dev/null +++ b/internal/ceres/generate_template_specializations.py @@ -0,0 +1,244 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2015 Google Inc. All rights reserved. +# http://ceres-solver.org/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: sameeragarwal@google.com (Sameer Agarwal) +# +# Script for explicitly generating template specialization of the +# SchurEliminator class. It is a rather large class +# and the number of explicit instantiations is also large. Explicitly +# generating these instantiations in separate .cc files breaks the +# compilation into separate compilation unit rather than one large cc +# file which takes 2+GB of RAM to compile. +# +# This script creates three sets of files. +# +# 1. schur_eliminator_x_x_x.cc and partitioned_matrix_view_x_x_x.cc +# where, the x indicates the template parameters and +# +# 2. schur_eliminator.cc & partitioned_matrix_view.cc +# +# that contains a factory function for instantiating these classes +# based on runtime parameters. +# +# 3. schur_templates.cc +# +# that contains a function which can be queried to determine what +# template specializations are available. +# +# The following list of tuples, specializations indicates the set of +# specializations that is generated. +SPECIALIZATIONS = [(2, 2, 2), + (2, 2, 3), + (2, 2, 4), + (2, 2, "Eigen::Dynamic"), + (2, 3, 3), + (2, 3, 4), + (2, 3, 6), + (2, 3, 9), + (2, 3, "Eigen::Dynamic"), + (2, 4, 3), + (2, 4, 4), + (2, 4, 8), + (2, 4, 9), + (2, 4, "Eigen::Dynamic"), + (2, "Eigen::Dynamic", "Eigen::Dynamic"), + (4, 4, 2), + (4, 4, 3), + (4, 4, 4), + (4, 4, "Eigen::Dynamic")] + +import schur_eliminator_template +import partitioned_matrix_view_template +import os +import glob + +def SuffixForSize(size): + if size == "Eigen::Dynamic": + return "d" + return str(size) + +def SpecializationFilename(prefix, row_block_size, e_block_size, f_block_size): + return "_".join([prefix] + map(SuffixForSize, (row_block_size, + e_block_size, + f_block_size))) + +def GenerateFactoryConditional(row_block_size, e_block_size, f_block_size): + conditionals = [] + if (row_block_size != "Eigen::Dynamic"): + conditionals.append("(options.row_block_size == %s)" % row_block_size) + if (e_block_size != "Eigen::Dynamic"): + conditionals.append("(options.e_block_size == %s)" % e_block_size) + if (f_block_size != "Eigen::Dynamic"): + conditionals.append("(options.f_block_size == %s)" % f_block_size) + if (len(conditionals) == 0): + return "%s" + + if (len(conditionals) == 1): + return " if " + conditionals[0] + "{\n %s\n }\n" + + return " if (" + " &&\n ".join(conditionals) + ") {\n %s\n }\n" + +def Specialize(name, data): + """ + Generate specialization code and the conditionals to instantiate it. + """ + + # Specialization files + for row_block_size, e_block_size, f_block_size in SPECIALIZATIONS: + output = SpecializationFilename("generated/" + name, + row_block_size, + e_block_size, + f_block_size) + ".cc" + + with open(output, "w") as f: + f.write(data["HEADER"]) + f.write(data["SPECIALIZATION_FILE"] % + (row_block_size, e_block_size, f_block_size)) + + # Generate the _d_d_d specialization. + output = SpecializationFilename("generated/" + name, + "Eigen::Dynamic", + "Eigen::Dynamic", + "Eigen::Dynamic") + ".cc" + with open(output, "w") as f: + f.write(data["HEADER"]) + f.write(data["DYNAMIC_FILE"] % + ("Eigen::Dynamic", "Eigen::Dynamic", "Eigen::Dynamic")) + + # Factory + with open(name + ".cc", "w") as f: + f.write(data["HEADER"]) + f.write(data["FACTORY_FILE_HEADER"]) + for row_block_size, e_block_size, f_block_size in SPECIALIZATIONS: + factory_conditional = GenerateFactoryConditional( + row_block_size, e_block_size, f_block_size) + factory = data["FACTORY"] % (row_block_size, e_block_size, f_block_size) + f.write(factory_conditional % factory); + f.write(data["FACTORY_FOOTER"]) + +QUERY_HEADER = """// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// What template specializations are available. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. +""" + +QUERY_FILE_HEADER = """ +#include "ceres/internal/eigen.h" +#include "ceres/schur_templates.h" + +namespace ceres { +namespace internal { + +void GetBestSchurTemplateSpecialization(int* row_block_size, + int* e_block_size, + int* f_block_size) { + LinearSolver::Options options; + options.row_block_size = *row_block_size; + options.e_block_size = *e_block_size; + options.f_block_size = *f_block_size; + *row_block_size = Eigen::Dynamic; + *e_block_size = Eigen::Dynamic; + *f_block_size = Eigen::Dynamic; +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION +""" + +QUERY_FOOTER = """ +#endif + return; +} + +} // namespace internal +} // namespace ceres +""" + +QUERY_ACTION = """ *row_block_size = %s; + *e_block_size = %s; + *f_block_size = %s; + return;""" + +def GenerateQueryFile(): + """ + Generate file that allows querying for available template specializations. + """ + + with open("schur_templates.cc", "w") as f: + f.write(QUERY_HEADER) + f.write(QUERY_FILE_HEADER) + for row_block_size, e_block_size, f_block_size in SPECIALIZATIONS: + factory_conditional = GenerateFactoryConditional( + row_block_size, e_block_size, f_block_size) + action = QUERY_ACTION % (row_block_size, e_block_size, f_block_size) + f.write(factory_conditional % action) + f.write(QUERY_FOOTER) + + +if __name__ == "__main__": + for f in glob.glob("generated/*"): + os.remove(f) + + Specialize("schur_eliminator", + schur_eliminator_template.__dict__) + Specialize("partitioned_matrix_view", + partitioned_matrix_view_template.__dict__) + GenerateQueryFile() diff --git a/internal/ceres/generated/partitioned_matrix_view_2_2_2.cc b/internal/ceres/generated/partitioned_matrix_view_2_2_2.cc new file mode 100644 index 0000000..86ad17b --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_2_2.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 2, 2>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_2_3.cc b/internal/ceres/generated/partitioned_matrix_view_2_2_3.cc new file mode 100644 index 0000000..33018d5 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_2_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 2, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_2_4.cc b/internal/ceres/generated/partitioned_matrix_view_2_2_4.cc new file mode 100644 index 0000000..a429a54 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_2_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 2, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_2_d.cc b/internal/ceres/generated/partitioned_matrix_view_2_2_d.cc new file mode 100644 index 0000000..f6f03ea --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_2_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 2, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_3_3.cc b/internal/ceres/generated/partitioned_matrix_view_2_3_3.cc new file mode 100644 index 0000000..0b73e1a --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_3_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 3, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_3_4.cc b/internal/ceres/generated/partitioned_matrix_view_2_3_4.cc new file mode 100644 index 0000000..bc4a861 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_3_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 3, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_3_6.cc b/internal/ceres/generated/partitioned_matrix_view_2_3_6.cc new file mode 100644 index 0000000..fe8f7dd --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_3_6.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 3, 6>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_3_9.cc b/internal/ceres/generated/partitioned_matrix_view_2_3_9.cc new file mode 100644 index 0000000..ac493fc --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_3_9.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 3, 9>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_3_d.cc b/internal/ceres/generated/partitioned_matrix_view_2_3_d.cc new file mode 100644 index 0000000..e29efaf --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_3_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 3, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_4_3.cc b/internal/ceres/generated/partitioned_matrix_view_2_4_3.cc new file mode 100644 index 0000000..e61e0a3 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_4_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 4, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_4_4.cc b/internal/ceres/generated/partitioned_matrix_view_2_4_4.cc new file mode 100644 index 0000000..2e1170d --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_4_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 4, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_4_8.cc b/internal/ceres/generated/partitioned_matrix_view_2_4_8.cc new file mode 100644 index 0000000..83015f1 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_4_8.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 4, 8>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_4_9.cc b/internal/ceres/generated/partitioned_matrix_view_2_4_9.cc new file mode 100644 index 0000000..25671f9 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_4_9.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 4, 9>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_4_d.cc b/internal/ceres/generated/partitioned_matrix_view_2_4_d.cc new file mode 100644 index 0000000..d259802 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_4_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, 4, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_2_d_d.cc b/internal/ceres/generated/partitioned_matrix_view_2_d_d.cc new file mode 100644 index 0000000..c956759 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_2_d_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<2, Eigen::Dynamic, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_4_4_2.cc b/internal/ceres/generated/partitioned_matrix_view_4_4_2.cc new file mode 100644 index 0000000..f08049c --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_4_4_2.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<4, 4, 2>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_4_4_3.cc b/internal/ceres/generated/partitioned_matrix_view_4_4_3.cc new file mode 100644 index 0000000..9342612 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_4_4_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<4, 4, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_4_4_4.cc b/internal/ceres/generated/partitioned_matrix_view_4_4_4.cc new file mode 100644 index 0000000..8b273fa --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_4_4_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<4, 4, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_4_4_d.cc b/internal/ceres/generated/partitioned_matrix_view_4_4_d.cc new file mode 100644 index 0000000..e8b45e4 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_4_4_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView<4, 4, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/partitioned_matrix_view_d_d_d.cc b/internal/ceres/generated/partitioned_matrix_view_d_d_d.cc new file mode 100644 index 0000000..3545b86 --- /dev/null +++ b/internal/ceres/generated/partitioned_matrix_view_d_d_d.cc @@ -0,0 +1,52 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of PartitionedMatrixView. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + + +#include "ceres/partitioned_matrix_view_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class PartitionedMatrixView; + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/generated/schur_eliminator_2_2_2.cc b/internal/ceres/generated/schur_eliminator_2_2_2.cc new file mode 100644 index 0000000..79fcf43 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_2_2.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 2, 2>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_2_3.cc b/internal/ceres/generated/schur_eliminator_2_2_3.cc new file mode 100644 index 0000000..edd7fb6 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_2_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 2, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_2_4.cc b/internal/ceres/generated/schur_eliminator_2_2_4.cc new file mode 100644 index 0000000..692267d --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_2_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 2, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_2_d.cc b/internal/ceres/generated/schur_eliminator_2_2_d.cc new file mode 100644 index 0000000..33d9c6d --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_2_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 2, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_3_3.cc b/internal/ceres/generated/schur_eliminator_2_3_3.cc new file mode 100644 index 0000000..4a5e2fe --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_3_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 3, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_3_4.cc b/internal/ceres/generated/schur_eliminator_2_3_4.cc new file mode 100644 index 0000000..7ee63d0 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_3_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 3, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_3_6.cc b/internal/ceres/generated/schur_eliminator_2_3_6.cc new file mode 100644 index 0000000..108760e --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_3_6.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 3, 6>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_3_9.cc b/internal/ceres/generated/schur_eliminator_2_3_9.cc new file mode 100644 index 0000000..4fea2fa --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_3_9.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 3, 9>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_3_d.cc b/internal/ceres/generated/schur_eliminator_2_3_d.cc new file mode 100644 index 0000000..0d13c99 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_3_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 3, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_4_3.cc b/internal/ceres/generated/schur_eliminator_2_4_3.cc new file mode 100644 index 0000000..3827c65 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_4_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 4, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_4_4.cc b/internal/ceres/generated/schur_eliminator_2_4_4.cc new file mode 100644 index 0000000..47bdfab --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_4_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 4, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_4_8.cc b/internal/ceres/generated/schur_eliminator_2_4_8.cc new file mode 100644 index 0000000..862c76a --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_4_8.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 4, 8>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_4_9.cc b/internal/ceres/generated/schur_eliminator_2_4_9.cc new file mode 100644 index 0000000..5b5b7cc --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_4_9.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 4, 9>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_4_d.cc b/internal/ceres/generated/schur_eliminator_2_4_d.cc new file mode 100644 index 0000000..ce2d450 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_4_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, 4, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_2_d_d.cc b/internal/ceres/generated/schur_eliminator_2_d_d.cc new file mode 100644 index 0000000..9b02bd9 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_2_d_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<2, Eigen::Dynamic, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_4_4_2.cc b/internal/ceres/generated/schur_eliminator_4_4_2.cc new file mode 100644 index 0000000..10f709d --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_4_4_2.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<4, 4, 2>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_4_4_3.cc b/internal/ceres/generated/schur_eliminator_4_4_3.cc new file mode 100644 index 0000000..bcbcc74 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_4_4_3.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<4, 4, 3>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_4_4_4.cc b/internal/ceres/generated/schur_eliminator_4_4_4.cc new file mode 100644 index 0000000..44ecc87 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_4_4_4.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<4, 4, 4>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_4_4_d.cc b/internal/ceres/generated/schur_eliminator_4_4_d.cc new file mode 100644 index 0000000..69c8563 --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_4_4_d.cc @@ -0,0 +1,58 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + +// This include must come before any #ifndef check on Ceres compile options. +#include "ceres/internal/port.h" + +#ifndef CERES_RESTRICT_SCHUR_SPECIALIZATION + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator<4, 4, Eigen::Dynamic>; + +} // namespace internal +} // namespace ceres + +#endif // CERES_RESTRICT_SCHUR_SPECIALIZATION diff --git a/internal/ceres/generated/schur_eliminator_d_d_d.cc b/internal/ceres/generated/schur_eliminator_d_d_d.cc new file mode 100644 index 0000000..348708b --- /dev/null +++ b/internal/ceres/generated/schur_eliminator_d_d_d.cc @@ -0,0 +1,52 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2017 Google Inc. All rights reserved. +// http://ceres-solver.org/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +// POSSIBILITY OF SUCH DAMAGE. +// +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Template specialization of SchurEliminator. +// +// ======================================== +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +// THIS FILE IS AUTOGENERATED. DO NOT EDIT. +//========================================= +// +// This file is generated using generate_template_specializations.py. + + +#include "ceres/schur_eliminator_impl.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +template class SchurEliminator; + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/gmock/gmock.h b/internal/ceres/gmock/gmock.h new file mode 100644 index 0000000..cd54177 --- /dev/null +++ b/internal/ceres/gmock/gmock.h @@ -0,0 +1,14978 @@ +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This is the main header file a user should include. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_H_ + +// This file implements the following syntax: +// +// ON_CALL(mock_object.Method(...)) +// .With(...) ? +// .WillByDefault(...); +// +// where With() is optional and WillByDefault() must appear exactly +// once. +// +// EXPECT_CALL(mock_object.Method(...)) +// .With(...) ? +// .Times(...) ? +// .InSequence(...) * +// .WillOnce(...) * +// .WillRepeatedly(...) ? +// .RetiresOnSaturation() ? ; +// +// where all clauses are optional and WillOnce() can be repeated. + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements some commonly used actions. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_ACTIONS_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_ACTIONS_H_ + +#ifndef _WIN32_WCE +# include +#endif + +#include +#include + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file defines some utilities useful for implementing Google +// Mock. They are subject to change without notice, so please DO NOT +// USE THEM IN USER CODE. + +#ifndef GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_INTERNAL_UTILS_H_ +#define GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_INTERNAL_UTILS_H_ + +#include +#include // NOLINT +#include + +// This file was GENERATED by command: +// pump.py gmock-generated-internal-utils.h.pump +// DO NOT EDIT BY HAND!!! + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file contains template meta-programming utility classes needed +// for implementing Google Mock. + +#ifndef GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_GENERATED_INTERNAL_UTILS_H_ +#define GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_GENERATED_INTERNAL_UTILS_H_ + +// Copyright 2008, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: vadimb@google.com (Vadim Berman) +// +// Low-level types and utilities for porting Google Mock to various +// platforms. All macros ending with _ and symbols defined in an +// internal namespace are subject to change without notice. Code +// outside Google Mock MUST NOT USE THEM DIRECTLY. Macros that don't +// end with _ are part of Google Mock's public API and can be used by +// code outside Google Mock. + +#ifndef GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_PORT_H_ +#define GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_PORT_H_ + +#include +#include +#include + +// Most of the utilities needed for porting Google Mock are also +// required for Google Test and are defined in gtest-port.h. +// +// Note to maintainers: to reduce code duplication, prefer adding +// portability utilities to Google Test's gtest-port.h instead of +// here, as Google Mock depends on Google Test. Only add a utility +// here if it's truly specific to Google Mock. +#include "gtest/gtest.h" +// Copyright 2015, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Injection point for custom user configurations. +// The following macros can be defined: +// +// Flag related macros: +// GMOCK_DECLARE_bool_(name) +// GMOCK_DECLARE_int32_(name) +// GMOCK_DECLARE_string_(name) +// GMOCK_DEFINE_bool_(name, default_val, doc) +// GMOCK_DEFINE_int32_(name, default_val, doc) +// GMOCK_DEFINE_string_(name, default_val, doc) +// +// ** Custom implementation starts here ** + +#ifndef GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_PORT_H_ +#define GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_PORT_H_ + +#endif // GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_PORT_H_ + +// To avoid conditional compilation everywhere, we make it +// gmock-port.h's responsibility to #include the header implementing +// tr1/tuple. gmock-port.h does this via gtest-port.h, which is +// guaranteed to pull in the tuple header. + +// For MS Visual C++, check the compiler version. At least VS 2003 is +// required to compile Google Mock. +#if defined(_MSC_VER) && _MSC_VER < 1310 +# error "At least Visual C++ 2003 (7.1) is required to compile Google Mock." +#endif + +// Macro for referencing flags. This is public as we want the user to +// use this syntax to reference Google Mock flags. +#define GMOCK_FLAG(name) FLAGS_gmock_##name + +#if !defined(GMOCK_DECLARE_bool_) + +// Macros for declaring flags. +#define GMOCK_DECLARE_bool_(name) extern GTEST_API_ bool GMOCK_FLAG(name) +#define GMOCK_DECLARE_int32_(name) \ + extern GTEST_API_ ::testing::internal::Int32 GMOCK_FLAG(name) +#define GMOCK_DECLARE_string_(name) \ + extern GTEST_API_ ::std::string GMOCK_FLAG(name) + +// Macros for defining flags. +#define GMOCK_DEFINE_bool_(name, default_val, doc) \ + GTEST_API_ bool GMOCK_FLAG(name) = (default_val) +#define GMOCK_DEFINE_int32_(name, default_val, doc) \ + GTEST_API_ ::testing::internal::Int32 GMOCK_FLAG(name) = (default_val) +#define GMOCK_DEFINE_string_(name, default_val, doc) \ + GTEST_API_ ::std::string GMOCK_FLAG(name) = (default_val) + +#endif // !defined(GMOCK_DECLARE_bool_) + +#endif // GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_PORT_H_ + +namespace testing { + +template +class Matcher; + +namespace internal { + +// An IgnoredValue object can be implicitly constructed from ANY value. +// This is used in implementing the IgnoreResult(a) action. +class IgnoredValue { + public: + // This constructor template allows any value to be implicitly + // converted to IgnoredValue. The object has no data member and + // doesn't try to remember anything about the argument. We + // deliberately omit the 'explicit' keyword in order to allow the + // conversion to be implicit. + template + IgnoredValue(const T& /* ignored */) {} // NOLINT(runtime/explicit) +}; + +// MatcherTuple::type is a tuple type where each field is a Matcher +// for the corresponding field in tuple type T. +template +struct MatcherTuple; + +template <> +struct MatcherTuple< ::testing::tuple<> > { + typedef ::testing::tuple< > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, + Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher, Matcher, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher, Matcher, Matcher, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher, Matcher, Matcher, Matcher, Matcher > type; +}; + +template +struct MatcherTuple< ::testing::tuple > { + typedef ::testing::tuple, Matcher, Matcher, Matcher, + Matcher, Matcher, Matcher, Matcher, Matcher, + Matcher > type; +}; + +// Template struct Function, where F must be a function type, contains +// the following typedefs: +// +// Result: the function's return type. +// ArgumentN: the type of the N-th argument, where N starts with 1. +// ArgumentTuple: the tuple type consisting of all parameters of F. +// ArgumentMatcherTuple: the tuple type consisting of Matchers for all +// parameters of F. +// MakeResultVoid: the function type obtained by substituting void +// for the return type of F. +// MakeResultIgnoredValue: +// the function type obtained by substituting Something +// for the return type of F. +template +struct Function; + +template +struct Function { + typedef R Result; + typedef ::testing::tuple<> ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(); + typedef IgnoredValue MakeResultIgnoredValue(); +}; + +template +struct Function + : Function { + typedef A1 Argument1; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1); + typedef IgnoredValue MakeResultIgnoredValue(A1); +}; + +template +struct Function + : Function { + typedef A2 Argument2; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2); +}; + +template +struct Function + : Function { + typedef A3 Argument3; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3); +}; + +template +struct Function + : Function { + typedef A4 Argument4; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4); +}; + +template +struct Function + : Function { + typedef A5 Argument5; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5); +}; + +template +struct Function + : Function { + typedef A6 Argument6; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5, A6); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5, A6); +}; + +template +struct Function + : Function { + typedef A7 Argument7; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5, A6, A7); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5, A6, A7); +}; + +template +struct Function + : Function { + typedef A8 Argument8; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5, A6, A7, A8); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5, A6, A7, A8); +}; + +template +struct Function + : Function { + typedef A9 Argument9; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5, A6, A7, A8, A9); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5, A6, A7, A8, + A9); +}; + +template +struct Function + : Function { + typedef A10 Argument10; + typedef ::testing::tuple ArgumentTuple; + typedef typename MatcherTuple::type ArgumentMatcherTuple; + typedef void MakeResultVoid(A1, A2, A3, A4, A5, A6, A7, A8, A9, A10); + typedef IgnoredValue MakeResultIgnoredValue(A1, A2, A3, A4, A5, A6, A7, A8, + A9, A10); +}; + +} // namespace internal + +} // namespace testing + +#endif // GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_GENERATED_INTERNAL_UTILS_H_ + +namespace testing { +namespace internal { + +// Converts an identifier name to a space-separated list of lower-case +// words. Each maximum substring of the form [A-Za-z][a-z]*|\d+ is +// treated as one word. For example, both "FooBar123" and +// "foo_bar_123" are converted to "foo bar 123". +GTEST_API_ string ConvertIdentifierNameToWords(const char* id_name); + +// PointeeOf::type is the type of a value pointed to by a +// Pointer, which can be either a smart pointer or a raw pointer. The +// following default implementation is for the case where Pointer is a +// smart pointer. +template +struct PointeeOf { + // Smart pointer classes define type element_type as the type of + // their pointees. + typedef typename Pointer::element_type type; +}; +// This specialization is for the raw pointer case. +template +struct PointeeOf { typedef T type; }; // NOLINT + +// GetRawPointer(p) returns the raw pointer underlying p when p is a +// smart pointer, or returns p itself when p is already a raw pointer. +// The following default implementation is for the smart pointer case. +template +inline const typename Pointer::element_type* GetRawPointer(const Pointer& p) { + return p.get(); +} +// This overloaded version is for the raw pointer case. +template +inline Element* GetRawPointer(Element* p) { return p; } + +// This comparator allows linked_ptr to be stored in sets. +template +struct LinkedPtrLessThan { + bool operator()(const ::testing::internal::linked_ptr& lhs, + const ::testing::internal::linked_ptr& rhs) const { + return lhs.get() < rhs.get(); + } +}; + +// Symbian compilation can be done with wchar_t being either a native +// type or a typedef. Using Google Mock with OpenC without wchar_t +// should require the definition of _STLP_NO_WCHAR_T. +// +// MSVC treats wchar_t as a native type usually, but treats it as the +// same as unsigned short when the compiler option /Zc:wchar_t- is +// specified. It defines _NATIVE_WCHAR_T_DEFINED symbol when wchar_t +// is a native type. +#if (GTEST_OS_SYMBIAN && defined(_STLP_NO_WCHAR_T)) || \ + (defined(_MSC_VER) && !defined(_NATIVE_WCHAR_T_DEFINED)) +// wchar_t is a typedef. +#else +# define GMOCK_WCHAR_T_IS_NATIVE_ 1 +#endif + +// signed wchar_t and unsigned wchar_t are NOT in the C++ standard. +// Using them is a bad practice and not portable. So DON'T use them. +// +// Still, Google Mock is designed to work even if the user uses signed +// wchar_t or unsigned wchar_t (obviously, assuming the compiler +// supports them). +// +// To gcc, +// wchar_t == signed wchar_t != unsigned wchar_t == unsigned int +#ifdef __GNUC__ +// signed/unsigned wchar_t are valid types. +# define GMOCK_HAS_SIGNED_WCHAR_T_ 1 +#endif + +// In what follows, we use the term "kind" to indicate whether a type +// is bool, an integer type (excluding bool), a floating-point type, +// or none of them. This categorization is useful for determining +// when a matcher argument type can be safely converted to another +// type in the implementation of SafeMatcherCast. +enum TypeKind { + kBool, kInteger, kFloatingPoint, kOther +}; + +// KindOf::value is the kind of type T. +template struct KindOf { + enum { value = kOther }; // The default kind. +}; + +// This macro declares that the kind of 'type' is 'kind'. +#define GMOCK_DECLARE_KIND_(type, kind) \ + template <> struct KindOf { enum { value = kind }; } + +GMOCK_DECLARE_KIND_(bool, kBool); + +// All standard integer types. +GMOCK_DECLARE_KIND_(char, kInteger); +GMOCK_DECLARE_KIND_(signed char, kInteger); +GMOCK_DECLARE_KIND_(unsigned char, kInteger); +GMOCK_DECLARE_KIND_(short, kInteger); // NOLINT +GMOCK_DECLARE_KIND_(unsigned short, kInteger); // NOLINT +GMOCK_DECLARE_KIND_(int, kInteger); +GMOCK_DECLARE_KIND_(unsigned int, kInteger); +GMOCK_DECLARE_KIND_(long, kInteger); // NOLINT +GMOCK_DECLARE_KIND_(unsigned long, kInteger); // NOLINT + +#if GMOCK_WCHAR_T_IS_NATIVE_ +GMOCK_DECLARE_KIND_(wchar_t, kInteger); +#endif + +// Non-standard integer types. +GMOCK_DECLARE_KIND_(Int64, kInteger); +GMOCK_DECLARE_KIND_(UInt64, kInteger); + +// All standard floating-point types. +GMOCK_DECLARE_KIND_(float, kFloatingPoint); +GMOCK_DECLARE_KIND_(double, kFloatingPoint); +GMOCK_DECLARE_KIND_(long double, kFloatingPoint); + +#undef GMOCK_DECLARE_KIND_ + +// Evaluates to the kind of 'type'. +#define GMOCK_KIND_OF_(type) \ + static_cast< ::testing::internal::TypeKind>( \ + ::testing::internal::KindOf::value) + +// Evaluates to true iff integer type T is signed. +#define GMOCK_IS_SIGNED_(T) (static_cast(-1) < 0) + +// LosslessArithmeticConvertibleImpl::value +// is true iff arithmetic type From can be losslessly converted to +// arithmetic type To. +// +// It's the user's responsibility to ensure that both From and To are +// raw (i.e. has no CV modifier, is not a pointer, and is not a +// reference) built-in arithmetic types, kFromKind is the kind of +// From, and kToKind is the kind of To; the value is +// implementation-defined when the above pre-condition is violated. +template +struct LosslessArithmeticConvertibleImpl : public false_type {}; + +// Converting bool to bool is lossless. +template <> +struct LosslessArithmeticConvertibleImpl + : public true_type {}; // NOLINT + +// Converting bool to any integer type is lossless. +template +struct LosslessArithmeticConvertibleImpl + : public true_type {}; // NOLINT + +// Converting bool to any floating-point type is lossless. +template +struct LosslessArithmeticConvertibleImpl + : public true_type {}; // NOLINT + +// Converting an integer to bool is lossy. +template +struct LosslessArithmeticConvertibleImpl + : public false_type {}; // NOLINT + +// Converting an integer to another non-bool integer is lossless iff +// the target type's range encloses the source type's range. +template +struct LosslessArithmeticConvertibleImpl + : public bool_constant< + // When converting from a smaller size to a larger size, we are + // fine as long as we are not converting from signed to unsigned. + ((sizeof(From) < sizeof(To)) && + (!GMOCK_IS_SIGNED_(From) || GMOCK_IS_SIGNED_(To))) || + // When converting between the same size, the signedness must match. + ((sizeof(From) == sizeof(To)) && + (GMOCK_IS_SIGNED_(From) == GMOCK_IS_SIGNED_(To)))> {}; // NOLINT + +#undef GMOCK_IS_SIGNED_ + +// Converting an integer to a floating-point type may be lossy, since +// the format of a floating-point number is implementation-defined. +template +struct LosslessArithmeticConvertibleImpl + : public false_type {}; // NOLINT + +// Converting a floating-point to bool is lossy. +template +struct LosslessArithmeticConvertibleImpl + : public false_type {}; // NOLINT + +// Converting a floating-point to an integer is lossy. +template +struct LosslessArithmeticConvertibleImpl + : public false_type {}; // NOLINT + +// Converting a floating-point to another floating-point is lossless +// iff the target type is at least as big as the source type. +template +struct LosslessArithmeticConvertibleImpl< + kFloatingPoint, From, kFloatingPoint, To> + : public bool_constant {}; // NOLINT + +// LosslessArithmeticConvertible::value is true iff arithmetic +// type From can be losslessly converted to arithmetic type To. +// +// It's the user's responsibility to ensure that both From and To are +// raw (i.e. has no CV modifier, is not a pointer, and is not a +// reference) built-in arithmetic types; the value is +// implementation-defined when the above pre-condition is violated. +template +struct LosslessArithmeticConvertible + : public LosslessArithmeticConvertibleImpl< + GMOCK_KIND_OF_(From), From, GMOCK_KIND_OF_(To), To> {}; // NOLINT + +// This interface knows how to report a Google Mock failure (either +// non-fatal or fatal). +class FailureReporterInterface { + public: + // The type of a failure (either non-fatal or fatal). + enum FailureType { + kNonfatal, kFatal + }; + + virtual ~FailureReporterInterface() {} + + // Reports a failure that occurred at the given source file location. + virtual void ReportFailure(FailureType type, const char* file, int line, + const string& message) = 0; +}; + +// Returns the failure reporter used by Google Mock. +GTEST_API_ FailureReporterInterface* GetFailureReporter(); + +// Asserts that condition is true; aborts the process with the given +// message if condition is false. We cannot use LOG(FATAL) or CHECK() +// as Google Mock might be used to mock the log sink itself. We +// inline this function to prevent it from showing up in the stack +// trace. +inline void Assert(bool condition, const char* file, int line, + const string& msg) { + if (!condition) { + GetFailureReporter()->ReportFailure(FailureReporterInterface::kFatal, + file, line, msg); + } +} +inline void Assert(bool condition, const char* file, int line) { + Assert(condition, file, line, "Assertion failed."); +} + +// Verifies that condition is true; generates a non-fatal failure if +// condition is false. +inline void Expect(bool condition, const char* file, int line, + const string& msg) { + if (!condition) { + GetFailureReporter()->ReportFailure(FailureReporterInterface::kNonfatal, + file, line, msg); + } +} +inline void Expect(bool condition, const char* file, int line) { + Expect(condition, file, line, "Expectation failed."); +} + +// Severity level of a log. +enum LogSeverity { + kInfo = 0, + kWarning = 1 +}; + +// Valid values for the --gmock_verbose flag. + +// All logs (informational and warnings) are printed. +const char kInfoVerbosity[] = "info"; +// Only warnings are printed. +const char kWarningVerbosity[] = "warning"; +// No logs are printed. +const char kErrorVerbosity[] = "error"; + +// Returns true iff a log with the given severity is visible according +// to the --gmock_verbose flag. +GTEST_API_ bool LogIsVisible(LogSeverity severity); + +// Prints the given message to stdout iff 'severity' >= the level +// specified by the --gmock_verbose flag. If stack_frames_to_skip >= +// 0, also prints the stack trace excluding the top +// stack_frames_to_skip frames. In opt mode, any positive +// stack_frames_to_skip is treated as 0, since we don't know which +// function calls will be inlined by the compiler and need to be +// conservative. +GTEST_API_ void Log(LogSeverity severity, + const string& message, + int stack_frames_to_skip); + +// TODO(wan@google.com): group all type utilities together. + +// Type traits. + +// is_reference::value is non-zero iff T is a reference type. +template struct is_reference : public false_type {}; +template struct is_reference : public true_type {}; + +// type_equals::value is non-zero iff T1 and T2 are the same type. +template struct type_equals : public false_type {}; +template struct type_equals : public true_type {}; + +// remove_reference::type removes the reference from type T, if any. +template struct remove_reference { typedef T type; }; // NOLINT +template struct remove_reference { typedef T type; }; // NOLINT + +// DecayArray::type turns an array type U[N] to const U* and preserves +// other types. Useful for saving a copy of a function argument. +template struct DecayArray { typedef T type; }; // NOLINT +template struct DecayArray { + typedef const T* type; +}; +// Sometimes people use arrays whose size is not available at the use site +// (e.g. extern const char kNamePrefix[]). This specialization covers that +// case. +template struct DecayArray { + typedef const T* type; +}; + +// Disable MSVC warnings for infinite recursion, since in this case the +// the recursion is unreachable. +#ifdef _MSC_VER +# pragma warning(push) +# pragma warning(disable:4717) +#endif + +// Invalid() is usable as an expression of type T, but will terminate +// the program with an assertion failure if actually run. This is useful +// when a value of type T is needed for compilation, but the statement +// will not really be executed (or we don't care if the statement +// crashes). +template +inline T Invalid() { + Assert(false, "", -1, "Internal error: attempt to return invalid value"); + // This statement is unreachable, and would never terminate even if it + // could be reached. It is provided only to placate compiler warnings + // about missing return statements. + return Invalid(); +} + +#ifdef _MSC_VER +# pragma warning(pop) +#endif + +// Given a raw type (i.e. having no top-level reference or const +// modifier) RawContainer that's either an STL-style container or a +// native array, class StlContainerView has the +// following members: +// +// - type is a type that provides an STL-style container view to +// (i.e. implements the STL container concept for) RawContainer; +// - const_reference is a type that provides a reference to a const +// RawContainer; +// - ConstReference(raw_container) returns a const reference to an STL-style +// container view to raw_container, which is a RawContainer. +// - Copy(raw_container) returns an STL-style container view of a +// copy of raw_container, which is a RawContainer. +// +// This generic version is used when RawContainer itself is already an +// STL-style container. +template +class StlContainerView { + public: + typedef RawContainer type; + typedef const type& const_reference; + + static const_reference ConstReference(const RawContainer& container) { + // Ensures that RawContainer is not a const type. + testing::StaticAssertTypeEq(); + return container; + } + static type Copy(const RawContainer& container) { return container; } +}; + +// This specialization is used when RawContainer is a native array type. +template +class StlContainerView { + public: + typedef GTEST_REMOVE_CONST_(Element) RawElement; + typedef internal::NativeArray type; + // NativeArray can represent a native array either by value or by + // reference (selected by a constructor argument), so 'const type' + // can be used to reference a const native array. We cannot + // 'typedef const type& const_reference' here, as that would mean + // ConstReference() has to return a reference to a local variable. + typedef const type const_reference; + + static const_reference ConstReference(const Element (&array)[N]) { + // Ensures that Element is not a const type. + testing::StaticAssertTypeEq(); +#if GTEST_OS_SYMBIAN + // The Nokia Symbian compiler confuses itself in template instantiation + // for this call without the cast to Element*: + // function call '[testing::internal::NativeArray].NativeArray( + // {lval} const char *[4], long, testing::internal::RelationToSource)' + // does not match + // 'testing::internal::NativeArray::NativeArray( + // char *const *, unsigned int, testing::internal::RelationToSource)' + // (instantiating: 'testing::internal::ContainsMatcherImpl + // ::Matches(const char * (&)[4]) const') + // (instantiating: 'testing::internal::StlContainerView:: + // ConstReference(const char * (&)[4])') + // (and though the N parameter type is mismatched in the above explicit + // conversion of it doesn't help - only the conversion of the array). + return type(const_cast(&array[0]), N, + RelationToSourceReference()); +#else + return type(array, N, RelationToSourceReference()); +#endif // GTEST_OS_SYMBIAN + } + static type Copy(const Element (&array)[N]) { +#if GTEST_OS_SYMBIAN + return type(const_cast(&array[0]), N, RelationToSourceCopy()); +#else + return type(array, N, RelationToSourceCopy()); +#endif // GTEST_OS_SYMBIAN + } +}; + +// This specialization is used when RawContainer is a native array +// represented as a (pointer, size) tuple. +template +class StlContainerView< ::testing::tuple > { + public: + typedef GTEST_REMOVE_CONST_( + typename internal::PointeeOf::type) RawElement; + typedef internal::NativeArray type; + typedef const type const_reference; + + static const_reference ConstReference( + const ::testing::tuple& array) { + return type(get<0>(array), get<1>(array), RelationToSourceReference()); + } + static type Copy(const ::testing::tuple& array) { + return type(get<0>(array), get<1>(array), RelationToSourceCopy()); + } +}; + +// The following specialization prevents the user from instantiating +// StlContainer with a reference type. +template class StlContainerView; + +// A type transform to remove constness from the first part of a pair. +// Pairs like that are used as the value_type of associative containers, +// and this transform produces a similar but assignable pair. +template +struct RemoveConstFromKey { + typedef T type; +}; + +// Partially specialized to remove constness from std::pair. +template +struct RemoveConstFromKey > { + typedef std::pair type; +}; + +// Mapping from booleans to types. Similar to boost::bool_ and +// std::integral_constant. +template +struct BooleanConstant {}; + +} // namespace internal +} // namespace testing + +#endif // GMOCK_INCLUDE_GMOCK_INTERNAL_GMOCK_INTERNAL_UTILS_H_ + + +#if GTEST_HAS_STD_TYPE_TRAITS_ // Defined by gtest-port.h via gmock-port.h. +#include +#endif + +namespace testing { + +// To implement an action Foo, define: +// 1. a class FooAction that implements the ActionInterface interface, and +// 2. a factory function that creates an Action object from a +// const FooAction*. +// +// The two-level delegation design follows that of Matcher, providing +// consistency for extension developers. It also eases ownership +// management as Action objects can now be copied like plain values. + +namespace internal { + +template +class ActionAdaptor; + +// BuiltInDefaultValueGetter::Get() returns a +// default-constructed T value. BuiltInDefaultValueGetter::Get() crashes with an error. +// +// This primary template is used when kDefaultConstructible is true. +template +struct BuiltInDefaultValueGetter { + static T Get() { return T(); } +}; +template +struct BuiltInDefaultValueGetter { + static T Get() { + Assert(false, __FILE__, __LINE__, + "Default action undefined for the function return type."); + return internal::Invalid(); + // The above statement will never be reached, but is required in + // order for this function to compile. + } +}; + +// BuiltInDefaultValue::Get() returns the "built-in" default value +// for type T, which is NULL when T is a raw pointer type, 0 when T is +// a numeric type, false when T is bool, or "" when T is string or +// std::string. In addition, in C++11 and above, it turns a +// default-constructed T value if T is default constructible. For any +// other type T, the built-in default T value is undefined, and the +// function will abort the process. +template +class BuiltInDefaultValue { + public: +#if GTEST_HAS_STD_TYPE_TRAITS_ + // This function returns true iff type T has a built-in default value. + static bool Exists() { + return ::std::is_default_constructible::value; + } + + static T Get() { + return BuiltInDefaultValueGetter< + T, ::std::is_default_constructible::value>::Get(); + } + +#else // GTEST_HAS_STD_TYPE_TRAITS_ + // This function returns true iff type T has a built-in default value. + static bool Exists() { + return false; + } + + static T Get() { + return BuiltInDefaultValueGetter::Get(); + } + +#endif // GTEST_HAS_STD_TYPE_TRAITS_ +}; + +// This partial specialization says that we use the same built-in +// default value for T and const T. +template +class BuiltInDefaultValue { + public: + static bool Exists() { return BuiltInDefaultValue::Exists(); } + static T Get() { return BuiltInDefaultValue::Get(); } +}; + +// This partial specialization defines the default values for pointer +// types. +template +class BuiltInDefaultValue { + public: + static bool Exists() { return true; } + static T* Get() { return NULL; } +}; + +// The following specializations define the default values for +// specific types we care about. +#define GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(type, value) \ + template <> \ + class BuiltInDefaultValue { \ + public: \ + static bool Exists() { return true; } \ + static type Get() { return value; } \ + } + +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(void, ); // NOLINT +#if GTEST_HAS_GLOBAL_STRING +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(::string, ""); +#endif // GTEST_HAS_GLOBAL_STRING +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(::std::string, ""); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(bool, false); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(unsigned char, '\0'); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(signed char, '\0'); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(char, '\0'); + +// There's no need for a default action for signed wchar_t, as that +// type is the same as wchar_t for gcc, and invalid for MSVC. +// +// There's also no need for a default action for unsigned wchar_t, as +// that type is the same as unsigned int for gcc, and invalid for +// MSVC. +#if GMOCK_WCHAR_T_IS_NATIVE_ +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(wchar_t, 0U); // NOLINT +#endif + +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(unsigned short, 0U); // NOLINT +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(signed short, 0); // NOLINT +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(unsigned int, 0U); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(signed int, 0); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(unsigned long, 0UL); // NOLINT +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(signed long, 0L); // NOLINT +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(UInt64, 0); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(Int64, 0); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(float, 0); +GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_(double, 0); + +#undef GMOCK_DEFINE_DEFAULT_ACTION_FOR_RETURN_TYPE_ + +} // namespace internal + +// When an unexpected function call is encountered, Google Mock will +// let it return a default value if the user has specified one for its +// return type, or if the return type has a built-in default value; +// otherwise Google Mock won't know what value to return and will have +// to abort the process. +// +// The DefaultValue class allows a user to specify the +// default value for a type T that is both copyable and publicly +// destructible (i.e. anything that can be used as a function return +// type). The usage is: +// +// // Sets the default value for type T to be foo. +// DefaultValue::Set(foo); +template +class DefaultValue { + public: + // Sets the default value for type T; requires T to be + // copy-constructable and have a public destructor. + static void Set(T x) { + delete producer_; + producer_ = new FixedValueProducer(x); + } + + // Provides a factory function to be called to generate the default value. + // This method can be used even if T is only move-constructible, but it is not + // limited to that case. + typedef T (*FactoryFunction)(); + static void SetFactory(FactoryFunction factory) { + delete producer_; + producer_ = new FactoryValueProducer(factory); + } + + // Unsets the default value for type T. + static void Clear() { + delete producer_; + producer_ = NULL; + } + + // Returns true iff the user has set the default value for type T. + static bool IsSet() { return producer_ != NULL; } + + // Returns true if T has a default return value set by the user or there + // exists a built-in default value. + static bool Exists() { + return IsSet() || internal::BuiltInDefaultValue::Exists(); + } + + // Returns the default value for type T if the user has set one; + // otherwise returns the built-in default value. Requires that Exists() + // is true, which ensures that the return value is well-defined. + static T Get() { + return producer_ == NULL ? + internal::BuiltInDefaultValue::Get() : producer_->Produce(); + } + + private: + class ValueProducer { + public: + virtual ~ValueProducer() {} + virtual T Produce() = 0; + }; + + class FixedValueProducer : public ValueProducer { + public: + explicit FixedValueProducer(T value) : value_(value) {} + virtual T Produce() { return value_; } + + private: + const T value_; + GTEST_DISALLOW_COPY_AND_ASSIGN_(FixedValueProducer); + }; + + class FactoryValueProducer : public ValueProducer { + public: + explicit FactoryValueProducer(FactoryFunction factory) + : factory_(factory) {} + virtual T Produce() { return factory_(); } + + private: + const FactoryFunction factory_; + GTEST_DISALLOW_COPY_AND_ASSIGN_(FactoryValueProducer); + }; + + static ValueProducer* producer_; +}; + +// This partial specialization allows a user to set default values for +// reference types. +template +class DefaultValue { + public: + // Sets the default value for type T&. + static void Set(T& x) { // NOLINT + address_ = &x; + } + + // Unsets the default value for type T&. + static void Clear() { + address_ = NULL; + } + + // Returns true iff the user has set the default value for type T&. + static bool IsSet() { return address_ != NULL; } + + // Returns true if T has a default return value set by the user or there + // exists a built-in default value. + static bool Exists() { + return IsSet() || internal::BuiltInDefaultValue::Exists(); + } + + // Returns the default value for type T& if the user has set one; + // otherwise returns the built-in default value if there is one; + // otherwise aborts the process. + static T& Get() { + return address_ == NULL ? + internal::BuiltInDefaultValue::Get() : *address_; + } + + private: + static T* address_; +}; + +// This specialization allows DefaultValue::Get() to +// compile. +template <> +class DefaultValue { + public: + static bool Exists() { return true; } + static void Get() {} +}; + +// Points to the user-set default value for type T. +template +typename DefaultValue::ValueProducer* DefaultValue::producer_ = NULL; + +// Points to the user-set default value for type T&. +template +T* DefaultValue::address_ = NULL; + +// Implement this interface to define an action for function type F. +template +class ActionInterface { + public: + typedef typename internal::Function::Result Result; + typedef typename internal::Function::ArgumentTuple ArgumentTuple; + + ActionInterface() {} + virtual ~ActionInterface() {} + + // Performs the action. This method is not const, as in general an + // action can have side effects and be stateful. For example, a + // get-the-next-element-from-the-collection action will need to + // remember the current element. + virtual Result Perform(const ArgumentTuple& args) = 0; + + private: + GTEST_DISALLOW_COPY_AND_ASSIGN_(ActionInterface); +}; + +// An Action is a copyable and IMMUTABLE (except by assignment) +// object that represents an action to be taken when a mock function +// of type F is called. The implementation of Action is just a +// linked_ptr to const ActionInterface, so copying is fairly cheap. +// Don't inherit from Action! +// +// You can view an object implementing ActionInterface as a +// concrete action (including its current state), and an Action +// object as a handle to it. +template +class Action { + public: + typedef typename internal::Function::Result Result; + typedef typename internal::Function::ArgumentTuple ArgumentTuple; + + // Constructs a null Action. Needed for storing Action objects in + // STL containers. + Action() : impl_(NULL) {} + + // Constructs an Action from its implementation. A NULL impl is + // used to represent the "do-default" action. + explicit Action(ActionInterface* impl) : impl_(impl) {} + + // Copy constructor. + Action(const Action& action) : impl_(action.impl_) {} + + // This constructor allows us to turn an Action object into an + // Action, as long as F's arguments can be implicitly converted + // to Func's and Func's return type can be implicitly converted to + // F's. + template + explicit Action(const Action& action); + + // Returns true iff this is the DoDefault() action. + bool IsDoDefault() const { return impl_.get() == NULL; } + + // Performs the action. Note that this method is const even though + // the corresponding method in ActionInterface is not. The reason + // is that a const Action means that it cannot be re-bound to + // another concrete action, not that the concrete action it binds to + // cannot change state. (Think of the difference between a const + // pointer and a pointer to const.) + Result Perform(const ArgumentTuple& args) const { + internal::Assert( + !IsDoDefault(), __FILE__, __LINE__, + "You are using DoDefault() inside a composite action like " + "DoAll() or WithArgs(). This is not supported for technical " + "reasons. Please instead spell out the default action, or " + "assign the default action to an Action variable and use " + "the variable in various places."); + return impl_->Perform(args); + } + + private: + template + friend class internal::ActionAdaptor; + + internal::linked_ptr > impl_; +}; + +// The PolymorphicAction class template makes it easy to implement a +// polymorphic action (i.e. an action that can be used in mock +// functions of than one type, e.g. Return()). +// +// To define a polymorphic action, a user first provides a COPYABLE +// implementation class that has a Perform() method template: +// +// class FooAction { +// public: +// template +// Result Perform(const ArgumentTuple& args) const { +// // Processes the arguments and returns a result, using +// // tr1::get(args) to get the N-th (0-based) argument in the tuple. +// } +// ... +// }; +// +// Then the user creates the polymorphic action using +// MakePolymorphicAction(object) where object has type FooAction. See +// the definition of Return(void) and SetArgumentPointee(value) for +// complete examples. +template +class PolymorphicAction { + public: + explicit PolymorphicAction(const Impl& impl) : impl_(impl) {} + + template + operator Action() const { + return Action(new MonomorphicImpl(impl_)); + } + + private: + template + class MonomorphicImpl : public ActionInterface { + public: + typedef typename internal::Function::Result Result; + typedef typename internal::Function::ArgumentTuple ArgumentTuple; + + explicit MonomorphicImpl(const Impl& impl) : impl_(impl) {} + + virtual Result Perform(const ArgumentTuple& args) { + return impl_.template Perform(args); + } + + private: + Impl impl_; + + GTEST_DISALLOW_ASSIGN_(MonomorphicImpl); + }; + + Impl impl_; + + GTEST_DISALLOW_ASSIGN_(PolymorphicAction); +}; + +// Creates an Action from its implementation and returns it. The +// created Action object owns the implementation. +template +Action MakeAction(ActionInterface* impl) { + return Action(impl); +} + +// Creates a polymorphic action from its implementation. This is +// easier to use than the PolymorphicAction constructor as it +// doesn't require you to explicitly write the template argument, e.g. +// +// MakePolymorphicAction(foo); +// vs +// PolymorphicAction(foo); +template +inline PolymorphicAction MakePolymorphicAction(const Impl& impl) { + return PolymorphicAction(impl); +} + +namespace internal { + +// Allows an Action object to pose as an Action, as long as F2 +// and F1 are compatible. +template +class ActionAdaptor : public ActionInterface { + public: + typedef typename internal::Function::Result Result; + typedef typename internal::Function::ArgumentTuple ArgumentTuple; + + explicit ActionAdaptor(const Action& from) : impl_(from.impl_) {} + + virtual Result Perform(const ArgumentTuple& args) { + return impl_->Perform(args); + } + + private: + const internal::linked_ptr > impl_; + + GTEST_DISALLOW_ASSIGN_(ActionAdaptor); +}; + +// Helper struct to specialize ReturnAction to execute a move instead of a copy +// on return. Useful for move-only types, but could be used on any type. +template +struct ByMoveWrapper { + explicit ByMoveWrapper(T value) : payload(internal::move(value)) {} + T payload; +}; + +// Implements the polymorphic Return(x) action, which can be used in +// any function that returns the type of x, regardless of the argument +// types. +// +// Note: The value passed into Return must be converted into +// Function::Result when this action is cast to Action rather than +// when that action is performed. This is important in scenarios like +// +// MOCK_METHOD1(Method, T(U)); +// ... +// { +// Foo foo; +// X x(&foo); +// EXPECT_CALL(mock, Method(_)).WillOnce(Return(x)); +// } +// +// In the example above the variable x holds reference to foo which leaves +// scope and gets destroyed. If copying X just copies a reference to foo, +// that copy will be left with a hanging reference. If conversion to T +// makes a copy of foo, the above code is safe. To support that scenario, we +// need to make sure that the type conversion happens inside the EXPECT_CALL +// statement, and conversion of the result of Return to Action is a +// good place for that. +// +template +class ReturnAction { + public: + // Constructs a ReturnAction object from the value to be returned. + // 'value' is passed by value instead of by const reference in order + // to allow Return("string literal") to compile. + explicit ReturnAction(R value) : value_(new R(internal::move(value))) {} + + // This template type conversion operator allows Return(x) to be + // used in ANY function that returns x's type. + template + operator Action() const { + // Assert statement belongs here because this is the best place to verify + // conditions on F. It produces the clearest error messages + // in most compilers. + // Impl really belongs in this scope as a local class but can't + // because MSVC produces duplicate symbols in different translation units + // in this case. Until MS fixes that bug we put Impl into the class scope + // and put the typedef both here (for use in assert statement) and + // in the Impl class. But both definitions must be the same. + typedef typename Function::Result Result; + GTEST_COMPILE_ASSERT_( + !is_reference::value, + use_ReturnRef_instead_of_Return_to_return_a_reference); + return Action(new Impl(value_)); + } + + private: + // Implements the Return(x) action for a particular function type F. + template + class Impl : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + + // The implicit cast is necessary when Result has more than one + // single-argument constructor (e.g. Result is std::vector) and R + // has a type conversion operator template. In that case, value_(value) + // won't compile as the compiler doesn't known which constructor of + // Result to call. ImplicitCast_ forces the compiler to convert R to + // Result without considering explicit constructors, thus resolving the + // ambiguity. value_ is then initialized using its copy constructor. + explicit Impl(const linked_ptr& value) + : value_before_cast_(*value), + value_(ImplicitCast_(value_before_cast_)) {} + + virtual Result Perform(const ArgumentTuple&) { return value_; } + + private: + GTEST_COMPILE_ASSERT_(!is_reference::value, + Result_cannot_be_a_reference_type); + // We save the value before casting just in case it is being cast to a + // wrapper type. + R value_before_cast_; + Result value_; + + GTEST_DISALLOW_COPY_AND_ASSIGN_(Impl); + }; + + // Partially specialize for ByMoveWrapper. This version of ReturnAction will + // move its contents instead. + template + class Impl, F> : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + + explicit Impl(const linked_ptr& wrapper) + : performed_(false), wrapper_(wrapper) {} + + virtual Result Perform(const ArgumentTuple&) { + GTEST_CHECK_(!performed_) + << "A ByMove() action should only be performed once."; + performed_ = true; + return internal::move(wrapper_->payload); + } + + private: + bool performed_; + const linked_ptr wrapper_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + const linked_ptr value_; + + GTEST_DISALLOW_ASSIGN_(ReturnAction); +}; + +// Implements the ReturnNull() action. +class ReturnNullAction { + public: + // Allows ReturnNull() to be used in any pointer-returning function. In C++11 + // this is enforced by returning nullptr, and in non-C++11 by asserting a + // pointer type on compile time. + template + static Result Perform(const ArgumentTuple&) { +#if GTEST_LANG_CXX11 + return nullptr; +#else + GTEST_COMPILE_ASSERT_(internal::is_pointer::value, + ReturnNull_can_be_used_to_return_a_pointer_only); + return NULL; +#endif // GTEST_LANG_CXX11 + } +}; + +// Implements the Return() action. +class ReturnVoidAction { + public: + // Allows Return() to be used in any void-returning function. + template + static void Perform(const ArgumentTuple&) { + CompileAssertTypesEqual(); + } +}; + +// Implements the polymorphic ReturnRef(x) action, which can be used +// in any function that returns a reference to the type of x, +// regardless of the argument types. +template +class ReturnRefAction { + public: + // Constructs a ReturnRefAction object from the reference to be returned. + explicit ReturnRefAction(T& ref) : ref_(ref) {} // NOLINT + + // This template type conversion operator allows ReturnRef(x) to be + // used in ANY function that returns a reference to x's type. + template + operator Action() const { + typedef typename Function::Result Result; + // Asserts that the function return type is a reference. This + // catches the user error of using ReturnRef(x) when Return(x) + // should be used, and generates some helpful error message. + GTEST_COMPILE_ASSERT_(internal::is_reference::value, + use_Return_instead_of_ReturnRef_to_return_a_value); + return Action(new Impl(ref_)); + } + + private: + // Implements the ReturnRef(x) action for a particular function type F. + template + class Impl : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + + explicit Impl(T& ref) : ref_(ref) {} // NOLINT + + virtual Result Perform(const ArgumentTuple&) { + return ref_; + } + + private: + T& ref_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + T& ref_; + + GTEST_DISALLOW_ASSIGN_(ReturnRefAction); +}; + +// Implements the polymorphic ReturnRefOfCopy(x) action, which can be +// used in any function that returns a reference to the type of x, +// regardless of the argument types. +template +class ReturnRefOfCopyAction { + public: + // Constructs a ReturnRefOfCopyAction object from the reference to + // be returned. + explicit ReturnRefOfCopyAction(const T& value) : value_(value) {} // NOLINT + + // This template type conversion operator allows ReturnRefOfCopy(x) to be + // used in ANY function that returns a reference to x's type. + template + operator Action() const { + typedef typename Function::Result Result; + // Asserts that the function return type is a reference. This + // catches the user error of using ReturnRefOfCopy(x) when Return(x) + // should be used, and generates some helpful error message. + GTEST_COMPILE_ASSERT_( + internal::is_reference::value, + use_Return_instead_of_ReturnRefOfCopy_to_return_a_value); + return Action(new Impl(value_)); + } + + private: + // Implements the ReturnRefOfCopy(x) action for a particular function type F. + template + class Impl : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + + explicit Impl(const T& value) : value_(value) {} // NOLINT + + virtual Result Perform(const ArgumentTuple&) { + return value_; + } + + private: + T value_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + const T value_; + + GTEST_DISALLOW_ASSIGN_(ReturnRefOfCopyAction); +}; + +// Implements the polymorphic DoDefault() action. +class DoDefaultAction { + public: + // This template type conversion operator allows DoDefault() to be + // used in any function. + template + operator Action() const { return Action(NULL); } +}; + +// Implements the Assign action to set a given pointer referent to a +// particular value. +template +class AssignAction { + public: + AssignAction(T1* ptr, T2 value) : ptr_(ptr), value_(value) {} + + template + void Perform(const ArgumentTuple& /* args */) const { + *ptr_ = value_; + } + + private: + T1* const ptr_; + const T2 value_; + + GTEST_DISALLOW_ASSIGN_(AssignAction); +}; + +#if !GTEST_OS_WINDOWS_MOBILE + +// Implements the SetErrnoAndReturn action to simulate return from +// various system calls and libc functions. +template +class SetErrnoAndReturnAction { + public: + SetErrnoAndReturnAction(int errno_value, T result) + : errno_(errno_value), + result_(result) {} + template + Result Perform(const ArgumentTuple& /* args */) const { + errno = errno_; + return result_; + } + + private: + const int errno_; + const T result_; + + GTEST_DISALLOW_ASSIGN_(SetErrnoAndReturnAction); +}; + +#endif // !GTEST_OS_WINDOWS_MOBILE + +// Implements the SetArgumentPointee(x) action for any function +// whose N-th argument (0-based) is a pointer to x's type. The +// template parameter kIsProto is true iff type A is ProtocolMessage, +// proto2::Message, or a sub-class of those. +template +class SetArgumentPointeeAction { + public: + // Constructs an action that sets the variable pointed to by the + // N-th function argument to 'value'. + explicit SetArgumentPointeeAction(const A& value) : value_(value) {} + + template + void Perform(const ArgumentTuple& args) const { + CompileAssertTypesEqual(); + *::testing::get(args) = value_; + } + + private: + const A value_; + + GTEST_DISALLOW_ASSIGN_(SetArgumentPointeeAction); +}; + +template +class SetArgumentPointeeAction { + public: + // Constructs an action that sets the variable pointed to by the + // N-th function argument to 'proto'. Both ProtocolMessage and + // proto2::Message have the CopyFrom() method, so the same + // implementation works for both. + explicit SetArgumentPointeeAction(const Proto& proto) : proto_(new Proto) { + proto_->CopyFrom(proto); + } + + template + void Perform(const ArgumentTuple& args) const { + CompileAssertTypesEqual(); + ::testing::get(args)->CopyFrom(*proto_); + } + + private: + const internal::linked_ptr proto_; + + GTEST_DISALLOW_ASSIGN_(SetArgumentPointeeAction); +}; + +// Implements the InvokeWithoutArgs(f) action. The template argument +// FunctionImpl is the implementation type of f, which can be either a +// function pointer or a functor. InvokeWithoutArgs(f) can be used as an +// Action as long as f's type is compatible with F (i.e. f can be +// assigned to a tr1::function). +template +class InvokeWithoutArgsAction { + public: + // The c'tor makes a copy of function_impl (either a function + // pointer or a functor). + explicit InvokeWithoutArgsAction(FunctionImpl function_impl) + : function_impl_(function_impl) {} + + // Allows InvokeWithoutArgs(f) to be used as any action whose type is + // compatible with f. + template + Result Perform(const ArgumentTuple&) { return function_impl_(); } + + private: + FunctionImpl function_impl_; + + GTEST_DISALLOW_ASSIGN_(InvokeWithoutArgsAction); +}; + +// Implements the InvokeWithoutArgs(object_ptr, &Class::Method) action. +template +class InvokeMethodWithoutArgsAction { + public: + InvokeMethodWithoutArgsAction(Class* obj_ptr, MethodPtr method_ptr) + : obj_ptr_(obj_ptr), method_ptr_(method_ptr) {} + + template + Result Perform(const ArgumentTuple&) const { + return (obj_ptr_->*method_ptr_)(); + } + + private: + Class* const obj_ptr_; + const MethodPtr method_ptr_; + + GTEST_DISALLOW_ASSIGN_(InvokeMethodWithoutArgsAction); +}; + +// Implements the IgnoreResult(action) action. +template +class IgnoreResultAction { + public: + explicit IgnoreResultAction(const A& action) : action_(action) {} + + template + operator Action() const { + // Assert statement belongs here because this is the best place to verify + // conditions on F. It produces the clearest error messages + // in most compilers. + // Impl really belongs in this scope as a local class but can't + // because MSVC produces duplicate symbols in different translation units + // in this case. Until MS fixes that bug we put Impl into the class scope + // and put the typedef both here (for use in assert statement) and + // in the Impl class. But both definitions must be the same. + typedef typename internal::Function::Result Result; + + // Asserts at compile time that F returns void. + CompileAssertTypesEqual(); + + return Action(new Impl(action_)); + } + + private: + template + class Impl : public ActionInterface { + public: + typedef typename internal::Function::Result Result; + typedef typename internal::Function::ArgumentTuple ArgumentTuple; + + explicit Impl(const A& action) : action_(action) {} + + virtual void Perform(const ArgumentTuple& args) { + // Performs the action and ignores its result. + action_.Perform(args); + } + + private: + // Type OriginalFunction is the same as F except that its return + // type is IgnoredValue. + typedef typename internal::Function::MakeResultIgnoredValue + OriginalFunction; + + const Action action_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + const A action_; + + GTEST_DISALLOW_ASSIGN_(IgnoreResultAction); +}; + +// A ReferenceWrapper object represents a reference to type T, +// which can be either const or not. It can be explicitly converted +// from, and implicitly converted to, a T&. Unlike a reference, +// ReferenceWrapper can be copied and can survive template type +// inference. This is used to support by-reference arguments in the +// InvokeArgument(...) action. The idea was from "reference +// wrappers" in tr1, which we don't have in our source tree yet. +template +class ReferenceWrapper { + public: + // Constructs a ReferenceWrapper object from a T&. + explicit ReferenceWrapper(T& l_value) : pointer_(&l_value) {} // NOLINT + + // Allows a ReferenceWrapper object to be implicitly converted to + // a T&. + operator T&() const { return *pointer_; } + private: + T* pointer_; +}; + +// Allows the expression ByRef(x) to be printed as a reference to x. +template +void PrintTo(const ReferenceWrapper& ref, ::std::ostream* os) { + T& value = ref; + UniversalPrinter::Print(value, os); +} + +// Does two actions sequentially. Used for implementing the DoAll(a1, +// a2, ...) action. +template +class DoBothAction { + public: + DoBothAction(Action1 action1, Action2 action2) + : action1_(action1), action2_(action2) {} + + // This template type conversion operator allows DoAll(a1, ..., a_n) + // to be used in ANY function of compatible type. + template + operator Action() const { + return Action(new Impl(action1_, action2_)); + } + + private: + // Implements the DoAll(...) action for a particular function type F. + template + class Impl : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + typedef typename Function::MakeResultVoid VoidResult; + + Impl(const Action& action1, const Action& action2) + : action1_(action1), action2_(action2) {} + + virtual Result Perform(const ArgumentTuple& args) { + action1_.Perform(args); + return action2_.Perform(args); + } + + private: + const Action action1_; + const Action action2_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + Action1 action1_; + Action2 action2_; + + GTEST_DISALLOW_ASSIGN_(DoBothAction); +}; + +} // namespace internal + +// An Unused object can be implicitly constructed from ANY value. +// This is handy when defining actions that ignore some or all of the +// mock function arguments. For example, given +// +// MOCK_METHOD3(Foo, double(const string& label, double x, double y)); +// MOCK_METHOD3(Bar, double(int index, double x, double y)); +// +// instead of +// +// double DistanceToOriginWithLabel(const string& label, double x, double y) { +// return sqrt(x*x + y*y); +// } +// double DistanceToOriginWithIndex(int index, double x, double y) { +// return sqrt(x*x + y*y); +// } +// ... +// EXEPCT_CALL(mock, Foo("abc", _, _)) +// .WillOnce(Invoke(DistanceToOriginWithLabel)); +// EXEPCT_CALL(mock, Bar(5, _, _)) +// .WillOnce(Invoke(DistanceToOriginWithIndex)); +// +// you could write +// +// // We can declare any uninteresting argument as Unused. +// double DistanceToOrigin(Unused, double x, double y) { +// return sqrt(x*x + y*y); +// } +// ... +// EXEPCT_CALL(mock, Foo("abc", _, _)).WillOnce(Invoke(DistanceToOrigin)); +// EXEPCT_CALL(mock, Bar(5, _, _)).WillOnce(Invoke(DistanceToOrigin)); +typedef internal::IgnoredValue Unused; + +// This constructor allows us to turn an Action object into an +// Action, as long as To's arguments can be implicitly converted +// to From's and From's return type cann be implicitly converted to +// To's. +template +template +Action::Action(const Action& from) + : impl_(new internal::ActionAdaptor(from)) {} + +// Creates an action that returns 'value'. 'value' is passed by value +// instead of const reference - otherwise Return("string literal") +// will trigger a compiler error about using array as initializer. +template +internal::ReturnAction Return(R value) { + return internal::ReturnAction(internal::move(value)); +} + +// Creates an action that returns NULL. +inline PolymorphicAction ReturnNull() { + return MakePolymorphicAction(internal::ReturnNullAction()); +} + +// Creates an action that returns from a void function. +inline PolymorphicAction Return() { + return MakePolymorphicAction(internal::ReturnVoidAction()); +} + +// Creates an action that returns the reference to a variable. +template +inline internal::ReturnRefAction ReturnRef(R& x) { // NOLINT + return internal::ReturnRefAction(x); +} + +// Creates an action that returns the reference to a copy of the +// argument. The copy is created when the action is constructed and +// lives as long as the action. +template +inline internal::ReturnRefOfCopyAction ReturnRefOfCopy(const R& x) { + return internal::ReturnRefOfCopyAction(x); +} + +// Modifies the parent action (a Return() action) to perform a move of the +// argument instead of a copy. +// Return(ByMove()) actions can only be executed once and will assert this +// invariant. +template +internal::ByMoveWrapper ByMove(R x) { + return internal::ByMoveWrapper(internal::move(x)); +} + +// Creates an action that does the default action for the give mock function. +inline internal::DoDefaultAction DoDefault() { + return internal::DoDefaultAction(); +} + +// Creates an action that sets the variable pointed by the N-th +// (0-based) function argument to 'value'. +template +PolymorphicAction< + internal::SetArgumentPointeeAction< + N, T, internal::IsAProtocolMessage::value> > +SetArgPointee(const T& x) { + return MakePolymorphicAction(internal::SetArgumentPointeeAction< + N, T, internal::IsAProtocolMessage::value>(x)); +} + +#if !((GTEST_GCC_VER_ && GTEST_GCC_VER_ < 40000) || GTEST_OS_SYMBIAN) +// This overload allows SetArgPointee() to accept a string literal. +// GCC prior to the version 4.0 and Symbian C++ compiler cannot distinguish +// this overload from the templated version and emit a compile error. +template +PolymorphicAction< + internal::SetArgumentPointeeAction > +SetArgPointee(const char* p) { + return MakePolymorphicAction(internal::SetArgumentPointeeAction< + N, const char*, false>(p)); +} + +template +PolymorphicAction< + internal::SetArgumentPointeeAction > +SetArgPointee(const wchar_t* p) { + return MakePolymorphicAction(internal::SetArgumentPointeeAction< + N, const wchar_t*, false>(p)); +} +#endif + +// The following version is DEPRECATED. +template +PolymorphicAction< + internal::SetArgumentPointeeAction< + N, T, internal::IsAProtocolMessage::value> > +SetArgumentPointee(const T& x) { + return MakePolymorphicAction(internal::SetArgumentPointeeAction< + N, T, internal::IsAProtocolMessage::value>(x)); +} + +// Creates an action that sets a pointer referent to a given value. +template +PolymorphicAction > Assign(T1* ptr, T2 val) { + return MakePolymorphicAction(internal::AssignAction(ptr, val)); +} + +#if !GTEST_OS_WINDOWS_MOBILE + +// Creates an action that sets errno and returns the appropriate error. +template +PolymorphicAction > +SetErrnoAndReturn(int errval, T result) { + return MakePolymorphicAction( + internal::SetErrnoAndReturnAction(errval, result)); +} + +#endif // !GTEST_OS_WINDOWS_MOBILE + +// Various overloads for InvokeWithoutArgs(). + +// Creates an action that invokes 'function_impl' with no argument. +template +PolymorphicAction > +InvokeWithoutArgs(FunctionImpl function_impl) { + return MakePolymorphicAction( + internal::InvokeWithoutArgsAction(function_impl)); +} + +// Creates an action that invokes the given method on the given object +// with no argument. +template +PolymorphicAction > +InvokeWithoutArgs(Class* obj_ptr, MethodPtr method_ptr) { + return MakePolymorphicAction( + internal::InvokeMethodWithoutArgsAction( + obj_ptr, method_ptr)); +} + +// Creates an action that performs an_action and throws away its +// result. In other words, it changes the return type of an_action to +// void. an_action MUST NOT return void, or the code won't compile. +template +inline internal::IgnoreResultAction IgnoreResult(const A& an_action) { + return internal::IgnoreResultAction(an_action); +} + +// Creates a reference wrapper for the given L-value. If necessary, +// you can explicitly specify the type of the reference. For example, +// suppose 'derived' is an object of type Derived, ByRef(derived) +// would wrap a Derived&. If you want to wrap a const Base& instead, +// where Base is a base class of Derived, just write: +// +// ByRef(derived) +template +inline internal::ReferenceWrapper ByRef(T& l_value) { // NOLINT + return internal::ReferenceWrapper(l_value); +} + +} // namespace testing + +#endif // GMOCK_INCLUDE_GMOCK_GMOCK_ACTIONS_H_ +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements some commonly used cardinalities. More +// cardinalities can be defined by the user implementing the +// CardinalityInterface interface if necessary. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_CARDINALITIES_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_CARDINALITIES_H_ + +#include +#include // NOLINT + +namespace testing { + +// To implement a cardinality Foo, define: +// 1. a class FooCardinality that implements the +// CardinalityInterface interface, and +// 2. a factory function that creates a Cardinality object from a +// const FooCardinality*. +// +// The two-level delegation design follows that of Matcher, providing +// consistency for extension developers. It also eases ownership +// management as Cardinality objects can now be copied like plain values. + +// The implementation of a cardinality. +class CardinalityInterface { + public: + virtual ~CardinalityInterface() {} + + // Conservative estimate on the lower/upper bound of the number of + // calls allowed. + virtual int ConservativeLowerBound() const { return 0; } + virtual int ConservativeUpperBound() const { return INT_MAX; } + + // Returns true iff call_count calls will satisfy this cardinality. + virtual bool IsSatisfiedByCallCount(int call_count) const = 0; + + // Returns true iff call_count calls will saturate this cardinality. + virtual bool IsSaturatedByCallCount(int call_count) const = 0; + + // Describes self to an ostream. + virtual void DescribeTo(::std::ostream* os) const = 0; +}; + +// A Cardinality is a copyable and IMMUTABLE (except by assignment) +// object that specifies how many times a mock function is expected to +// be called. The implementation of Cardinality is just a linked_ptr +// to const CardinalityInterface, so copying is fairly cheap. +// Don't inherit from Cardinality! +class GTEST_API_ Cardinality { + public: + // Constructs a null cardinality. Needed for storing Cardinality + // objects in STL containers. + Cardinality() {} + + // Constructs a Cardinality from its implementation. + explicit Cardinality(const CardinalityInterface* impl) : impl_(impl) {} + + // Conservative estimate on the lower/upper bound of the number of + // calls allowed. + int ConservativeLowerBound() const { return impl_->ConservativeLowerBound(); } + int ConservativeUpperBound() const { return impl_->ConservativeUpperBound(); } + + // Returns true iff call_count calls will satisfy this cardinality. + bool IsSatisfiedByCallCount(int call_count) const { + return impl_->IsSatisfiedByCallCount(call_count); + } + + // Returns true iff call_count calls will saturate this cardinality. + bool IsSaturatedByCallCount(int call_count) const { + return impl_->IsSaturatedByCallCount(call_count); + } + + // Returns true iff call_count calls will over-saturate this + // cardinality, i.e. exceed the maximum number of allowed calls. + bool IsOverSaturatedByCallCount(int call_count) const { + return impl_->IsSaturatedByCallCount(call_count) && + !impl_->IsSatisfiedByCallCount(call_count); + } + + // Describes self to an ostream + void DescribeTo(::std::ostream* os) const { impl_->DescribeTo(os); } + + // Describes the given actual call count to an ostream. + static void DescribeActualCallCountTo(int actual_call_count, + ::std::ostream* os); + + private: + internal::linked_ptr impl_; +}; + +// Creates a cardinality that allows at least n calls. +GTEST_API_ Cardinality AtLeast(int n); + +// Creates a cardinality that allows at most n calls. +GTEST_API_ Cardinality AtMost(int n); + +// Creates a cardinality that allows any number of calls. +GTEST_API_ Cardinality AnyNumber(); + +// Creates a cardinality that allows between min and max calls. +GTEST_API_ Cardinality Between(int min, int max); + +// Creates a cardinality that allows exactly n calls. +GTEST_API_ Cardinality Exactly(int n); + +// Creates a cardinality from its implementation. +inline Cardinality MakeCardinality(const CardinalityInterface* c) { + return Cardinality(c); +} + +} // namespace testing + +#endif // GMOCK_INCLUDE_GMOCK_GMOCK_CARDINALITIES_H_ +// This file was GENERATED by a script. DO NOT EDIT BY HAND!!! + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements some commonly used variadic actions. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_ACTIONS_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_ACTIONS_H_ + + +namespace testing { +namespace internal { + +// InvokeHelper knows how to unpack an N-tuple and invoke an N-ary +// function or method with the unpacked values, where F is a function +// type that takes N arguments. +template +class InvokeHelper; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple<>&) { + return function(); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple<>&) { + return (obj_ptr->*method_ptr)(); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args), get<5>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args), get<5>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args), get<5>(args), get<6>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args), get<5>(args), + get<6>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args), get<5>(args), get<6>(args), + get<7>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args), get<5>(args), + get<6>(args), get<7>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args), get<5>(args), get<6>(args), + get<7>(args), get<8>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args), get<5>(args), + get<6>(args), get<7>(args), get<8>(args)); + } +}; + +template +class InvokeHelper > { + public: + template + static R Invoke(Function function, const ::testing::tuple& args) { + return function(get<0>(args), get<1>(args), get<2>(args), + get<3>(args), get<4>(args), get<5>(args), get<6>(args), + get<7>(args), get<8>(args), get<9>(args)); + } + + template + static R InvokeMethod(Class* obj_ptr, + MethodPtr method_ptr, + const ::testing::tuple& args) { + return (obj_ptr->*method_ptr)(get<0>(args), get<1>(args), + get<2>(args), get<3>(args), get<4>(args), get<5>(args), + get<6>(args), get<7>(args), get<8>(args), get<9>(args)); + } +}; + +// An INTERNAL macro for extracting the type of a tuple field. It's +// subject to change without notice - DO NOT USE IN USER CODE! +#define GMOCK_FIELD_(Tuple, N) \ + typename ::testing::tuple_element::type + +// SelectArgs::type is the +// type of an n-ary function whose i-th (1-based) argument type is the +// k{i}-th (0-based) field of ArgumentTuple, which must be a tuple +// type, and whose return type is Result. For example, +// SelectArgs, 0, 3>::type +// is int(bool, long). +// +// SelectArgs::Select(args) +// returns the selected fields (k1, k2, ..., k_n) of args as a tuple. +// For example, +// SelectArgs, 2, 0>::Select( +// ::testing::make_tuple(true, 'a', 2.5)) +// returns tuple (2.5, true). +// +// The numbers in list k1, k2, ..., k_n must be >= 0, where n can be +// in the range [0, 10]. Duplicates are allowed and they don't have +// to be in an ascending or descending order. + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5), + GMOCK_FIELD_(ArgumentTuple, k6), GMOCK_FIELD_(ArgumentTuple, k7), + GMOCK_FIELD_(ArgumentTuple, k8), GMOCK_FIELD_(ArgumentTuple, k9), + GMOCK_FIELD_(ArgumentTuple, k10)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args), get(args), get(args), + get(args), get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& /* args */) { + return SelectedArgs(); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5), + GMOCK_FIELD_(ArgumentTuple, k6)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5), + GMOCK_FIELD_(ArgumentTuple, k6), GMOCK_FIELD_(ArgumentTuple, k7)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args), get(args), get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5), + GMOCK_FIELD_(ArgumentTuple, k6), GMOCK_FIELD_(ArgumentTuple, k7), + GMOCK_FIELD_(ArgumentTuple, k8)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args), get(args), get(args), + get(args)); + } +}; + +template +class SelectArgs { + public: + typedef Result type(GMOCK_FIELD_(ArgumentTuple, k1), + GMOCK_FIELD_(ArgumentTuple, k2), GMOCK_FIELD_(ArgumentTuple, k3), + GMOCK_FIELD_(ArgumentTuple, k4), GMOCK_FIELD_(ArgumentTuple, k5), + GMOCK_FIELD_(ArgumentTuple, k6), GMOCK_FIELD_(ArgumentTuple, k7), + GMOCK_FIELD_(ArgumentTuple, k8), GMOCK_FIELD_(ArgumentTuple, k9)); + typedef typename Function::ArgumentTuple SelectedArgs; + static SelectedArgs Select(const ArgumentTuple& args) { + return SelectedArgs(get(args), get(args), get(args), + get(args), get(args), get(args), get(args), + get(args), get(args)); + } +}; + +#undef GMOCK_FIELD_ + +// Implements the WithArgs action. +template +class WithArgsAction { + public: + explicit WithArgsAction(const InnerAction& action) : action_(action) {} + + template + operator Action() const { return MakeAction(new Impl(action_)); } + + private: + template + class Impl : public ActionInterface { + public: + typedef typename Function::Result Result; + typedef typename Function::ArgumentTuple ArgumentTuple; + + explicit Impl(const InnerAction& action) : action_(action) {} + + virtual Result Perform(const ArgumentTuple& args) { + return action_.Perform(SelectArgs::Select(args)); + } + + private: + typedef typename SelectArgs::type InnerFunctionType; + + Action action_; + }; + + const InnerAction action_; + + GTEST_DISALLOW_ASSIGN_(WithArgsAction); +}; + +// A macro from the ACTION* family (defined later in this file) +// defines an action that can be used in a mock function. Typically, +// these actions only care about a subset of the arguments of the mock +// function. For example, if such an action only uses the second +// argument, it can be used in any mock function that takes >= 2 +// arguments where the type of the second argument is compatible. +// +// Therefore, the action implementation must be prepared to take more +// arguments than it needs. The ExcessiveArg type is used to +// represent those excessive arguments. In order to keep the compiler +// error messages tractable, we define it in the testing namespace +// instead of testing::internal. However, this is an INTERNAL TYPE +// and subject to change without notice, so a user MUST NOT USE THIS +// TYPE DIRECTLY. +struct ExcessiveArg {}; + +// A helper class needed for implementing the ACTION* macros. +template +class ActionHelper { + public: + static Result Perform(Impl* impl, const ::testing::tuple<>& args) { + return impl->template gmock_PerformImpl<>(args, ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), + get<1>(args), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), + get<1>(args), get<2>(args), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), + get<1>(args), get<2>(args), get<3>(args), ExcessiveArg(), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, + get<0>(args), get<1>(args), get<2>(args), get<3>(args), get<4>(args), + ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, + get<0>(args), get<1>(args), get<2>(args), get<3>(args), get<4>(args), + get<5>(args), ExcessiveArg(), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, + get<0>(args), get<1>(args), get<2>(args), get<3>(args), get<4>(args), + get<5>(args), get<6>(args), ExcessiveArg(), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), get<1>(args), get<2>(args), get<3>(args), + get<4>(args), get<5>(args), get<6>(args), get<7>(args), ExcessiveArg(), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), get<1>(args), get<2>(args), get<3>(args), + get<4>(args), get<5>(args), get<6>(args), get<7>(args), get<8>(args), + ExcessiveArg()); + } + + template + static Result Perform(Impl* impl, const ::testing::tuple& args) { + return impl->template gmock_PerformImpl(args, get<0>(args), get<1>(args), get<2>(args), get<3>(args), + get<4>(args), get<5>(args), get<6>(args), get<7>(args), get<8>(args), + get<9>(args)); + } +}; + +} // namespace internal + +// Various overloads for Invoke(). + +// WithArgs(an_action) creates an action that passes +// the selected arguments of the mock function to an_action and +// performs it. It serves as an adaptor between actions with +// different argument lists. C++ doesn't support default arguments for +// function templates, so we have to overload it. +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +template +inline internal::WithArgsAction +WithArgs(const InnerAction& action) { + return internal::WithArgsAction(action); +} + +// Creates an action that does actions a1, a2, ..., sequentially in +// each invocation. +template +inline internal::DoBothAction +DoAll(Action1 a1, Action2 a2) { + return internal::DoBothAction(a1, a2); +} + +template +inline internal::DoBothAction > +DoAll(Action1 a1, Action2 a2, Action3 a3) { + return DoAll(a1, DoAll(a2, a3)); +} + +template +inline internal::DoBothAction > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4) { + return DoAll(a1, DoAll(a2, a3, a4)); +} + +template +inline internal::DoBothAction > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5) { + return DoAll(a1, DoAll(a2, a3, a4, a5)); +} + +template +inline internal::DoBothAction > > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5, Action6 a6) { + return DoAll(a1, DoAll(a2, a3, a4, a5, a6)); +} + +template +inline internal::DoBothAction > > > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5, Action6 a6, + Action7 a7) { + return DoAll(a1, DoAll(a2, a3, a4, a5, a6, a7)); +} + +template +inline internal::DoBothAction > > > > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5, Action6 a6, + Action7 a7, Action8 a8) { + return DoAll(a1, DoAll(a2, a3, a4, a5, a6, a7, a8)); +} + +template +inline internal::DoBothAction > > > > > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5, Action6 a6, + Action7 a7, Action8 a8, Action9 a9) { + return DoAll(a1, DoAll(a2, a3, a4, a5, a6, a7, a8, a9)); +} + +template +inline internal::DoBothAction > > > > > > > > +DoAll(Action1 a1, Action2 a2, Action3 a3, Action4 a4, Action5 a5, Action6 a6, + Action7 a7, Action8 a8, Action9 a9, Action10 a10) { + return DoAll(a1, DoAll(a2, a3, a4, a5, a6, a7, a8, a9, a10)); +} + +} // namespace testing + +// The ACTION* family of macros can be used in a namespace scope to +// define custom actions easily. The syntax: +// +// ACTION(name) { statements; } +// +// will define an action with the given name that executes the +// statements. The value returned by the statements will be used as +// the return value of the action. Inside the statements, you can +// refer to the K-th (0-based) argument of the mock function by +// 'argK', and refer to its type by 'argK_type'. For example: +// +// ACTION(IncrementArg1) { +// arg1_type temp = arg1; +// return ++(*temp); +// } +// +// allows you to write +// +// ...WillOnce(IncrementArg1()); +// +// You can also refer to the entire argument tuple and its type by +// 'args' and 'args_type', and refer to the mock function type and its +// return type by 'function_type' and 'return_type'. +// +// Note that you don't need to specify the types of the mock function +// arguments. However rest assured that your code is still type-safe: +// you'll get a compiler error if *arg1 doesn't support the ++ +// operator, or if the type of ++(*arg1) isn't compatible with the +// mock function's return type, for example. +// +// Sometimes you'll want to parameterize the action. For that you can use +// another macro: +// +// ACTION_P(name, param_name) { statements; } +// +// For example: +// +// ACTION_P(Add, n) { return arg0 + n; } +// +// will allow you to write: +// +// ...WillOnce(Add(5)); +// +// Note that you don't need to provide the type of the parameter +// either. If you need to reference the type of a parameter named +// 'foo', you can write 'foo_type'. For example, in the body of +// ACTION_P(Add, n) above, you can write 'n_type' to refer to the type +// of 'n'. +// +// We also provide ACTION_P2, ACTION_P3, ..., up to ACTION_P10 to support +// multi-parameter actions. +// +// For the purpose of typing, you can view +// +// ACTION_Pk(Foo, p1, ..., pk) { ... } +// +// as shorthand for +// +// template +// FooActionPk Foo(p1_type p1, ..., pk_type pk) { ... } +// +// In particular, you can provide the template type arguments +// explicitly when invoking Foo(), as in Foo(5, false); +// although usually you can rely on the compiler to infer the types +// for you automatically. You can assign the result of expression +// Foo(p1, ..., pk) to a variable of type FooActionPk. This can be useful when composing actions. +// +// You can also overload actions with different numbers of parameters: +// +// ACTION_P(Plus, a) { ... } +// ACTION_P2(Plus, a, b) { ... } +// +// While it's tempting to always use the ACTION* macros when defining +// a new action, you should also consider implementing ActionInterface +// or using MakePolymorphicAction() instead, especially if you need to +// use the action a lot. While these approaches require more work, +// they give you more control on the types of the mock function +// arguments and the action parameters, which in general leads to +// better compiler error messages that pay off in the long run. They +// also allow overloading actions based on parameter types (as opposed +// to just based on the number of parameters). +// +// CAVEAT: +// +// ACTION*() can only be used in a namespace scope. The reason is +// that C++ doesn't yet allow function-local types to be used to +// instantiate templates. The up-coming C++0x standard will fix this. +// Once that's done, we'll consider supporting using ACTION*() inside +// a function. +// +// MORE INFORMATION: +// +// To learn more about using these macros, please search for 'ACTION' +// on http://code.google.com/p/googlemock/wiki/CookBook. + +// An internal macro needed for implementing ACTION*(). +#define GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_\ + const args_type& args GTEST_ATTRIBUTE_UNUSED_, \ + arg0_type arg0 GTEST_ATTRIBUTE_UNUSED_, \ + arg1_type arg1 GTEST_ATTRIBUTE_UNUSED_, \ + arg2_type arg2 GTEST_ATTRIBUTE_UNUSED_, \ + arg3_type arg3 GTEST_ATTRIBUTE_UNUSED_, \ + arg4_type arg4 GTEST_ATTRIBUTE_UNUSED_, \ + arg5_type arg5 GTEST_ATTRIBUTE_UNUSED_, \ + arg6_type arg6 GTEST_ATTRIBUTE_UNUSED_, \ + arg7_type arg7 GTEST_ATTRIBUTE_UNUSED_, \ + arg8_type arg8 GTEST_ATTRIBUTE_UNUSED_, \ + arg9_type arg9 GTEST_ATTRIBUTE_UNUSED_ + +// Sometimes you want to give an action explicit template parameters +// that cannot be inferred from its value parameters. ACTION() and +// ACTION_P*() don't support that. ACTION_TEMPLATE() remedies that +// and can be viewed as an extension to ACTION() and ACTION_P*(). +// +// The syntax: +// +// ACTION_TEMPLATE(ActionName, +// HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), +// AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } +// +// defines an action template that takes m explicit template +// parameters and n value parameters. name_i is the name of the i-th +// template parameter, and kind_i specifies whether it's a typename, +// an integral constant, or a template. p_i is the name of the i-th +// value parameter. +// +// Example: +// +// // DuplicateArg(output) converts the k-th argument of the mock +// // function to type T and copies it to *output. +// ACTION_TEMPLATE(DuplicateArg, +// HAS_2_TEMPLATE_PARAMS(int, k, typename, T), +// AND_1_VALUE_PARAMS(output)) { +// *output = T(::testing::get(args)); +// } +// ... +// int n; +// EXPECT_CALL(mock, Foo(_, _)) +// .WillOnce(DuplicateArg<1, unsigned char>(&n)); +// +// To create an instance of an action template, write: +// +// ActionName(v1, ..., v_n) +// +// where the ts are the template arguments and the vs are the value +// arguments. The value argument types are inferred by the compiler. +// If you want to explicitly specify the value argument types, you can +// provide additional template arguments: +// +// ActionName(v1, ..., v_n) +// +// where u_i is the desired type of v_i. +// +// ACTION_TEMPLATE and ACTION/ACTION_P* can be overloaded on the +// number of value parameters, but not on the number of template +// parameters. Without the restriction, the meaning of the following +// is unclear: +// +// OverloadedAction(x); +// +// Are we using a single-template-parameter action where 'bool' refers +// to the type of x, or are we using a two-template-parameter action +// where the compiler is asked to infer the type of x? +// +// Implementation notes: +// +// GMOCK_INTERNAL_*_HAS_m_TEMPLATE_PARAMS and +// GMOCK_INTERNAL_*_AND_n_VALUE_PARAMS are internal macros for +// implementing ACTION_TEMPLATE. The main trick we use is to create +// new macro invocations when expanding a macro. For example, we have +// +// #define ACTION_TEMPLATE(name, template_params, value_params) +// ... GMOCK_INTERNAL_DECL_##template_params ... +// +// which causes ACTION_TEMPLATE(..., HAS_1_TEMPLATE_PARAMS(typename, T), ...) +// to expand to +// +// ... GMOCK_INTERNAL_DECL_HAS_1_TEMPLATE_PARAMS(typename, T) ... +// +// Since GMOCK_INTERNAL_DECL_HAS_1_TEMPLATE_PARAMS is a macro, the +// preprocessor will continue to expand it to +// +// ... typename T ... +// +// This technique conforms to the C++ standard and is portable. It +// allows us to implement action templates using O(N) code, where N is +// the maximum number of template/value parameters supported. Without +// using it, we'd have to devote O(N^2) amount of code to implement all +// combinations of m and n. + +// Declares the template parameters. +#define GMOCK_INTERNAL_DECL_HAS_1_TEMPLATE_PARAMS(kind0, name0) kind0 name0 +#define GMOCK_INTERNAL_DECL_HAS_2_TEMPLATE_PARAMS(kind0, name0, kind1, \ + name1) kind0 name0, kind1 name1 +#define GMOCK_INTERNAL_DECL_HAS_3_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2) kind0 name0, kind1 name1, kind2 name2 +#define GMOCK_INTERNAL_DECL_HAS_4_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3) kind0 name0, kind1 name1, kind2 name2, \ + kind3 name3 +#define GMOCK_INTERNAL_DECL_HAS_5_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4) kind0 name0, kind1 name1, \ + kind2 name2, kind3 name3, kind4 name4 +#define GMOCK_INTERNAL_DECL_HAS_6_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5) kind0 name0, \ + kind1 name1, kind2 name2, kind3 name3, kind4 name4, kind5 name5 +#define GMOCK_INTERNAL_DECL_HAS_7_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, \ + name6) kind0 name0, kind1 name1, kind2 name2, kind3 name3, kind4 name4, \ + kind5 name5, kind6 name6 +#define GMOCK_INTERNAL_DECL_HAS_8_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, name6, \ + kind7, name7) kind0 name0, kind1 name1, kind2 name2, kind3 name3, \ + kind4 name4, kind5 name5, kind6 name6, kind7 name7 +#define GMOCK_INTERNAL_DECL_HAS_9_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, name6, \ + kind7, name7, kind8, name8) kind0 name0, kind1 name1, kind2 name2, \ + kind3 name3, kind4 name4, kind5 name5, kind6 name6, kind7 name7, \ + kind8 name8 +#define GMOCK_INTERNAL_DECL_HAS_10_TEMPLATE_PARAMS(kind0, name0, kind1, \ + name1, kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, \ + name6, kind7, name7, kind8, name8, kind9, name9) kind0 name0, \ + kind1 name1, kind2 name2, kind3 name3, kind4 name4, kind5 name5, \ + kind6 name6, kind7 name7, kind8 name8, kind9 name9 + +// Lists the template parameters. +#define GMOCK_INTERNAL_LIST_HAS_1_TEMPLATE_PARAMS(kind0, name0) name0 +#define GMOCK_INTERNAL_LIST_HAS_2_TEMPLATE_PARAMS(kind0, name0, kind1, \ + name1) name0, name1 +#define GMOCK_INTERNAL_LIST_HAS_3_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2) name0, name1, name2 +#define GMOCK_INTERNAL_LIST_HAS_4_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3) name0, name1, name2, name3 +#define GMOCK_INTERNAL_LIST_HAS_5_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4) name0, name1, name2, name3, \ + name4 +#define GMOCK_INTERNAL_LIST_HAS_6_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5) name0, name1, \ + name2, name3, name4, name5 +#define GMOCK_INTERNAL_LIST_HAS_7_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, \ + name6) name0, name1, name2, name3, name4, name5, name6 +#define GMOCK_INTERNAL_LIST_HAS_8_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, name6, \ + kind7, name7) name0, name1, name2, name3, name4, name5, name6, name7 +#define GMOCK_INTERNAL_LIST_HAS_9_TEMPLATE_PARAMS(kind0, name0, kind1, name1, \ + kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, name6, \ + kind7, name7, kind8, name8) name0, name1, name2, name3, name4, name5, \ + name6, name7, name8 +#define GMOCK_INTERNAL_LIST_HAS_10_TEMPLATE_PARAMS(kind0, name0, kind1, \ + name1, kind2, name2, kind3, name3, kind4, name4, kind5, name5, kind6, \ + name6, kind7, name7, kind8, name8, kind9, name9) name0, name1, name2, \ + name3, name4, name5, name6, name7, name8, name9 + +// Declares the types of value parameters. +#define GMOCK_INTERNAL_DECL_TYPE_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_DECL_TYPE_AND_1_VALUE_PARAMS(p0) , typename p0##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_2_VALUE_PARAMS(p0, p1) , \ + typename p0##_type, typename p1##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_3_VALUE_PARAMS(p0, p1, p2) , \ + typename p0##_type, typename p1##_type, typename p2##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_4_VALUE_PARAMS(p0, p1, p2, p3) , \ + typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4) , \ + typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type, typename p4##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5) , \ + typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type, typename p4##_type, typename p5##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6) , typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type, typename p4##_type, typename p5##_type, \ + typename p6##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7) , typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type, typename p4##_type, typename p5##_type, \ + typename p6##_type, typename p7##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8) , typename p0##_type, typename p1##_type, typename p2##_type, \ + typename p3##_type, typename p4##_type, typename p5##_type, \ + typename p6##_type, typename p7##_type, typename p8##_type +#define GMOCK_INTERNAL_DECL_TYPE_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8, p9) , typename p0##_type, typename p1##_type, \ + typename p2##_type, typename p3##_type, typename p4##_type, \ + typename p5##_type, typename p6##_type, typename p7##_type, \ + typename p8##_type, typename p9##_type + +// Initializes the value parameters. +#define GMOCK_INTERNAL_INIT_AND_0_VALUE_PARAMS()\ + () +#define GMOCK_INTERNAL_INIT_AND_1_VALUE_PARAMS(p0)\ + (p0##_type gmock_p0) : p0(gmock_p0) +#define GMOCK_INTERNAL_INIT_AND_2_VALUE_PARAMS(p0, p1)\ + (p0##_type gmock_p0, p1##_type gmock_p1) : p0(gmock_p0), p1(gmock_p1) +#define GMOCK_INTERNAL_INIT_AND_3_VALUE_PARAMS(p0, p1, p2)\ + (p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2) +#define GMOCK_INTERNAL_INIT_AND_4_VALUE_PARAMS(p0, p1, p2, p3)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3) +#define GMOCK_INTERNAL_INIT_AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4) : p0(gmock_p0), p1(gmock_p1), \ + p2(gmock_p2), p3(gmock_p3), p4(gmock_p4) +#define GMOCK_INTERNAL_INIT_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5) +#define GMOCK_INTERNAL_INIT_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6) +#define GMOCK_INTERNAL_INIT_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7) : p0(gmock_p0), p1(gmock_p1), \ + p2(gmock_p2), p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), \ + p7(gmock_p7) +#define GMOCK_INTERNAL_INIT_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7, \ + p8##_type gmock_p8) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), p7(gmock_p7), \ + p8(gmock_p8) +#define GMOCK_INTERNAL_INIT_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8, p9)\ + (p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7, p8##_type gmock_p8, \ + p9##_type gmock_p9) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), p7(gmock_p7), \ + p8(gmock_p8), p9(gmock_p9) + +// Declares the fields for storing the value parameters. +#define GMOCK_INTERNAL_DEFN_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_DEFN_AND_1_VALUE_PARAMS(p0) p0##_type p0; +#define GMOCK_INTERNAL_DEFN_AND_2_VALUE_PARAMS(p0, p1) p0##_type p0; \ + p1##_type p1; +#define GMOCK_INTERNAL_DEFN_AND_3_VALUE_PARAMS(p0, p1, p2) p0##_type p0; \ + p1##_type p1; p2##_type p2; +#define GMOCK_INTERNAL_DEFN_AND_4_VALUE_PARAMS(p0, p1, p2, p3) p0##_type p0; \ + p1##_type p1; p2##_type p2; p3##_type p3; +#define GMOCK_INTERNAL_DEFN_AND_5_VALUE_PARAMS(p0, p1, p2, p3, \ + p4) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; p4##_type p4; +#define GMOCK_INTERNAL_DEFN_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, \ + p5) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; p4##_type p4; \ + p5##_type p5; +#define GMOCK_INTERNAL_DEFN_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; p4##_type p4; \ + p5##_type p5; p6##_type p6; +#define GMOCK_INTERNAL_DEFN_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; p4##_type p4; \ + p5##_type p5; p6##_type p6; p7##_type p7; +#define GMOCK_INTERNAL_DEFN_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; \ + p4##_type p4; p5##_type p5; p6##_type p6; p7##_type p7; p8##_type p8; +#define GMOCK_INTERNAL_DEFN_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8, p9) p0##_type p0; p1##_type p1; p2##_type p2; p3##_type p3; \ + p4##_type p4; p5##_type p5; p6##_type p6; p7##_type p7; p8##_type p8; \ + p9##_type p9; + +// Lists the value parameters. +#define GMOCK_INTERNAL_LIST_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_LIST_AND_1_VALUE_PARAMS(p0) p0 +#define GMOCK_INTERNAL_LIST_AND_2_VALUE_PARAMS(p0, p1) p0, p1 +#define GMOCK_INTERNAL_LIST_AND_3_VALUE_PARAMS(p0, p1, p2) p0, p1, p2 +#define GMOCK_INTERNAL_LIST_AND_4_VALUE_PARAMS(p0, p1, p2, p3) p0, p1, p2, p3 +#define GMOCK_INTERNAL_LIST_AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4) p0, p1, \ + p2, p3, p4 +#define GMOCK_INTERNAL_LIST_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5) p0, \ + p1, p2, p3, p4, p5 +#define GMOCK_INTERNAL_LIST_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6) p0, p1, p2, p3, p4, p5, p6 +#define GMOCK_INTERNAL_LIST_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7) p0, p1, p2, p3, p4, p5, p6, p7 +#define GMOCK_INTERNAL_LIST_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8) p0, p1, p2, p3, p4, p5, p6, p7, p8 +#define GMOCK_INTERNAL_LIST_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8, p9) p0, p1, p2, p3, p4, p5, p6, p7, p8, p9 + +// Lists the value parameter types. +#define GMOCK_INTERNAL_LIST_TYPE_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_LIST_TYPE_AND_1_VALUE_PARAMS(p0) , p0##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_2_VALUE_PARAMS(p0, p1) , p0##_type, \ + p1##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_3_VALUE_PARAMS(p0, p1, p2) , p0##_type, \ + p1##_type, p2##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_4_VALUE_PARAMS(p0, p1, p2, p3) , \ + p0##_type, p1##_type, p2##_type, p3##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4) , \ + p0##_type, p1##_type, p2##_type, p3##_type, p4##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5) , \ + p0##_type, p1##_type, p2##_type, p3##_type, p4##_type, p5##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6) , p0##_type, p1##_type, p2##_type, p3##_type, p4##_type, p5##_type, \ + p6##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7) , p0##_type, p1##_type, p2##_type, p3##_type, p4##_type, \ + p5##_type, p6##_type, p7##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8) , p0##_type, p1##_type, p2##_type, p3##_type, p4##_type, \ + p5##_type, p6##_type, p7##_type, p8##_type +#define GMOCK_INTERNAL_LIST_TYPE_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8, p9) , p0##_type, p1##_type, p2##_type, p3##_type, p4##_type, \ + p5##_type, p6##_type, p7##_type, p8##_type, p9##_type + +// Declares the value parameters. +#define GMOCK_INTERNAL_DECL_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_DECL_AND_1_VALUE_PARAMS(p0) p0##_type p0 +#define GMOCK_INTERNAL_DECL_AND_2_VALUE_PARAMS(p0, p1) p0##_type p0, \ + p1##_type p1 +#define GMOCK_INTERNAL_DECL_AND_3_VALUE_PARAMS(p0, p1, p2) p0##_type p0, \ + p1##_type p1, p2##_type p2 +#define GMOCK_INTERNAL_DECL_AND_4_VALUE_PARAMS(p0, p1, p2, p3) p0##_type p0, \ + p1##_type p1, p2##_type p2, p3##_type p3 +#define GMOCK_INTERNAL_DECL_AND_5_VALUE_PARAMS(p0, p1, p2, p3, \ + p4) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, p4##_type p4 +#define GMOCK_INTERNAL_DECL_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, \ + p5) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, p4##_type p4, \ + p5##_type p5 +#define GMOCK_INTERNAL_DECL_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, \ + p6) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, p4##_type p4, \ + p5##_type p5, p6##_type p6 +#define GMOCK_INTERNAL_DECL_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, p4##_type p4, \ + p5##_type p5, p6##_type p6, p7##_type p7 +#define GMOCK_INTERNAL_DECL_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, \ + p4##_type p4, p5##_type p5, p6##_type p6, p7##_type p7, p8##_type p8 +#define GMOCK_INTERNAL_DECL_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8, p9) p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, \ + p4##_type p4, p5##_type p5, p6##_type p6, p7##_type p7, p8##_type p8, \ + p9##_type p9 + +// The suffix of the class template implementing the action template. +#define GMOCK_INTERNAL_COUNT_AND_0_VALUE_PARAMS() +#define GMOCK_INTERNAL_COUNT_AND_1_VALUE_PARAMS(p0) P +#define GMOCK_INTERNAL_COUNT_AND_2_VALUE_PARAMS(p0, p1) P2 +#define GMOCK_INTERNAL_COUNT_AND_3_VALUE_PARAMS(p0, p1, p2) P3 +#define GMOCK_INTERNAL_COUNT_AND_4_VALUE_PARAMS(p0, p1, p2, p3) P4 +#define GMOCK_INTERNAL_COUNT_AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4) P5 +#define GMOCK_INTERNAL_COUNT_AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5) P6 +#define GMOCK_INTERNAL_COUNT_AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6) P7 +#define GMOCK_INTERNAL_COUNT_AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7) P8 +#define GMOCK_INTERNAL_COUNT_AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8) P9 +#define GMOCK_INTERNAL_COUNT_AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, \ + p7, p8, p9) P10 + +// The name of the class template implementing the action template. +#define GMOCK_ACTION_CLASS_(name, value_params)\ + GTEST_CONCAT_TOKEN_(name##Action, GMOCK_INTERNAL_COUNT_##value_params) + +#define ACTION_TEMPLATE(name, template_params, value_params)\ + template \ + class GMOCK_ACTION_CLASS_(name, value_params) {\ + public:\ + explicit GMOCK_ACTION_CLASS_(name, value_params)\ + GMOCK_INTERNAL_INIT_##value_params {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + explicit gmock_Impl GMOCK_INTERNAL_INIT_##value_params {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + GMOCK_INTERNAL_DEFN_##value_params\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(\ + new gmock_Impl(GMOCK_INTERNAL_LIST_##value_params));\ + }\ + GMOCK_INTERNAL_DEFN_##value_params\ + private:\ + GTEST_DISALLOW_ASSIGN_(GMOCK_ACTION_CLASS_(name, value_params));\ + };\ + template \ + inline GMOCK_ACTION_CLASS_(name, value_params)<\ + GMOCK_INTERNAL_LIST_##template_params\ + GMOCK_INTERNAL_LIST_TYPE_##value_params> name(\ + GMOCK_INTERNAL_DECL_##value_params) {\ + return GMOCK_ACTION_CLASS_(name, value_params)<\ + GMOCK_INTERNAL_LIST_##template_params\ + GMOCK_INTERNAL_LIST_TYPE_##value_params>(\ + GMOCK_INTERNAL_LIST_##value_params);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + GMOCK_ACTION_CLASS_(name, value_params)<\ + GMOCK_INTERNAL_LIST_##template_params\ + GMOCK_INTERNAL_LIST_TYPE_##value_params>::gmock_Impl::\ + gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION(name)\ + class name##Action {\ + public:\ + name##Action() {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl() {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl());\ + }\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##Action);\ + };\ + inline name##Action name() {\ + return name##Action();\ + }\ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##Action::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P(name, p0)\ + template \ + class name##ActionP {\ + public:\ + explicit name##ActionP(p0##_type gmock_p0) : p0(gmock_p0) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + explicit gmock_Impl(p0##_type gmock_p0) : p0(gmock_p0) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0));\ + }\ + p0##_type p0;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP);\ + };\ + template \ + inline name##ActionP name(p0##_type p0) {\ + return name##ActionP(p0);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P2(name, p0, p1)\ + template \ + class name##ActionP2 {\ + public:\ + name##ActionP2(p0##_type gmock_p0, p1##_type gmock_p1) : p0(gmock_p0), \ + p1(gmock_p1) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1) : p0(gmock_p0), \ + p1(gmock_p1) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP2);\ + };\ + template \ + inline name##ActionP2 name(p0##_type p0, \ + p1##_type p1) {\ + return name##ActionP2(p0, p1);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP2::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P3(name, p0, p1, p2)\ + template \ + class name##ActionP3 {\ + public:\ + name##ActionP3(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP3);\ + };\ + template \ + inline name##ActionP3 name(p0##_type p0, \ + p1##_type p1, p2##_type p2) {\ + return name##ActionP3(p0, p1, p2);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP3::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P4(name, p0, p1, p2, p3)\ + template \ + class name##ActionP4 {\ + public:\ + name##ActionP4(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3) : p0(gmock_p0), p1(gmock_p1), \ + p2(gmock_p2), p3(gmock_p3) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP4);\ + };\ + template \ + inline name##ActionP4 name(p0##_type p0, p1##_type p1, p2##_type p2, \ + p3##_type p3) {\ + return name##ActionP4(p0, p1, \ + p2, p3);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP4::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P5(name, p0, p1, p2, p3, p4)\ + template \ + class name##ActionP5 {\ + public:\ + name##ActionP5(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, \ + p4##_type gmock_p4) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4) : p0(gmock_p0), \ + p1(gmock_p1), p2(gmock_p2), p3(gmock_p3), p4(gmock_p4) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP5);\ + };\ + template \ + inline name##ActionP5 name(p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, \ + p4##_type p4) {\ + return name##ActionP5(p0, p1, p2, p3, p4);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP5::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P6(name, p0, p1, p2, p3, p4, p5)\ + template \ + class name##ActionP6 {\ + public:\ + name##ActionP6(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4, p5));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP6);\ + };\ + template \ + inline name##ActionP6 name(p0##_type p0, p1##_type p1, p2##_type p2, \ + p3##_type p3, p4##_type p4, p5##_type p5) {\ + return name##ActionP6(p0, p1, p2, p3, p4, p5);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP6::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P7(name, p0, p1, p2, p3, p4, p5, p6)\ + template \ + class name##ActionP7 {\ + public:\ + name##ActionP7(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5, p6##_type gmock_p6) : p0(gmock_p0), p1(gmock_p1), \ + p2(gmock_p2), p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), \ + p6(gmock_p6) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4, p5, \ + p6));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP7);\ + };\ + template \ + inline name##ActionP7 name(p0##_type p0, p1##_type p1, \ + p2##_type p2, p3##_type p3, p4##_type p4, p5##_type p5, \ + p6##_type p6) {\ + return name##ActionP7(p0, p1, p2, p3, p4, p5, p6);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP7::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P8(name, p0, p1, p2, p3, p4, p5, p6, p7)\ + template \ + class name##ActionP8 {\ + public:\ + name##ActionP8(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5, p6##_type gmock_p6, \ + p7##_type gmock_p7) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), \ + p7(gmock_p7) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7) : p0(gmock_p0), \ + p1(gmock_p1), p2(gmock_p2), p3(gmock_p3), p4(gmock_p4), \ + p5(gmock_p5), p6(gmock_p6), p7(gmock_p7) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4, p5, \ + p6, p7));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP8);\ + };\ + template \ + inline name##ActionP8 name(p0##_type p0, \ + p1##_type p1, p2##_type p2, p3##_type p3, p4##_type p4, p5##_type p5, \ + p6##_type p6, p7##_type p7) {\ + return name##ActionP8(p0, p1, p2, p3, p4, p5, \ + p6, p7);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP8::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P9(name, p0, p1, p2, p3, p4, p5, p6, p7, p8)\ + template \ + class name##ActionP9 {\ + public:\ + name##ActionP9(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5, p6##_type gmock_p6, p7##_type gmock_p7, \ + p8##_type gmock_p8) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), p7(gmock_p7), \ + p8(gmock_p8) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7, \ + p8##_type gmock_p8) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), \ + p7(gmock_p7), p8(gmock_p8) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + p8##_type p8;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + p8##_type p8;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP9);\ + };\ + template \ + inline name##ActionP9 name(p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, \ + p4##_type p4, p5##_type p5, p6##_type p6, p7##_type p7, \ + p8##_type p8) {\ + return name##ActionP9(p0, p1, p2, \ + p3, p4, p5, p6, p7, p8);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP9::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +#define ACTION_P10(name, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9)\ + template \ + class name##ActionP10 {\ + public:\ + name##ActionP10(p0##_type gmock_p0, p1##_type gmock_p1, \ + p2##_type gmock_p2, p3##_type gmock_p3, p4##_type gmock_p4, \ + p5##_type gmock_p5, p6##_type gmock_p6, p7##_type gmock_p7, \ + p8##_type gmock_p8, p9##_type gmock_p9) : p0(gmock_p0), p1(gmock_p1), \ + p2(gmock_p2), p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), \ + p7(gmock_p7), p8(gmock_p8), p9(gmock_p9) {}\ + template \ + class gmock_Impl : public ::testing::ActionInterface {\ + public:\ + typedef F function_type;\ + typedef typename ::testing::internal::Function::Result return_type;\ + typedef typename ::testing::internal::Function::ArgumentTuple\ + args_type;\ + gmock_Impl(p0##_type gmock_p0, p1##_type gmock_p1, p2##_type gmock_p2, \ + p3##_type gmock_p3, p4##_type gmock_p4, p5##_type gmock_p5, \ + p6##_type gmock_p6, p7##_type gmock_p7, p8##_type gmock_p8, \ + p9##_type gmock_p9) : p0(gmock_p0), p1(gmock_p1), p2(gmock_p2), \ + p3(gmock_p3), p4(gmock_p4), p5(gmock_p5), p6(gmock_p6), \ + p7(gmock_p7), p8(gmock_p8), p9(gmock_p9) {}\ + virtual return_type Perform(const args_type& args) {\ + return ::testing::internal::ActionHelper::\ + Perform(this, args);\ + }\ + template \ + return_type gmock_PerformImpl(const args_type& args, arg0_type arg0, \ + arg1_type arg1, arg2_type arg2, arg3_type arg3, arg4_type arg4, \ + arg5_type arg5, arg6_type arg6, arg7_type arg7, arg8_type arg8, \ + arg9_type arg9) const;\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + p8##_type p8;\ + p9##_type p9;\ + private:\ + GTEST_DISALLOW_ASSIGN_(gmock_Impl);\ + };\ + template operator ::testing::Action() const {\ + return ::testing::Action(new gmock_Impl(p0, p1, p2, p3, p4, p5, \ + p6, p7, p8, p9));\ + }\ + p0##_type p0;\ + p1##_type p1;\ + p2##_type p2;\ + p3##_type p3;\ + p4##_type p4;\ + p5##_type p5;\ + p6##_type p6;\ + p7##_type p7;\ + p8##_type p8;\ + p9##_type p9;\ + private:\ + GTEST_DISALLOW_ASSIGN_(name##ActionP10);\ + };\ + template \ + inline name##ActionP10 name(p0##_type p0, p1##_type p1, p2##_type p2, p3##_type p3, \ + p4##_type p4, p5##_type p5, p6##_type p6, p7##_type p7, p8##_type p8, \ + p9##_type p9) {\ + return name##ActionP10(p0, \ + p1, p2, p3, p4, p5, p6, p7, p8, p9);\ + }\ + template \ + template \ + template \ + typename ::testing::internal::Function::Result\ + name##ActionP10::gmock_Impl::gmock_PerformImpl(\ + GMOCK_ACTION_ARG_TYPES_AND_NAMES_UNUSED_) const + +namespace testing { + + +// The ACTION*() macros trigger warning C4100 (unreferenced formal +// parameter) in MSVC with -W4. Unfortunately they cannot be fixed in +// the macro definition, as the warnings are generated when the macro +// is expanded and macro expansion cannot contain #pragma. Therefore +// we suppress them here. +#ifdef _MSC_VER +# pragma warning(push) +# pragma warning(disable:4100) +#endif + +// Various overloads for InvokeArgument(). +// +// The InvokeArgument(a1, a2, ..., a_k) action invokes the N-th +// (0-based) argument, which must be a k-ary callable, of the mock +// function, with arguments a1, a2, ..., a_k. +// +// Notes: +// +// 1. The arguments are passed by value by default. If you need to +// pass an argument by reference, wrap it inside ByRef(). For +// example, +// +// InvokeArgument<1>(5, string("Hello"), ByRef(foo)) +// +// passes 5 and string("Hello") by value, and passes foo by +// reference. +// +// 2. If the callable takes an argument by reference but ByRef() is +// not used, it will receive the reference to a copy of the value, +// instead of the original value. For example, when the 0-th +// argument of the mock function takes a const string&, the action +// +// InvokeArgument<0>(string("Hello")) +// +// makes a copy of the temporary string("Hello") object and passes a +// reference of the copy, instead of the original temporary object, +// to the callable. This makes it easy for a user to define an +// InvokeArgument action from temporary values and have it performed +// later. + +namespace internal { +namespace invoke_argument { + +// Appears in InvokeArgumentAdl's argument list to help avoid +// accidental calls to user functions of the same name. +struct AdlTag {}; + +// InvokeArgumentAdl - a helper for InvokeArgument. +// The basic overloads are provided here for generic functors. +// Overloads for other custom-callables are provided in the +// internal/custom/callback-actions.h header. + +template +R InvokeArgumentAdl(AdlTag, F f) { + return f(); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1) { + return f(a1); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2) { + return f(a1, a2); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3) { + return f(a1, a2, a3); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4) { + return f(a1, a2, a3, a4); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5) { + return f(a1, a2, a3, a4, a5); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6) { + return f(a1, a2, a3, a4, a5, a6); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6, + A7 a7) { + return f(a1, a2, a3, a4, a5, a6, a7); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6, + A7 a7, A8 a8) { + return f(a1, a2, a3, a4, a5, a6, a7, a8); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6, + A7 a7, A8 a8, A9 a9) { + return f(a1, a2, a3, a4, a5, a6, a7, a8, a9); +} +template +R InvokeArgumentAdl(AdlTag, F f, A1 a1, A2 a2, A3 a3, A4 a4, A5 a5, A6 a6, + A7 a7, A8 a8, A9 a9, A10 a10) { + return f(a1, a2, a3, a4, a5, a6, a7, a8, a9, a10); +} +} // namespace invoke_argument +} // namespace internal + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_0_VALUE_PARAMS()) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args)); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_1_VALUE_PARAMS(p0)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_2_VALUE_PARAMS(p0, p1)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_3_VALUE_PARAMS(p0, p1, p2)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_4_VALUE_PARAMS(p0, p1, p2, p3)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4, p5); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4, p5, p6); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4, p5, p6, p7); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7, p8)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4, p5, p6, p7, p8); +} + +ACTION_TEMPLATE(InvokeArgument, + HAS_1_TEMPLATE_PARAMS(int, k), + AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7, p8, p9)) { + using internal::invoke_argument::InvokeArgumentAdl; + return InvokeArgumentAdl( + internal::invoke_argument::AdlTag(), + ::testing::get(args), p0, p1, p2, p3, p4, p5, p6, p7, p8, p9); +} + +// Various overloads for ReturnNew(). +// +// The ReturnNew(a1, a2, ..., a_k) action returns a pointer to a new +// instance of type T, constructed on the heap with constructor arguments +// a1, a2, ..., and a_k. The caller assumes ownership of the returned value. +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_0_VALUE_PARAMS()) { + return new T(); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_1_VALUE_PARAMS(p0)) { + return new T(p0); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_2_VALUE_PARAMS(p0, p1)) { + return new T(p0, p1); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_3_VALUE_PARAMS(p0, p1, p2)) { + return new T(p0, p1, p2); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_4_VALUE_PARAMS(p0, p1, p2, p3)) { + return new T(p0, p1, p2, p3); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_5_VALUE_PARAMS(p0, p1, p2, p3, p4)) { + return new T(p0, p1, p2, p3, p4); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_6_VALUE_PARAMS(p0, p1, p2, p3, p4, p5)) { + return new T(p0, p1, p2, p3, p4, p5); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_7_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6)) { + return new T(p0, p1, p2, p3, p4, p5, p6); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_8_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7)) { + return new T(p0, p1, p2, p3, p4, p5, p6, p7); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_9_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7, p8)) { + return new T(p0, p1, p2, p3, p4, p5, p6, p7, p8); +} + +ACTION_TEMPLATE(ReturnNew, + HAS_1_TEMPLATE_PARAMS(typename, T), + AND_10_VALUE_PARAMS(p0, p1, p2, p3, p4, p5, p6, p7, p8, p9)) { + return new T(p0, p1, p2, p3, p4, p5, p6, p7, p8, p9); +} + +#ifdef _MSC_VER +# pragma warning(pop) +#endif + +} // namespace testing + +// Include any custom actions added by the local installation. +// We must include this header at the end to make sure it can use the +// declarations from this file. +// This file was GENERATED by command: +// pump.py gmock-generated-actions.h.pump +// DO NOT EDIT BY HAND!!! + +#ifndef GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_GENERATED_ACTIONS_H_ +#define GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_GENERATED_ACTIONS_H_ + +#endif // GMOCK_INCLUDE_GMOCK_INTERNAL_CUSTOM_GMOCK_GENERATED_ACTIONS_H_ + +#endif // GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_ACTIONS_H_ +// This file was GENERATED by command: +// pump.py gmock-generated-function-mockers.h.pump +// DO NOT EDIT BY HAND!!! + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements function mockers of various arities. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_FUNCTION_MOCKERS_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_FUNCTION_MOCKERS_H_ + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements the ON_CALL() and EXPECT_CALL() macros. +// +// A user can use the ON_CALL() macro to specify the default action of +// a mock method. The syntax is: +// +// ON_CALL(mock_object, Method(argument-matchers)) +// .With(multi-argument-matcher) +// .WillByDefault(action); +// +// where the .With() clause is optional. +// +// A user can use the EXPECT_CALL() macro to specify an expectation on +// a mock method. The syntax is: +// +// EXPECT_CALL(mock_object, Method(argument-matchers)) +// .With(multi-argument-matchers) +// .Times(cardinality) +// .InSequence(sequences) +// .After(expectations) +// .WillOnce(action) +// .WillRepeatedly(action) +// .RetiresOnSaturation(); +// +// where all clauses are optional, and .InSequence()/.After()/ +// .WillOnce() can appear any number of times. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_SPEC_BUILDERS_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_SPEC_BUILDERS_H_ + +#include +#include +#include +#include +#include + +#if GTEST_HAS_EXCEPTIONS +# include // NOLINT +#endif + +// Copyright 2007, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// +// Author: wan@google.com (Zhanyong Wan) + +// Google Mock - a framework for writing C++ mock classes. +// +// This file implements some commonly used argument matchers. More +// matchers can be defined by the user implementing the +// MatcherInterface interface if necessary. + +#ifndef GMOCK_INCLUDE_GMOCK_GMOCK_MATCHERS_H_ +#define GMOCK_INCLUDE_GMOCK_GMOCK_MATCHERS_H_ + +#include +#include +#include +#include +#include // NOLINT +#include +#include +#include +#include + + +#if GTEST_HAS_STD_INITIALIZER_LIST_ +# include // NOLINT -- must be after gtest.h +#endif + +namespace testing { + +// To implement a matcher Foo for type T, define: +// 1. a class FooMatcherImpl that implements the +// MatcherInterface interface, and +// 2. a factory function that creates a Matcher object from a +// FooMatcherImpl*. +// +// The two-level delegation design makes it possible to allow a user +// to write "v" instead of "Eq(v)" where a Matcher is expected, which +// is impossible if we pass matchers by pointers. It also eases +// ownership management as Matcher objects can now be copied like +// plain values. + +// MatchResultListener is an abstract class. Its << operator can be +// used by a matcher to explain why a value matches or doesn't match. +// +// TODO(wan@google.com): add method +// bool InterestedInWhy(bool result) const; +// to indicate whether the listener is interested in why the match +// result is 'result'. +class MatchResultListener { + public: + // Creates a listener object with the given underlying ostream. The + // listener does not own the ostream, and does not dereference it + // in the constructor or destructor. + explicit MatchResultListener(::std::ostream* os) : stream_(os) {} + virtual ~MatchResultListener() = 0; // Makes this class abstract. + + // Streams x to the underlying ostream; does nothing if the ostream + // is NULL. + template + MatchResultListener& operator<<(const T& x) { + if (stream_ != NULL) + *stream_ << x; + return *this; + } + + // Returns the underlying ostream. + ::std::ostream* stream() { return stream_; } + + // Returns true iff the listener is interested in an explanation of + // the match result. A matcher's MatchAndExplain() method can use + // this information to avoid generating the explanation when no one + // intends to hear it. + bool IsInterested() const { return stream_ != NULL; } + + private: + ::std::ostream* const stream_; + + GTEST_DISALLOW_COPY_AND_ASSIGN_(MatchResultListener); +}; + +inline MatchResultListener::~MatchResultListener() { +} + +// An instance of a subclass of this knows how to describe itself as a +// matcher. +class MatcherDescriberInterface { + public: + virtual ~MatcherDescriberInterface() {} + + // Describes this matcher to an ostream. The function should print + // a verb phrase that describes the property a value matching this + // matcher should have. The subject of the verb phrase is the value + // being matched. For example, the DescribeTo() method of the Gt(7) + // matcher prints "is greater than 7". + virtual void DescribeTo(::std::ostream* os) const = 0; + + // Describes the negation of this matcher to an ostream. For + // example, if the description of this matcher is "is greater than + // 7", the negated description could be "is not greater than 7". + // You are not required to override this when implementing + // MatcherInterface, but it is highly advised so that your matcher + // can produce good error messages. + virtual void DescribeNegationTo(::std::ostream* os) const { + *os << "not ("; + DescribeTo(os); + *os << ")"; + } +}; + +// The implementation of a matcher. +template +class MatcherInterface : public MatcherDescriberInterface { + public: + // Returns true iff the matcher matches x; also explains the match + // result to 'listener' if necessary (see the next paragraph), in + // the form of a non-restrictive relative clause ("which ...", + // "whose ...", etc) that describes x. For example, the + // MatchAndExplain() method of the Pointee(...) matcher should + // generate an explanation like "which points to ...". + // + // Implementations of MatchAndExplain() should add an explanation of + // the match result *if and only if* they can provide additional + // information that's not already present (or not obvious) in the + // print-out of x and the matcher's description. Whether the match + // succeeds is not a factor in deciding whether an explanation is + // needed, as sometimes the caller needs to print a failure message + // when the match succeeds (e.g. when the matcher is used inside + // Not()). + // + // For example, a "has at least 10 elements" matcher should explain + // what the actual element count is, regardless of the match result, + // as it is useful information to the reader; on the other hand, an + // "is empty" matcher probably only needs to explain what the actual + // size is when the match fails, as it's redundant to say that the + // size is 0 when the value is already known to be empty. + // + // You should override this method when defining a new matcher. + // + // It's the responsibility of the caller (Google Mock) to guarantee + // that 'listener' is not NULL. This helps to simplify a matcher's + // implementation when it doesn't care about the performance, as it + // can talk to 'listener' without checking its validity first. + // However, in order to implement dummy listeners efficiently, + // listener->stream() may be NULL. + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; + + // Inherits these methods from MatcherDescriberInterface: + // virtual void DescribeTo(::std::ostream* os) const = 0; + // virtual void DescribeNegationTo(::std::ostream* os) const; +}; + +// A match result listener that stores the explanation in a string. +class StringMatchResultListener : public MatchResultListener { + public: + StringMatchResultListener() : MatchResultListener(&ss_) {} + + // Returns the explanation accumulated so far. + internal::string str() const { return ss_.str(); } + + // Clears the explanation accumulated so far. + void Clear() { ss_.str(""); } + + private: + ::std::stringstream ss_; + + GTEST_DISALLOW_COPY_AND_ASSIGN_(StringMatchResultListener); +}; + +namespace internal { + +struct AnyEq { + template + bool operator()(const A& a, const B& b) const { return a == b; } +}; +struct AnyNe { + template + bool operator()(const A& a, const B& b) const { return a != b; } +}; +struct AnyLt { + template + bool operator()(const A& a, const B& b) const { return a < b; } +}; +struct AnyGt { + template + bool operator()(const A& a, const B& b) const { return a > b; } +}; +struct AnyLe { + template + bool operator()(const A& a, const B& b) const { return a <= b; } +}; +struct AnyGe { + template + bool operator()(const A& a, const B& b) const { return a >= b; } +}; + +// A match result listener that ignores the explanation. +class DummyMatchResultListener : public MatchResultListener { + public: + DummyMatchResultListener() : MatchResultListener(NULL) {} + + private: + GTEST_DISALLOW_COPY_AND_ASSIGN_(DummyMatchResultListener); +}; + +// A match result listener that forwards the explanation to a given +// ostream. The difference between this and MatchResultListener is +// that the former is concrete. +class StreamMatchResultListener : public MatchResultListener { + public: + explicit StreamMatchResultListener(::std::ostream* os) + : MatchResultListener(os) {} + + private: + GTEST_DISALLOW_COPY_AND_ASSIGN_(StreamMatchResultListener); +}; + +// An internal class for implementing Matcher, which will derive +// from it. We put functionalities common to all Matcher +// specializations here to avoid code duplication. +template +class MatcherBase { + public: + // Returns true iff the matcher matches x; also explains the match + // result to 'listener'. + bool MatchAndExplain(T x, MatchResultListener* listener) const { + return impl_->MatchAndExplain(x, listener); + } + + // Returns true iff this matcher matches x. + bool Matches(T x) const { + DummyMatchResultListener dummy; + return MatchAndExplain(x, &dummy); + } + + // Describes this matcher to an ostream. + void DescribeTo(::std::ostream* os) const { impl_->DescribeTo(os); } + + // Describes the negation of this matcher to an ostream. + void DescribeNegationTo(::std::ostream* os) const { + impl_->DescribeNegationTo(os); + } + + // Explains why x matches, or doesn't match, the matcher. + void ExplainMatchResultTo(T x, ::std::ostream* os) const { + StreamMatchResultListener listener(os); + MatchAndExplain(x, &listener); + } + + // Returns the describer for this matcher object; retains ownership + // of the describer, which is only guaranteed to be alive when + // this matcher object is alive. + const MatcherDescriberInterface* GetDescriber() const { + return impl_.get(); + } + + protected: + MatcherBase() {} + + // Constructs a matcher from its implementation. + explicit MatcherBase(const MatcherInterface* impl) + : impl_(impl) {} + + virtual ~MatcherBase() {} + + private: + // shared_ptr (util/gtl/shared_ptr.h) and linked_ptr have similar + // interfaces. The former dynamically allocates a chunk of memory + // to hold the reference count, while the latter tracks all + // references using a circular linked list without allocating + // memory. It has been observed that linked_ptr performs better in + // typical scenarios. However, shared_ptr can out-perform + // linked_ptr when there are many more uses of the copy constructor + // than the default constructor. + // + // If performance becomes a problem, we should see if using + // shared_ptr helps. + ::testing::internal::linked_ptr > impl_; +}; + +} // namespace internal + +// A Matcher is a copyable and IMMUTABLE (except by assignment) +// object that can check whether a value of type T matches. The +// implementation of Matcher is just a linked_ptr to const +// MatcherInterface, so copying is fairly cheap. Don't inherit +// from Matcher! +template +class Matcher : public internal::MatcherBase { + public: + // Constructs a null matcher. Needed for storing Matcher objects in STL + // containers. A default-constructed matcher is not yet initialized. You + // cannot use it until a valid value has been assigned to it. + explicit Matcher() {} // NOLINT + + // Constructs a matcher from its implementation. + explicit Matcher(const MatcherInterface* impl) + : internal::MatcherBase(impl) {} + + // Implicit constructor here allows people to write + // EXPECT_CALL(foo, Bar(5)) instead of EXPECT_CALL(foo, Bar(Eq(5))) sometimes + Matcher(T value); // NOLINT +}; + +// The following two specializations allow the user to write str +// instead of Eq(str) and "foo" instead of Eq("foo") when a string +// matcher is expected. +template <> +class GTEST_API_ Matcher + : public internal::MatcherBase { + public: + Matcher() {} + + explicit Matcher(const MatcherInterface* impl) + : internal::MatcherBase(impl) {} + + // Allows the user to write str instead of Eq(str) sometimes, where + // str is a string object. + Matcher(const internal::string& s); // NOLINT + + // Allows the user to write "foo" instead of Eq("foo") sometimes. + Matcher(const char* s); // NOLINT +}; + +template <> +class GTEST_API_ Matcher + : public internal::MatcherBase { + public: + Matcher() {} + + explicit Matcher(const MatcherInterface* impl) + : internal::MatcherBase(impl) {} + + // Allows the user to write str instead of Eq(str) sometimes, where + // str is a string object. + Matcher(const internal::string& s); // NOLINT + + // Allows the user to write "foo" instead of Eq("foo") sometimes. + Matcher(const char* s); // NOLINT +}; + +#if GTEST_HAS_STRING_PIECE_ +// The following two specializations allow the user to write str +// instead of Eq(str) and "foo" instead of Eq("foo") when a StringPiece +// matcher is expected. +template <> +class GTEST_API_ Matcher + : public internal::MatcherBase { + public: + Matcher() {} + + explicit Matcher(const MatcherInterface* impl) + : internal::MatcherBase(impl) {} + + // Allows the user to write str instead of Eq(str) sometimes, where + // str is a string object. + Matcher(const internal::string& s); // NOLINT + + // Allows the user to write "foo" instead of Eq("foo") sometimes. + Matcher(const char* s); // NOLINT + + // Allows the user to pass StringPieces directly. + Matcher(StringPiece s); // NOLINT +}; + +template <> +class GTEST_API_ Matcher + : public internal::MatcherBase { + public: + Matcher() {} + + explicit Matcher(const MatcherInterface* impl) + : internal::MatcherBase(impl) {} + + // Allows the user to write str instead of Eq(str) sometimes, where + // str is a string object. + Matcher(const internal::string& s); // NOLINT + + // Allows the user to write "foo" instead of Eq("foo") sometimes. + Matcher(const char* s); // NOLINT + + // Allows the user to pass StringPieces directly. + Matcher(StringPiece s); // NOLINT +}; +#endif // GTEST_HAS_STRING_PIECE_ + +// The PolymorphicMatcher class template makes it easy to implement a +// polymorphic matcher (i.e. a matcher that can match values of more +// than one type, e.g. Eq(n) and NotNull()). +// +// To define a polymorphic matcher, a user should provide an Impl +// class that has a DescribeTo() method and a DescribeNegationTo() +// method, and define a member function (or member function template) +// +// bool MatchAndExplain(const Value& value, +// MatchResultListener* listener) const; +// +// See the definition of NotNull() for a complete example. +template +class PolymorphicMatcher { + public: + explicit PolymorphicMatcher(const Impl& an_impl) : impl_(an_impl) {} + + // Returns a mutable reference to the underlying matcher + // implementation object. + Impl& mutable_impl() { return impl_; } + + // Returns an immutable reference to the underlying matcher + // implementation object. + const Impl& impl() const { return impl_; } + + template + operator Matcher() const { + return Matcher(new MonomorphicImpl(impl_)); + } + + private: + template + class MonomorphicImpl : public MatcherInterface { + public: + explicit MonomorphicImpl(const Impl& impl) : impl_(impl) {} + + virtual void DescribeTo(::std::ostream* os) const { + impl_.DescribeTo(os); + } + + virtual void DescribeNegationTo(::std::ostream* os) const { + impl_.DescribeNegationTo(os); + } + + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const { + return impl_.MatchAndExplain(x, listener); + } + + private: + const Impl impl_; + + GTEST_DISALLOW_ASSIGN_(MonomorphicImpl); + }; + + Impl impl_; + + GTEST_DISALLOW_ASSIGN_(PolymorphicMatcher); +}; + +// Creates a matcher from its implementation. This is easier to use +// than the Matcher constructor as it doesn't require you to +// explicitly write the template argument, e.g. +// +// MakeMatcher(foo); +// vs +// Matcher(foo); +template +inline Matcher MakeMatcher(const MatcherInterface* impl) { + return Matcher(impl); +} + +// Creates a polymorphic matcher from its implementation. This is +// easier to use than the PolymorphicMatcher constructor as it +// doesn't require you to explicitly write the template argument, e.g. +// +// MakePolymorphicMatcher(foo); +// vs +// PolymorphicMatcher(foo); +template +inline PolymorphicMatcher MakePolymorphicMatcher(const Impl& impl) { + return PolymorphicMatcher(impl); +} + +// Anything inside the 'internal' namespace IS INTERNAL IMPLEMENTATION +// and MUST NOT BE USED IN USER CODE!!! +namespace internal { + +// The MatcherCastImpl class template is a helper for implementing +// MatcherCast(). We need this helper in order to partially +// specialize the implementation of MatcherCast() (C++ allows +// class/struct templates to be partially specialized, but not +// function templates.). + +// This general version is used when MatcherCast()'s argument is a +// polymorphic matcher (i.e. something that can be converted to a +// Matcher but is not one yet; for example, Eq(value)) or a value (for +// example, "hello"). +template +class MatcherCastImpl { + public: + static Matcher Cast(const M& polymorphic_matcher_or_value) { + // M can be a polymorhic matcher, in which case we want to use + // its conversion operator to create Matcher. Or it can be a value + // that should be passed to the Matcher's constructor. + // + // We can't call Matcher(polymorphic_matcher_or_value) when M is a + // polymorphic matcher because it'll be ambiguous if T has an implicit + // constructor from M (this usually happens when T has an implicit + // constructor from any type). + // + // It won't work to unconditionally implict_cast + // polymorphic_matcher_or_value to Matcher because it won't trigger + // a user-defined conversion from M to T if one exists (assuming M is + // a value). + return CastImpl( + polymorphic_matcher_or_value, + BooleanConstant< + internal::ImplicitlyConvertible >::value>()); + } + + private: + static Matcher CastImpl(const M& value, BooleanConstant) { + // M can't be implicitly converted to Matcher, so M isn't a polymorphic + // matcher. It must be a value then. Use direct initialization to create + // a matcher. + return Matcher(ImplicitCast_(value)); + } + + static Matcher CastImpl(const M& polymorphic_matcher_or_value, + BooleanConstant) { + // M is implicitly convertible to Matcher, which means that either + // M is a polymorhpic matcher or Matcher has an implicit constructor + // from M. In both cases using the implicit conversion will produce a + // matcher. + // + // Even if T has an implicit constructor from M, it won't be called because + // creating Matcher would require a chain of two user-defined conversions + // (first to create T from M and then to create Matcher from T). + return polymorphic_matcher_or_value; + } +}; + +// This more specialized version is used when MatcherCast()'s argument +// is already a Matcher. This only compiles when type T can be +// statically converted to type U. +template +class MatcherCastImpl > { + public: + static Matcher Cast(const Matcher& source_matcher) { + return Matcher(new Impl(source_matcher)); + } + + private: + class Impl : public MatcherInterface { + public: + explicit Impl(const Matcher& source_matcher) + : source_matcher_(source_matcher) {} + + // We delegate the matching logic to the source matcher. + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const { + return source_matcher_.MatchAndExplain(static_cast(x), listener); + } + + virtual void DescribeTo(::std::ostream* os) const { + source_matcher_.DescribeTo(os); + } + + virtual void DescribeNegationTo(::std::ostream* os) const { + source_matcher_.DescribeNegationTo(os); + } + + private: + const Matcher source_matcher_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; +}; + +// This even more specialized version is used for efficiently casting +// a matcher to its own type. +template +class MatcherCastImpl > { + public: + static Matcher Cast(const Matcher& matcher) { return matcher; } +}; + +} // namespace internal + +// In order to be safe and clear, casting between different matcher +// types is done explicitly via MatcherCast(m), which takes a +// matcher m and returns a Matcher. It compiles only when T can be +// statically converted to the argument type of m. +template +inline Matcher MatcherCast(const M& matcher) { + return internal::MatcherCastImpl::Cast(matcher); +} + +// Implements SafeMatcherCast(). +// +// We use an intermediate class to do the actual safe casting as Nokia's +// Symbian compiler cannot decide between +// template ... (M) and +// template ... (const Matcher&) +// for function templates but can for member function templates. +template +class SafeMatcherCastImpl { + public: + // This overload handles polymorphic matchers and values only since + // monomorphic matchers are handled by the next one. + template + static inline Matcher Cast(const M& polymorphic_matcher_or_value) { + return internal::MatcherCastImpl::Cast(polymorphic_matcher_or_value); + } + + // This overload handles monomorphic matchers. + // + // In general, if type T can be implicitly converted to type U, we can + // safely convert a Matcher to a Matcher (i.e. Matcher is + // contravariant): just keep a copy of the original Matcher, convert the + // argument from type T to U, and then pass it to the underlying Matcher. + // The only exception is when U is a reference and T is not, as the + // underlying Matcher may be interested in the argument's address, which + // is not preserved in the conversion from T to U. + template + static inline Matcher Cast(const Matcher& matcher) { + // Enforce that T can be implicitly converted to U. + GTEST_COMPILE_ASSERT_((internal::ImplicitlyConvertible::value), + T_must_be_implicitly_convertible_to_U); + // Enforce that we are not converting a non-reference type T to a reference + // type U. + GTEST_COMPILE_ASSERT_( + internal::is_reference::value || !internal::is_reference::value, + cannot_convert_non_referentce_arg_to_reference); + // In case both T and U are arithmetic types, enforce that the + // conversion is not lossy. + typedef GTEST_REMOVE_REFERENCE_AND_CONST_(T) RawT; + typedef GTEST_REMOVE_REFERENCE_AND_CONST_(U) RawU; + const bool kTIsOther = GMOCK_KIND_OF_(RawT) == internal::kOther; + const bool kUIsOther = GMOCK_KIND_OF_(RawU) == internal::kOther; + GTEST_COMPILE_ASSERT_( + kTIsOther || kUIsOther || + (internal::LosslessArithmeticConvertible::value), + conversion_of_arithmetic_types_must_be_lossless); + return MatcherCast(matcher); + } +}; + +template +inline Matcher SafeMatcherCast(const M& polymorphic_matcher) { + return SafeMatcherCastImpl::Cast(polymorphic_matcher); +} + +// A() returns a matcher that matches any value of type T. +template +Matcher A(); + +// Anything inside the 'internal' namespace IS INTERNAL IMPLEMENTATION +// and MUST NOT BE USED IN USER CODE!!! +namespace internal { + +// If the explanation is not empty, prints it to the ostream. +inline void PrintIfNotEmpty(const internal::string& explanation, + ::std::ostream* os) { + if (explanation != "" && os != NULL) { + *os << ", " << explanation; + } +} + +// Returns true if the given type name is easy to read by a human. +// This is used to decide whether printing the type of a value might +// be helpful. +inline bool IsReadableTypeName(const string& type_name) { + // We consider a type name readable if it's short or doesn't contain + // a template or function type. + return (type_name.length() <= 20 || + type_name.find_first_of("<(") == string::npos); +} + +// Matches the value against the given matcher, prints the value and explains +// the match result to the listener. Returns the match result. +// 'listener' must not be NULL. +// Value cannot be passed by const reference, because some matchers take a +// non-const argument. +template +bool MatchPrintAndExplain(Value& value, const Matcher& matcher, + MatchResultListener* listener) { + if (!listener->IsInterested()) { + // If the listener is not interested, we do not need to construct the + // inner explanation. + return matcher.Matches(value); + } + + StringMatchResultListener inner_listener; + const bool match = matcher.MatchAndExplain(value, &inner_listener); + + UniversalPrint(value, listener->stream()); +#if GTEST_HAS_RTTI + const string& type_name = GetTypeName(); + if (IsReadableTypeName(type_name)) + *listener->stream() << " (of type " << type_name << ")"; +#endif + PrintIfNotEmpty(inner_listener.str(), listener->stream()); + + return match; +} + +// An internal helper class for doing compile-time loop on a tuple's +// fields. +template +class TuplePrefix { + public: + // TuplePrefix::Matches(matcher_tuple, value_tuple) returns true + // iff the first N fields of matcher_tuple matches the first N + // fields of value_tuple, respectively. + template + static bool Matches(const MatcherTuple& matcher_tuple, + const ValueTuple& value_tuple) { + return TuplePrefix::Matches(matcher_tuple, value_tuple) + && get(matcher_tuple).Matches(get(value_tuple)); + } + + // TuplePrefix::ExplainMatchFailuresTo(matchers, values, os) + // describes failures in matching the first N fields of matchers + // against the first N fields of values. If there is no failure, + // nothing will be streamed to os. + template + static void ExplainMatchFailuresTo(const MatcherTuple& matchers, + const ValueTuple& values, + ::std::ostream* os) { + // First, describes failures in the first N - 1 fields. + TuplePrefix::ExplainMatchFailuresTo(matchers, values, os); + + // Then describes the failure (if any) in the (N - 1)-th (0-based) + // field. + typename tuple_element::type matcher = + get(matchers); + typedef typename tuple_element::type Value; + Value value = get(values); + StringMatchResultListener listener; + if (!matcher.MatchAndExplain(value, &listener)) { + // TODO(wan): include in the message the name of the parameter + // as used in MOCK_METHOD*() when possible. + *os << " Expected arg #" << N - 1 << ": "; + get(matchers).DescribeTo(os); + *os << "\n Actual: "; + // We remove the reference in type Value to prevent the + // universal printer from printing the address of value, which + // isn't interesting to the user most of the time. The + // matcher's MatchAndExplain() method handles the case when + // the address is interesting. + internal::UniversalPrint(value, os); + PrintIfNotEmpty(listener.str(), os); + *os << "\n"; + } + } +}; + +// The base case. +template <> +class TuplePrefix<0> { + public: + template + static bool Matches(const MatcherTuple& /* matcher_tuple */, + const ValueTuple& /* value_tuple */) { + return true; + } + + template + static void ExplainMatchFailuresTo(const MatcherTuple& /* matchers */, + const ValueTuple& /* values */, + ::std::ostream* /* os */) {} +}; + +// TupleMatches(matcher_tuple, value_tuple) returns true iff all +// matchers in matcher_tuple match the corresponding fields in +// value_tuple. It is a compiler error if matcher_tuple and +// value_tuple have different number of fields or incompatible field +// types. +template +bool TupleMatches(const MatcherTuple& matcher_tuple, + const ValueTuple& value_tuple) { + // Makes sure that matcher_tuple and value_tuple have the same + // number of fields. + GTEST_COMPILE_ASSERT_(tuple_size::value == + tuple_size::value, + matcher_and_value_have_different_numbers_of_fields); + return TuplePrefix::value>:: + Matches(matcher_tuple, value_tuple); +} + +// Describes failures in matching matchers against values. If there +// is no failure, nothing will be streamed to os. +template +void ExplainMatchFailureTupleTo(const MatcherTuple& matchers, + const ValueTuple& values, + ::std::ostream* os) { + TuplePrefix::value>::ExplainMatchFailuresTo( + matchers, values, os); +} + +// TransformTupleValues and its helper. +// +// TransformTupleValuesHelper hides the internal machinery that +// TransformTupleValues uses to implement a tuple traversal. +template +class TransformTupleValuesHelper { + private: + typedef ::testing::tuple_size TupleSize; + + public: + // For each member of tuple 't', taken in order, evaluates '*out++ = f(t)'. + // Returns the final value of 'out' in case the caller needs it. + static OutIter Run(Func f, const Tuple& t, OutIter out) { + return IterateOverTuple()(f, t, out); + } + + private: + template + struct IterateOverTuple { + OutIter operator() (Func f, const Tup& t, OutIter out) const { + *out++ = f(::testing::get(t)); + return IterateOverTuple()(f, t, out); + } + }; + template + struct IterateOverTuple { + OutIter operator() (Func /* f */, const Tup& /* t */, OutIter out) const { + return out; + } + }; +}; + +// Successively invokes 'f(element)' on each element of the tuple 't', +// appending each result to the 'out' iterator. Returns the final value +// of 'out'. +template +OutIter TransformTupleValues(Func f, const Tuple& t, OutIter out) { + return TransformTupleValuesHelper::Run(f, t, out); +} + +// Implements A(). +template +class AnyMatcherImpl : public MatcherInterface { + public: + virtual bool MatchAndExplain( + T /* x */, MatchResultListener* /* listener */) const { return true; } + virtual void DescribeTo(::std::ostream* os) const { *os << "is anything"; } + virtual void DescribeNegationTo(::std::ostream* os) const { + // This is mostly for completeness' safe, as it's not very useful + // to write Not(A()). However we cannot completely rule out + // such a possibility, and it doesn't hurt to be prepared. + *os << "never matches"; + } +}; + +// Implements _, a matcher that matches any value of any +// type. This is a polymorphic matcher, so we need a template type +// conversion operator to make it appearing as a Matcher for any +// type T. +class AnythingMatcher { + public: + template + operator Matcher() const { return A(); } +}; + +// Implements a matcher that compares a given value with a +// pre-supplied value using one of the ==, <=, <, etc, operators. The +// two values being compared don't have to have the same type. +// +// The matcher defined here is polymorphic (for example, Eq(5) can be +// used to match an int, a short, a double, etc). Therefore we use +// a template type conversion operator in the implementation. +// +// The following template definition assumes that the Rhs parameter is +// a "bare" type (i.e. neither 'const T' nor 'T&'). +template +class ComparisonBase { + public: + explicit ComparisonBase(const Rhs& rhs) : rhs_(rhs) {} + template + operator Matcher() const { + return MakeMatcher(new Impl(rhs_)); + } + + private: + template + class Impl : public MatcherInterface { + public: + explicit Impl(const Rhs& rhs) : rhs_(rhs) {} + virtual bool MatchAndExplain( + Lhs lhs, MatchResultListener* /* listener */) const { + return Op()(lhs, rhs_); + } + virtual void DescribeTo(::std::ostream* os) const { + *os << D::Desc() << " "; + UniversalPrint(rhs_, os); + } + virtual void DescribeNegationTo(::std::ostream* os) const { + *os << D::NegatedDesc() << " "; + UniversalPrint(rhs_, os); + } + private: + Rhs rhs_; + GTEST_DISALLOW_ASSIGN_(Impl); + }; + Rhs rhs_; + GTEST_DISALLOW_ASSIGN_(ComparisonBase); +}; + +template +class EqMatcher : public ComparisonBase, Rhs, AnyEq> { + public: + explicit EqMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyEq>(rhs) { } + static const char* Desc() { return "is equal to"; } + static const char* NegatedDesc() { return "isn't equal to"; } +}; +template +class NeMatcher : public ComparisonBase, Rhs, AnyNe> { + public: + explicit NeMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyNe>(rhs) { } + static const char* Desc() { return "isn't equal to"; } + static const char* NegatedDesc() { return "is equal to"; } +}; +template +class LtMatcher : public ComparisonBase, Rhs, AnyLt> { + public: + explicit LtMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyLt>(rhs) { } + static const char* Desc() { return "is <"; } + static const char* NegatedDesc() { return "isn't <"; } +}; +template +class GtMatcher : public ComparisonBase, Rhs, AnyGt> { + public: + explicit GtMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyGt>(rhs) { } + static const char* Desc() { return "is >"; } + static const char* NegatedDesc() { return "isn't >"; } +}; +template +class LeMatcher : public ComparisonBase, Rhs, AnyLe> { + public: + explicit LeMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyLe>(rhs) { } + static const char* Desc() { return "is <="; } + static const char* NegatedDesc() { return "isn't <="; } +}; +template +class GeMatcher : public ComparisonBase, Rhs, AnyGe> { + public: + explicit GeMatcher(const Rhs& rhs) + : ComparisonBase, Rhs, AnyGe>(rhs) { } + static const char* Desc() { return "is >="; } + static const char* NegatedDesc() { return "isn't >="; } +}; + +// Implements the polymorphic IsNull() matcher, which matches any raw or smart +// pointer that is NULL. +class IsNullMatcher { + public: + template + bool MatchAndExplain(const Pointer& p, + MatchResultListener* /* listener */) const { +#if GTEST_LANG_CXX11 + return p == nullptr; +#else // GTEST_LANG_CXX11 + return GetRawPointer(p) == NULL; +#endif // GTEST_LANG_CXX11 + } + + void DescribeTo(::std::ostream* os) const { *os << "is NULL"; } + void DescribeNegationTo(::std::ostream* os) const { + *os << "isn't NULL"; + } +}; + +// Implements the polymorphic NotNull() matcher, which matches any raw or smart +// pointer that is not NULL. +class NotNullMatcher { + public: + template + bool MatchAndExplain(const Pointer& p, + MatchResultListener* /* listener */) const { +#if GTEST_LANG_CXX11 + return p != nullptr; +#else // GTEST_LANG_CXX11 + return GetRawPointer(p) != NULL; +#endif // GTEST_LANG_CXX11 + } + + void DescribeTo(::std::ostream* os) const { *os << "isn't NULL"; } + void DescribeNegationTo(::std::ostream* os) const { + *os << "is NULL"; + } +}; + +// Ref(variable) matches any argument that is a reference to +// 'variable'. This matcher is polymorphic as it can match any +// super type of the type of 'variable'. +// +// The RefMatcher template class implements Ref(variable). It can +// only be instantiated with a reference type. This prevents a user +// from mistakenly using Ref(x) to match a non-reference function +// argument. For example, the following will righteously cause a +// compiler error: +// +// int n; +// Matcher m1 = Ref(n); // This won't compile. +// Matcher m2 = Ref(n); // This will compile. +template +class RefMatcher; + +template +class RefMatcher { + // Google Mock is a generic framework and thus needs to support + // mocking any function types, including those that take non-const + // reference arguments. Therefore the template parameter T (and + // Super below) can be instantiated to either a const type or a + // non-const type. + public: + // RefMatcher() takes a T& instead of const T&, as we want the + // compiler to catch using Ref(const_value) as a matcher for a + // non-const reference. + explicit RefMatcher(T& x) : object_(x) {} // NOLINT + + template + operator Matcher() const { + // By passing object_ (type T&) to Impl(), which expects a Super&, + // we make sure that Super is a super type of T. In particular, + // this catches using Ref(const_value) as a matcher for a + // non-const reference, as you cannot implicitly convert a const + // reference to a non-const reference. + return MakeMatcher(new Impl(object_)); + } + + private: + template + class Impl : public MatcherInterface { + public: + explicit Impl(Super& x) : object_(x) {} // NOLINT + + // MatchAndExplain() takes a Super& (as opposed to const Super&) + // in order to match the interface MatcherInterface. + virtual bool MatchAndExplain( + Super& x, MatchResultListener* listener) const { + *listener << "which is located @" << static_cast(&x); + return &x == &object_; + } + + virtual void DescribeTo(::std::ostream* os) const { + *os << "references the variable "; + UniversalPrinter::Print(object_, os); + } + + virtual void DescribeNegationTo(::std::ostream* os) const { + *os << "does not reference the variable "; + UniversalPrinter::Print(object_, os); + } + + private: + const Super& object_; + + GTEST_DISALLOW_ASSIGN_(Impl); + }; + + T& object_; + + GTEST_DISALLOW_ASSIGN_(RefMatcher); +}; + +// Polymorphic helper functions for narrow and wide string matchers. +inline bool CaseInsensitiveCStringEquals(const char* lhs, const char* rhs) { + return String::CaseInsensitiveCStringEquals(lhs, rhs); +} + +inline bool CaseInsensitiveCStringEquals(const wchar_t* lhs, + const wchar_t* rhs) { + return String::CaseInsensitiveWideCStringEquals(lhs, rhs); +} + +// String comparison for narrow or wide strings that can have embedded NUL +// characters. +template +bool CaseInsensitiveStringEquals(const StringType& s1, + const StringType& s2) { + // Are the heads equal? + if (!CaseInsensitiveCStringEquals(s1.c_str(), s2.c_str())) { + return false; + } + + // Skip the equal heads. + const typename StringType::value_type nul = 0; + const size_t i1 = s1.find(nul), i2 = s2.find(nul); + + // Are we at the end of either s1 or s2? + if (i1 == StringType::npos || i2 == StringType::npos) { + return i1 == i2; + } + + // Are the tails equal? + return CaseInsensitiveStringEquals(s1.substr(i1 + 1), s2.substr(i2 + 1)); +} + +// String matchers. + +// Implements equality-based string matchers like StrEq, StrCaseNe, and etc. +template +class StrEqualityMatcher { + public: + StrEqualityMatcher(const StringType& str, bool expect_eq, + bool case_sensitive) + : string_(str), expect_eq_(expect_eq), case_sensitive_(case_sensitive) {} + + // Accepts pointer types, particularly: + // const char* + // char* + // const wchar_t* + // wchar_t* + template + bool MatchAndExplain(CharType* s, MatchResultListener* listener) const { + if (s == NULL) { + return !expect_eq_; + } + return MatchAndExplain(StringType(s), listener); + } + + // Matches anything that can convert to StringType. + // + // This is a template, not just a plain function with const StringType&, + // because StringPiece has some interfering non-explicit constructors. + template + bool MatchAndExplain(const MatcheeStringType& s, + MatchResultListener* /* listener */) const { + const StringType& s2(s); + const bool eq = case_sensitive_ ? s2 == string_ : + CaseInsensitiveStringEquals(s2, string_); + return expect_eq_ == eq; + } + + void DescribeTo(::std::ostream* os) const { + DescribeToHelper(expect_eq_, os); + } + + void DescribeNegationTo(::std::ostream* os) const { + DescribeToHelper(!expect_eq_, os); + } + + private: + void DescribeToHelper(bool expect_eq, ::std::ostream* os) const { + *os << (expect_eq ? "is " : "isn't "); + *os << "equal to "; + if (!case_sensitive_) { + *os << "(ignoring case) "; + } + UniversalPrint(string_, os); + } + + const StringType string_; + const bool expect_eq_; + const bool case_sensitive_; + + GTEST_DISALLOW_ASSIGN_(StrEqualityMatcher); +}; + +// Implements the polymorphic HasSubstr(substring) matcher, which +// can be used as a Matcher as long as T can be converted to a +// string. +template +class HasSubstrMatcher { + public: + explicit HasSubstrMatcher(const StringType& substring) + : substring_(substring) {} + + // Accepts pointer types, particularly: + // const char* + // char* + // const wchar_t* + // wchar_t* + template + bool MatchAndExplain(CharType* s, MatchResultListener* listener) const { + return s != NULL && MatchAndExplain(StringType(s), listener); + } + + // Matches anything that can convert to StringType. + // + // This is a template, not just a plain function with const StringType&, + // because StringPiece has some interfering non-explicit constructors. + template + bool MatchAndExplain(const MatcheeStringType& s, + MatchResultListener* /* listener */) const { + const StringType& s2(s); + return s2.find(substring_) != StringType::npos; + } + + // Describes what this matcher matches. + void DescribeTo(::std::ostream* os) const { + *os << "has substring "; + UniversalPrint(substring_, os); + } + + void DescribeNegationTo(::std::ostream* os) const { + *os << "has no substring "; + UniversalPrint(substring_, os); + } + + private: + const StringType substring_; + + GTEST_DISALLOW_ASSIGN_(HasSubstrMatcher); +}; + +// Implements the polymorphic StartsWith(substring) matcher, which +// can be used as a Matcher as long as T can be converted to a +// string. +template +class StartsWithMatcher { + public: + explicit StartsWithMatcher(const StringType& prefix) : prefix_(prefix) { + } + + // Accepts pointer types, particularly: + // const char* + // char* + // const wchar_t* + // wchar_t* + template + bool MatchAndExplain(CharType* s, MatchResultListener* listener) const { + return s != NULL && MatchAndExplain(StringType(s), listener); + } + + // Matches anything that can convert to StringType. + // + // This is a template, not just a plain function with const StringType&, + // because StringPiece has some interfering non-explicit constructors. + template + bool MatchAndExplain(const MatcheeStringType& s, + MatchResultListener* /* listener */) const { + const StringType& s2(s); + return s2.length() >= prefix_.length() && + s2.substr(0, prefix_.length()) == prefix_; + } + + void DescribeTo(::std::ostream* os) const { + *os << "starts with "; + UniversalPrint(prefix_, os); + } + + void DescribeNegationTo(::std::ostream* os) const { + *os << "doesn't start with "; + UniversalPrint(prefix_, os); + } + + private: + const StringType prefix_; + + GTEST_DISALLOW_ASSIGN_(StartsWithMatcher); +}; + +// Implements the polymorphic EndsWith(substring) matcher, which +// can be used as a Matcher as long as T can be converted to a +// string. +template +class EndsWithMatcher { + public: + explicit EndsWithMatcher(const StringType& suffix) : suffix_(suffix) {} + + // Accepts pointer types, particularly: + // const char* + // char* + // const wchar_t* + // wchar_t* + template + bool MatchAndExplain(CharType* s, MatchResultListener* listener) const { + return s != NULL && MatchAndExplain(StringType(s), listener); + } + + // Matches anything that can convert to StringType. + // + // This is a template, not just a plain function with const StringType&, + // because StringPiece has some interfering non-explicit constructors. + template + bool MatchAndExplain(const MatcheeStringType& s, + MatchResultListener* /* listener */) const { + const StringType& s2(s); + return s2.length() >= suffix_.length() && + s2.substr(s2.length() - suffix_.length()) == suffix_; + } + + void DescribeTo(::std::ostream* os) const { + *os << "ends with "; + UniversalPrint(suffix_, os); + } + + void DescribeNegationTo(::std::ostream* os) const { + *os << "doesn't end with "; + UniversalPrint(suffix_, os); + } + + private: + const StringType suffix_; + + GTEST_DISALLOW_ASSIGN_(EndsWithMatcher); +}; + +// Implements polymorphic matchers MatchesRegex(regex) and +// ContainsRegex(regex), which can be used as a Matcher as long as +// T can be converted to a string. +class MatchesRegexMatcher { + public: + MatchesRegexMatcher(const RE* regex, bool full_match) + : regex_(regex), full_match_(full_match) {} + + // Accepts pointer types, particularly: + // const char* + // char* + // const wchar_t* + // wchar_t* + template + bool MatchAndExplain(CharType* s, MatchResultListener* listener) const { + return s != NULL && MatchAndExplain(internal::string(s), listener); + } + + // Matches anything that can convert to internal::string. + // + // This is a template, not just a plain function with const internal::string&, + // because StringPiece has some interfering non-explicit constructors. + template + bool MatchAndExplain(const MatcheeStringType& s, + MatchResultListener* /* listener */) const { + const internal::string& s2(s); + return full_match_ ? RE::FullMatch(s2, *regex_) : + RE::PartialMatch(s2, *regex_); + } + + void DescribeTo(::std::ostream* os) const { + *os << (full_match_ ? "matches" : "contains") + << " regular expression "; + UniversalPrinter::Print(regex_->pattern(), os); + } + + void DescribeNegationTo(::std::ostream* os) const { + *os << "doesn't " << (full_match_ ? "match" : "contain") + << " regular expression "; + UniversalPrinter::Print(regex_->pattern(), os); + } + + private: + const internal::linked_ptr regex_; + const bool full_match_; + + GTEST_DISALLOW_ASSIGN_(MatchesRegexMatcher); +}; + +// Implements a matcher that compares the two fields of a 2-tuple +// using one of the ==, <=, <, etc, operators. The two fields being +// compared don't have to have the same type. +// +// The matcher defined here is polymorphic (for example, Eq() can be +// used to match a tuple, a tuple, +// etc). Therefore we use a template type conversion operator in the +// implementation. +template +class PairMatchBase { + public: + template + operator Matcher< ::testing::tuple >() const { + return MakeMatcher(new Impl< ::testing::tuple >); + } + template + operator Matcher&>() const { + return MakeMatcher(new Impl&>); + } + + private: + static ::std::ostream& GetDesc(::std::ostream& os) { // NOLINT + return os << D::Desc(); + } + + template + class Impl : public MatcherInterface { + public: + virtual bool MatchAndExplain( + Tuple args, + MatchResultListener* /* listener */) const { + return Op()(::testing::get<0>(args), ::testing::get<1>(args)); + } + virtual void DescribeTo(::std::ostream* os) const { + *os << "are " << GetDesc; + } + virtual void DescribeNegationTo(::std::ostream* os) const { + *os << "aren't " << GetDesc; + } + }; +}; + +class Eq2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "an equal pair"; } +}; +class Ne2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "an unequal pair"; } +}; +class Lt2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "a pair where the first < the second"; } +}; +class Gt2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "a pair where the first > the second"; } +}; +class Le2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "a pair where the first <= the second"; } +}; +class Ge2Matcher : public PairMatchBase { + public: + static const char* Desc() { return "a pair where the first >= the second"; } +}; + +// Implements the Not(...) matcher for a particular argument type T. +// We do not nest it inside the NotMatcher class template, as that +// will prevent different instantiations of NotMatcher from sharing +// the same NotMatcherImpl class. +template +class NotMatcherImpl : public MatcherInterface { + public: + explicit NotMatcherImpl(const Matcher& matcher) + : matcher_(matcher) {} + + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const { + return !matcher_.MatchAndExplain(x, listener); + } + + virtual void DescribeTo(::std::ostream* os) const { + matcher_.DescribeNegationTo(os); + } + + virtual void DescribeNegationTo(::std::ostream* os) const { + matcher_.DescribeTo(os); + } + + private: + const Matcher matcher_; + + GTEST_DISALLOW_ASSIGN_(NotMatcherImpl); +}; + +// Implements the Not(m) matcher, which matches a value that doesn't +// match matcher m. +template +class NotMatcher { + public: + explicit NotMatcher(InnerMatcher matcher) : matcher_(matcher) {} + + // This template type conversion operator allows Not(m) to be used + // to match any type m can match. + template + operator Matcher() const { + return Matcher(new NotMatcherImpl(SafeMatcherCast(matcher_))); + } + + private: + InnerMatcher matcher_; + + GTEST_DISALLOW_ASSIGN_(NotMatcher); +}; + +// Implements the AllOf(m1, m2) matcher for a particular argument type +// T. We do not nest it inside the BothOfMatcher class template, as +// that will prevent different instantiations of BothOfMatcher from +// sharing the same BothOfMatcherImpl class. +template +class BothOfMatcherImpl : public MatcherInterface { + public: + BothOfMatcherImpl(const Matcher& matcher1, const Matcher& matcher2) + : matcher1_(matcher1), matcher2_(matcher2) {} + + virtual void DescribeTo(::std::ostream* os) const { + *os << "("; + matcher1_.DescribeTo(os); + *os << ") and ("; + matcher2_.DescribeTo(os); + *os << ")"; + } + + virtual void DescribeNegationTo(::std::ostream* os) const { + *os << "("; + matcher1_.DescribeNegationTo(os); + *os << ") or ("; + matcher2_.DescribeNegationTo(os); + *os << ")"; + } + + virtual bool MatchAndExplain(T x, MatchResultListener* listener) const { + // If either matcher1_ or matcher2_ doesn't match x, we only need + // to explain why one of them fails. + StringMatchResultListener listener1; + if (!matcher1_.MatchAndExplain(x, &listener1)) { + *listener << listener1.str(); + return false; + } + + StringMatchResultListener listener2; + if (!matcher2_.MatchAndExplain(x, &listener2)) { + *listener << listener2.str(); + return false; + } + + // Otherwise we need to explain why *both* of them match. + const internal::string s1 = listener1.str(); + const internal::string s2 = listener2.str(); + + if (s1 == "") { + *listener << s2; + } else { + *listener << s1; + if (s2 != "") { + *listener << ", and " << s2; + } + } + return true; + } + + private: + const Matcher matcher1_; + const Matcher matcher2_; + + GTEST_DISALLOW_ASSIGN_(BothOfMatcherImpl); +}; + +#if GTEST_LANG_CXX11 +// MatcherList provides mechanisms for storing a variable number of matchers in +// a list structure (ListType) and creating a combining matcher from such a +// list. +// The template is defined recursively using the following template paramters: +// * kSize is the length of the MatcherList. +// * Head is the type of the first matcher of the list. +// * Tail denotes the types of the remaining matchers of the list. +template +struct MatcherList { + typedef MatcherList MatcherListTail; + typedef ::std::pair ListType; + + // BuildList stores variadic type values in a nested pair structure. + // Example: + // MatcherList<3, int, string, float>::BuildList(5, "foo", 2.0) will return + // the corresponding result of type pair>. + static ListType BuildList(const Head& matcher, const Tail&... tail) { + return ListType(matcher, MatcherListTail::BuildList(tail...)); + } + + // CreateMatcher creates a Matcher from a given list of matchers (built + // by BuildList()). CombiningMatcher is used to combine the matchers of the + // list. CombiningMatcher must implement MatcherInterface and have a + // constructor taking two Matchers as input. + template class CombiningMatcher> + static Matcher CreateMatcher(const ListType& matchers) { + return Matcher(new CombiningMatcher( + SafeMatcherCast(matchers.first), + MatcherListTail::template CreateMatcher( + matchers.second))); + } +}; + +// The following defines the base case for the recursive definition of +// MatcherList. +template +struct MatcherList<2, Matcher1, Matcher2> { + typedef ::std::pair ListType; + + static ListType BuildList(const Matcher1& matcher1, + const Matcher2& matcher2) { + return ::std::pair(matcher1, matcher2); + } + + template class CombiningMatcher> + static Matcher CreateMatcher(const ListType& matchers) { + return Matcher(new CombiningMatcher( + SafeMatcherCast(matchers.first), + SafeMatcherCast(matchers.second))); + } +}; + +// VariadicMatcher is used for the variadic implementation of +// AllOf(m_1, m_2, ...) and AnyOf(m_1, m_2, ...). +// CombiningMatcher is used to recursively combine the provided matchers +// (of type Args...). +template

cX3|#%2 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 literal 0 HcmV?d00001 diff --git a/data/libmv-ba-problems/problem_03.bin b/data/libmv-ba-problems/problem_03.bin new file mode 100644 index 0000000000000000000000000000000000000000..5a2910da58c2af6e4a389e453f86c5aac0ce2335 GIT binary patch literal 125582 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 z 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 + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + ga('create', 'UA-49769510-1', 'ceres-solver.org'); + ga('send', 'pageview'); + +{% endblock %} diff --git a/docs/source/analytical_derivatives.rst b/docs/source/analytical_derivatives.rst new file mode 100644 index 0000000..2a3a404 --- /dev/null +++ b/docs/source/analytical_derivatives.rst @@ -0,0 +1,192 @@ +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-analytical_derivatives: + +==================== +Analytic Derivatives +==================== + +Consider the problem of fitting the following curve (`Rat43 +`_) to +data: + +.. math:: + y = \frac{b_1}{(1+e^{b_2-b_3x})^{1/b_4}} + +That is, given some data :math:`\{x_i, y_i\},\ \forall i=1,... ,n`, +determine parameters :math:`b_1, b_2, b_3` and :math:`b_4` that best +fit this data. + +Which can be stated as the problem of finding the +values of :math:`b_1, b_2, b_3` and :math:`b_4` are the ones that +minimize the following objective function [#f1]_: + +.. math:: + \begin{align} + E(b_1, b_2, b_3, b_4) + &= \sum_i f^2(b_1, b_2, b_3, b_4 ; x_i, y_i)\\ + &= \sum_i \left(\frac{b_1}{(1+e^{b_2-b_3x_i})^{1/b_4}} - y_i\right)^2\\ + \end{align} + +To solve this problem using Ceres Solver, we need to define a +:class:`CostFunction` that computes the residual :math:`f` for a given +:math:`x` and :math:`y` and its derivatives with respect to +:math:`b_1, b_2, b_3` and :math:`b_4`. + +Using elementary differential calculus, we can see that: + +.. math:: + \begin{align} + D_1 f(b_1, b_2, b_3, b_4; x,y) &= \frac{1}{(1+e^{b_2-b_3x})^{1/b_4}}\\ + D_2 f(b_1, b_2, b_3, b_4; x,y) &= + \frac{-b_1e^{b_2-b_3x}}{b_4(1+e^{b_2-b_3x})^{1/b_4 + 1}} \\ + D_3 f(b_1, b_2, b_3, b_4; x,y) &= + \frac{b_1xe^{b_2-b_3x}}{b_4(1+e^{b_2-b_3x})^{1/b_4 + 1}} \\ + D_4 f(b_1, b_2, b_3, b_4; x,y) & = \frac{b_1 \log\left(1+e^{b_2-b_3x}\right) }{b_4^2(1+e^{b_2-b_3x})^{1/b_4}} + \end{align} + +With these derivatives in hand, we can now implement the +:class:`CostFunction` as: + +.. code-block:: c++ + + class Rat43Analytic : public SizedCostFunction<1,4> { + public: + Rat43Analytic(const double x, const double y) : x_(x), y_(y) {} + virtual ~Rat43Analytic() {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + const double b1 = parameters[0][0]; + const double b2 = parameters[0][1]; + const double b3 = parameters[0][2]; + const double b4 = parameters[0][3]; + + residuals[0] = b1 * pow(1 + exp(b2 - b3 * x_), -1.0 / b4) - y_; + + if (!jacobians) return true; + double* jacobian = jacobians[0]; + if (!jacobian) return true; + + jacobian[0] = pow(1 + exp(b2 - b3 * x_), -1.0 / b4); + jacobian[1] = -b1 * exp(b2 - b3 * x_) * + pow(1 + exp(b2 - b3 * x_), -1.0 / b4 - 1) / b4; + jacobian[2] = x_ * b1 * exp(b2 - b3 * x_) * + pow(1 + exp(b2 - b3 * x_), -1.0 / b4 - 1) / b4; + jacobian[3] = b1 * log(1 + exp(b2 - b3 * x_)) * + pow(1 + exp(b2 - b3 * x_), -1.0 / b4) / (b4 * b4); + return true; + } + + private: + const double x_; + const double y_; + }; + +This is tedious code, hard to read and with a lot of +redundancy. So in practice we will cache some sub-expressions to +improve its efficiency, which would give us something like: + +.. code-block:: c++ + + class Rat43AnalyticOptimized : public SizedCostFunction<1,4> { + public: + Rat43AnalyticOptimized(const double x, const double y) : x_(x), y_(y) {} + virtual ~Rat43AnalyticOptimized() {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + const double b1 = parameters[0][0]; + const double b2 = parameters[0][1]; + const double b3 = parameters[0][2]; + const double b4 = parameters[0][3]; + + const double t1 = exp(b2 - b3 * x_); + const double t2 = 1 + t1; + const double t3 = pow(t2, -1.0 / b4); + residuals[0] = b1 * t3 - y_; + + if (!jacobians) return true; + double* jacobian = jacobians[0]; + if (!jacobian) return true; + + const double t4 = pow(t2, -1.0 / b4 - 1); + jacobian[0] = t3; + jacobian[1] = -b1 * t1 * t4 / b4; + jacobian[2] = -x_ * jacobian[1]; + jacobian[3] = b1 * log(t2) * t3 / (b4 * b4); + return true; + } + + private: + const double x_; + const double y_; + }; + +What is the difference in performance of these two implementations? + +========================== ========= +CostFunction Time (ns) +========================== ========= +Rat43Analytic 255 +Rat43AnalyticOptimized 92 +========================== ========= + +``Rat43AnalyticOptimized`` is :math:`2.8` times faster than +``Rat43Analytic``. This difference in run-time is not uncommon. To +get the best performance out of analytically computed derivatives, one +usually needs to optimize the code to account for common +sub-expressions. + + +When should you use analytical derivatives? +=========================================== + +#. The expressions are simple, e.g. mostly linear. + +#. A computer algebra system like `Maple + `_ , `Mathematica + `_, or `SymPy + `_ can be used to symbolically + differentiate the objective function and generate the C++ to + evaluate them. + +#. Performance is of utmost concern and there is algebraic structure + in the terms that you can exploit to get better performance than + automatic differentiation. + + That said, getting the best performance out of analytical + derivatives requires a non-trivial amount of work. Before going + down this path, it is useful to measure the amount of time being + spent evaluating the Jacobian as a fraction of the total solve time + and remember `Amdahl's Law + `_ is your friend. + +#. There is no other way to compute the derivatives, e.g. you + wish to compute the derivative of the root of a polynomial: + + .. math:: + a_3(x,y)z^3 + a_2(x,y)z^2 + a_1(x,y)z + a_0(x,y) = 0 + + + with respect to :math:`x` and :math:`y`. This requires the use of + the `Inverse Function Theorem + `_ + +#. You love the chain rule and actually enjoy doing all the algebra by + hand. + + +.. rubric:: Footnotes + +.. [#f1] The notion of best fit depends on the choice of the objective + function used to measure the quality of fit, which in turn + depends on the underlying noise process which generated the + observations. Minimizing the sum of squared differences is + the right thing to do when the noise is `Gaussian + `_. In + that case the optimal value of the parameters is the `Maximum + Likelihood Estimate + `_. diff --git a/docs/source/automatic_derivatives.rst b/docs/source/automatic_derivatives.rst new file mode 100644 index 0000000..1251814 --- /dev/null +++ b/docs/source/automatic_derivatives.rst @@ -0,0 +1,307 @@ +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-automatic_derivatives: + +===================== +Automatic Derivatives +===================== + +We will now consider automatic differentiation. It is a technique that +can compute exact derivatives, fast, while requiring about the same +effort from the user as is needed to use numerical differentiation. + +Don't believe me? Well here goes. The following code fragment +implements an automatically differentiated ``CostFunction`` for `Rat43 +`_. + +.. code-block:: c++ + + struct Rat43CostFunctor { + Rat43CostFunctor(const double x, const double y) : x_(x), y_(y) {} + + template + bool operator()(const T* parameters, T* residuals) const { + const T b1 = parameters[0]; + const T b2 = parameters[1]; + const T b3 = parameters[2]; + const T b4 = parameters[3]; + residuals[0] = b1 * pow(1.0 + exp(b2 - b3 * x_), -1.0 / b4) - y_; + return true; + } + + private: + const double x_; + const double y_; + }; + + + CostFunction* cost_function = + new AutoDiffCostFunction( + new Rat43CostFunctor(x, y)); + +Notice that compared to numeric differentiation, the only difference +when defining the functor for use with automatic differentiation is +the signature of the ``operator()``. + +In the case of numeric differentition it was + +.. code-block:: c++ + + bool operator()(const double* parameters, double* residuals) const; + +and for automatic differentiation it is a templated function of the +form + +.. code-block:: c++ + + template bool operator()(const T* parameters, T* residuals) const; + + +So what does this small change buy us? The following table compares +the time it takes to evaluate the residual and the Jacobian for +`Rat43` using various methods. + +========================== ========= +CostFunction Time (ns) +========================== ========= +Rat43Analytic 255 +Rat43AnalyticOptimized 92 +Rat43NumericDiffForward 262 +Rat43NumericDiffCentral 517 +Rat43NumericDiffRidders 3760 +Rat43AutomaticDiff 129 +========================== ========= + +We can get exact derivatives using automatic differentiation +(``Rat43AutomaticDiff``) with about the same effort that is required +to write the code for numeric differentiation but only :math:`40\%` +slower than hand optimized analytical derivatives. + +So how does it work? For this we will have to learn about **Dual +Numbers** and **Jets** . + + +Dual Numbers & Jets +=================== + +.. NOTE:: + + Reading this and the next section on implementing Jets is not + necessary to use automatic differentiation in Ceres Solver. But + knowing the basics of how Jets work is useful when debugging and + reasoning about the performance of automatic differentiation. + +Dual numbers are an extension of the real numbers analogous to complex +numbers: whereas complex numbers augment the reals by introducing an +imaginary unit :math:`\iota` such that :math:`\iota^2 = -1`, dual +numbers introduce an *infinitesimal* unit :math:`\epsilon` such that +:math:`\epsilon^2 = 0` . A dual number :math:`a + v\epsilon` has two +components, the *real* component :math:`a` and the *infinitesimal* +component :math:`v`. + +Surprisingly, this simple change leads to a convenient method for +computing exact derivatives without needing to manipulate complicated +symbolic expressions. + +For example, consider the function + +.. math:: + + f(x) = x^2 , + +Then, + +.. math:: + + \begin{align} + f(10 + \epsilon) &= (10 + \epsilon)^2\\ + &= 100 + 20 \epsilon + \epsilon^2\\ + &= 100 + 20 \epsilon + \end{align} + +Observe that the coefficient of :math:`\epsilon` is :math:`Df(10) = +20`. Indeed this generalizes to functions which are not +polynomial. Consider an arbitrary differentiable function +:math:`f(x)`. Then we can evaluate :math:`f(x + \epsilon)` by +considering the Taylor expansion of :math:`f` near :math:`x`, which +gives us the infinite series + +.. math:: + \begin{align} + f(x + \epsilon) &= f(x) + Df(x) \epsilon + D^2f(x) + \frac{\epsilon^2}{2} + D^3f(x) \frac{\epsilon^3}{6} + \cdots\\ + f(x + \epsilon) &= f(x) + Df(x) \epsilon + \end{align} + +Here we are using the fact that :math:`\epsilon^2 = 0`. + +A `Jet `_ is a +:math:`n`-dimensional dual number, where we augment the real numbers +with :math:`n` infinitesimal units :math:`\epsilon_i,\ i=1,...,n` with +the property that :math:`\forall i, j\ :\epsilon_i\epsilon_j = 0`. Then +a Jet consists of a *real* part :math:`a` and a :math:`n`-dimensional +*infinitesimal* part :math:`\mathbf{v}`, i.e., + +.. math:: + x = a + \sum_j v_{j} \epsilon_j + +The summation notation gets tedious, so we will also just write + +.. math:: + x = a + \mathbf{v}. + +where the :math:`\epsilon_i`'s are implict. Then, using the same +Taylor series expansion used above, we can see that: + +.. math:: + + f(a + \mathbf{v}) = f(a) + Df(a) \mathbf{v}. + +Similarly for a multivariate function +:math:`f:\mathbb{R}^{n}\rightarrow \mathbb{R}^m`, evaluated on +:math:`x_i = a_i + \mathbf{v}_i,\ \forall i = 1,...,n`: + +.. math:: + f(x_1,..., x_n) = f(a_1, ..., a_n) + \sum_i D_i f(a_1, ..., a_n) \mathbf{v}_i + +So if each :math:`\mathbf{v}_i = e_i` were the :math:`i^{\text{th}}` +standard basis vector, then, the above expression would simplify to + +.. math:: + f(x_1,..., x_n) = f(a_1, ..., a_n) + \sum_i D_i f(a_1, ..., a_n) \epsilon_i + +and we can extract the coordinates of the Jacobian by inspecting the +coefficients of :math:`\epsilon_i`. + +Implementing Jets +----------------- + +In order for the above to work in practice, we will need the ability +to evaluate an arbitrary function :math:`f` not just on real numbers +but also on dual numbers, but one does not usually evaluate functions +by evaluating their Taylor expansions, + +This is where C++ templates and operator overloading comes into +play. The following code fragment has a simple implementation of a +``Jet`` and some operators/functions that operate on them. + +.. code-block:: c++ + + template struct Jet { + double a; + Eigen::Matrix v; + }; + + template Jet operator+(const Jet& f, const Jet& g) { + return Jet(f.a + g.a, f.v + g.v); + } + + template Jet operator-(const Jet& f, const Jet& g) { + return Jet(f.a - g.a, f.v - g.v); + } + + template Jet operator*(const Jet& f, const Jet& g) { + return Jet(f.a * g.a, f.a * g.v + f.v * g.a); + } + + template Jet operator/(const Jet& f, const Jet& g) { + return Jet(f.a / g.a, f.v / g.a - f.a * g.v / (g.a * g.a)); + } + + template Jet exp(const Jet& f) { + return Jet(exp(f.a), exp(f.a) * f.v); + } + + // This is a simple implementation for illustration purposes, the + // actual implementation of pow requires careful handling of a number + // of corner cases. + template Jet pow(const Jet& f, const Jet& g) { + return Jet(pow(f.a, g.a), + g.a * pow(f.a, g.a - 1.0) * f.v + + pow(f.a, g.a) * log(f.a); * g.v); + } + + +With these overloaded functions in hand, we can now call +``Rat43CostFunctor`` with an array of Jets instead of doubles. Putting +that together with appropriately initialized Jets allows us to compute +the Jacobian as follows: + +.. code-block:: c++ + + class Rat43Automatic : public ceres::SizedCostFunction<1,4> { + public: + Rat43Automatic(const Rat43CostFunctor* functor) : functor_(functor) {} + virtual ~Rat43Automatic() {} + virtual bool Evaluate(double const* const* parameters, + double* residuals, + double** jacobians) const { + // Just evaluate the residuals if Jacobians are not required. + if (!jacobians) return (*functor_)(parameters[0], residuals); + + // Initialize the Jets + ceres::Jet<4> jets[4]; + for (int i = 0; i < 4; ++i) { + jets[i].a = parameters[0][i]; + jets[i].v.setZero(); + jets[i].v[i] = 1.0; + } + + ceres::Jet<4> result; + (*functor_)(jets, &result); + + // Copy the values out of the Jet. + residuals[0] = result.a; + for (int i = 0; i < 4; ++i) { + jacobians[0][i] = result.v[i]; + } + return true; + } + + private: + std::unique_ptr functor_; + }; + +Indeed, this is essentially how :class:`AutoDiffCostFunction` works. + + +Pitfalls +======== + +Automatic differentiation frees the user from the burden of computing +and reasoning about the symbolic expressions for the Jacobians, but +this freedom comes at a cost. For example consider the following +simple functor: + +.. code-block:: c++ + + struct Functor { + template bool operator()(const T* x, T* residual) const { + residual[0] = 1.0 - sqrt(x[0] * x[0] + x[1] * x[1]); + return true; + } + }; + +Looking at the code for the residual computation, one does not foresee +any problems. However, if we look at the analytical expressions for +the Jacobian: + +.. math:: + + y &= 1 - \sqrt{x_0^2 + x_1^2}\\ + D_1y &= -\frac{x_0}{\sqrt{x_0^2 + x_1^2}},\ + D_2y = -\frac{x_1}{\sqrt{x_0^2 + x_1^2}} + +we find that it is an indeterminate form at :math:`x_0 = 0, x_1 = +0`. + +There is no single solution to this problem. In some cases one needs +to reason explicitly about the points where indeterminacy may occur +and use alternate expressions using `L'Hopital's rule +`_ (see for +example some of the conversion routines in `rotation.h +`_. In +other cases, one may need to regularize the expressions to eliminate +these points. diff --git a/docs/source/bibliography.rst b/docs/source/bibliography.rst new file mode 100644 index 0000000..5352c65 --- /dev/null +++ b/docs/source/bibliography.rst @@ -0,0 +1,132 @@ +.. _sec-bibliography: + +============ +Bibliography +============ + +.. [Agarwal] S. Agarwal, N. Snavely, S. M. Seitz and R. Szeliski, + **Bundle Adjustment in the Large**, *Proceedings of the European + Conference on Computer Vision*, pp. 29--42, 2010. + +.. [Bjorck] A. Bjorck, **Numerical Methods for Least Squares + Problems**, SIAM, 1996 + +.. [Brown] D. C. Brown, **A solution to the general problem of + multiple station analytical stereo triangulation**, Technical + Report 43, Patrick Airforce Base, Florida, 1958. + +.. [ByrdNocedal] R. H. Byrd, J. Nocedal, R. B. Schanbel, + **Representations of Quasi-Newton Matrices and their use in Limited + Memory Methods**, *Mathematical Programming* 63(4):129–-156, 1994. + +.. [ByrdSchnabel] R.H. Byrd, R.B. Schnabel, and G.A. Shultz, **Approximate + solution of the trust region problem by minimization over + two dimensional subspaces**, *Mathematical programming*, + 40(1):247–263, 1988. + +.. [Chen] Y. Chen, T. A. Davis, W. W. Hager, and + S. Rajamanickam, **Algorithm 887: CHOLMOD, Supernodal Sparse + Cholesky Factorization and Update/Downdate**, *TOMS*, 35(3), 2008. + +.. [Conn] A.R. Conn, N.I.M. Gould, and P.L. Toint, **Trust region + methods**, *Society for Industrial Mathematics*, 2000. + +.. [GolubPereyra] G.H. Golub and V. Pereyra, **The differentiation of + pseudo-inverses and nonlinear least squares problems whose + variables separate**, *SIAM Journal on numerical analysis*, + 10(2):413–432, 1973. + +.. [HartleyZisserman] R.I. Hartley & A. Zisserman, **Multiview + Geometry in Computer Vision**, Cambridge University Press, 2004. + +.. [KanataniMorris] K. Kanatani and D. D. Morris, **Gauges and gauge + transformations for uncertainty description of geometric structure + with indeterminacy**, *IEEE Transactions on Information Theory* + 47(5):2017-2028, 2001. + +.. [Keys] R. G. Keys, **Cubic convolution interpolation for digital + image processing**, *IEEE Trans. on Acoustics, Speech, and Signal + Processing*, 29(6), 1981. + +.. [KushalAgarwal] A. Kushal and S. Agarwal, **Visibility based + preconditioning for bundle adjustment**, *In Proceedings of the + IEEE Conference on Computer Vision and Pattern Recognition*, 2012. + +.. [Kanzow] C. Kanzow, N. Yamashita and M. Fukushima, + **Levenberg–Marquardt methods with strong local convergence + properties for solving nonlinear equations with convex + constraints**, *Journal of Computational and Applied Mathematics*, + 177(2):375–397, 2005. + +.. [Levenberg] K. Levenberg, **A method for the solution of certain + nonlinear problems in least squares**, *Quart. Appl. Math*, + 2(2):164–168, 1944. + +.. [LiSaad] Na Li and Y. Saad, **MIQR: A multilevel incomplete qr + preconditioner for large sparse least squares problems**, *SIAM + Journal on Matrix Analysis and Applications*, 28(2):524–550, 2007. + +.. [Madsen] K. Madsen, H.B. Nielsen, and O. Tingleff, **Methods for + nonlinear least squares problems**, 2004. + +.. [Mandel] J. Mandel, **On block diagonal and Schur complement + preconditioning**, *Numer. Math.*, 58(1):79–93, 1990. + +.. [Marquardt] D.W. Marquardt, **An algorithm for least squares + estimation of nonlinear parameters**, *J. SIAM*, 11(2):431–441, + 1963. + +.. [Mathew] T.P.A. Mathew, **Domain decomposition methods for the + numerical solution of partial differential equations**, Springer + Verlag, 2008. + +.. [NashSofer] S.G. Nash and A. Sofer, **Assessing a search direction + within a truncated newton method**, *Operations Research Letters*, + 9(4):219–221, 1990. + +.. [Nocedal] J. Nocedal, **Updating Quasi-Newton Matrices with Limited + Storage**, *Mathematics of Computation*, 35(151): 773--782, 1980. + +.. [NocedalWright] J. Nocedal & S. Wright, **Numerical Optimization**, + Springer, 2004. + +.. [Oren] S. S. Oren, **Self-scaling Variable Metric (SSVM) Algorithms + Part II: Implementation and Experiments**, Management Science, + 20(5), 863-874, 1974. + +.. [Press] W. H. Press, S. A. Teukolsky, W. T. Vetterling + & B. P. Flannery, **Numerical Recipes**, Cambridge University + Press, 2007. + +.. [Ridders] C. J. F. Ridders, **Accurate computation of F'(x) and + F'(x) F"(x)**, Advances in Engineering Software 4(2), 75-76, 1978. + +.. [RuheWedin] A. Ruhe and P.Å. Wedin, **Algorithms for separable + nonlinear least squares problems**, Siam Review, 22(3):318–337, + 1980. + +.. [Saad] Y. Saad, **Iterative methods for sparse linear + systems**, SIAM, 2003. + +.. [Stigler] S. M. Stigler, **Gauss and the invention of least + squares**, *The Annals of Statistics*, 9(3):465-474, 1981. + +.. [TenenbaumDirector] J. Tenenbaum & B. Director, **How Gauss + Determined the Orbit of Ceres**. + +.. [TrefethenBau] L.N. Trefethen and D. Bau, **Numerical Linear + Algebra**, SIAM, 1997. + +.. [Triggs] B. Triggs, P. F. Mclauchlan, R. I. Hartley & + A. W. Fitzgibbon, **Bundle Adjustment: A Modern Synthesis**, + Proceedings of the International Workshop on Vision Algorithms: + Theory and Practice, pp. 298-372, 1999. + +.. [Wiberg] T. Wiberg, **Computation of principal components when data + are missing**, In Proc. *Second Symp. Computational Statistics*, + pages 229–236, 1976. + +.. [WrightHolt] S. J. Wright and J. N. Holt, **An Inexact + Levenberg Marquardt Method for Large Sparse Nonlinear Least + Squares**, *Journal of the Australian Mathematical Society Series + B*, 26(4):387–403, 1985. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..17de116 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# Ceres Solver documentation build configuration file, created by +# sphinx-quickstart on Sun Jan 20 20:34:07 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Ceres Solver' +copyright = u'2016 Google Inc' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.13' +# The full version, including alpha/beta/rc tags. +release = '1.13.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["_themes",] +import sphinx_rtd_theme +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "Ceres Solver" + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +html_domain_indices = True + +# If false, no index is generated. +html_use_index = True + +# If true, the index is split into individual pages for each letter. +html_split_index = False + +# If true, links to the reST sources are added to the pages. +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'CeresSolverdoc' + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'CeresSolver.tex', u'Ceres Solver', + u'Sameer Agarwal, Keir Mierle & Others', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'ceressolver', u'Ceres Solver', + [u'Sameer Agarwal, Keir Mierle & Others'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'CeresSolver', u'Ceres Solver', + u'Sameer Agarwal, Keir Mierle & Others', 'CeresSolver', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000..b8f8165 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,131 @@ +.. _chapter-contributing: + +============ +Contributing +============ + +We welcome contributions to Ceres, whether they are new features, bug +fixes or tests. The Ceres `mailing +`_ list is the best place +for all development related discussions. Please consider joining +it. If you have ideas on how you would like to contribute to Ceres, it +is a good idea to let us know on the mailing list before you start +development. We may have suggestions that will save effort when trying +to merge your work into the main branch. If you are looking for ideas, +please let us know about your interest and skills and we will be happy +to make a suggestion or three. + +We follow Google's `C++ Style Guide +`_ and +use `git `_ for version control. We use the +`Gerrit `_ to collaborate and +review changes to Ceres. Gerrit enables pre-commit reviews so that +Ceres can maintain a linear history with clean, reviewed commits, and +no merges. + +We now describe how to set up your development environment and submit +a change list for review via Gerrit. + +Setting up your Environment +=========================== + +1. Download and configure ``git``. + + * Mac ``brew install git``. + * Linux ``sudo apt-get install git``. + * Windows. Download `msysgit + `_, which includes a minimal + `Cygwin `_ install. + +2. Sign up for `Gerrit + `_. You will also + need to sign the Contributor License Agreement (CLA) with Google, + which gives Google a royalty-free unlimited license to use your + contributions. You retain copyright. + +3. Clone the Ceres Solver ``git`` repository from Gerrit. + + .. code-block:: bash + + git clone https://ceres-solver.googlesource.com/ceres-solver + + +4. Build Ceres, following the instructions in + :ref:`chapter-installation`. + + On Mac and Linux, the ``CMake`` build will download and enable + the Gerrit pre-commit hook automatically. This pre-submit hook + creates `Change-Id: ...` lines in your commits. + + If this does not work OR you are on Windows, execute the + following in the root directory of the local ``git`` repository: + + .. code-block:: bash + + curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg + chmod +x .git/hooks/commit-msg + +5. Configure your Gerrit password with a ``.gitcookies`` which allows pushing + to Gerrit without having to enter a very long random password every time: + + * Sign into `http://ceres-solver-review.googlesource.com + `_. + + * Click ``Settings -> HTTP Password -> Obtain Password``. + + * (maybe) Select an account for multi-login. This should be the + same as your Gerrit login. + + * Click ``Allow access`` when the page requests access to your + ``git`` repositories. + + * Follow the instructions from Gerrit to create a ``.gitcookies`` file on + your system, either in ``$HOME/.gitcookies`` (Mac and Linux) or + ``%USERPROFILE%\.gitcookies`` (Windows). Note that for Windows, please get + a recent `Git for Windows `_ install to + enable automatic lookup in the ``%USERPROFILE%\.gitcookies``. + +Submitting a change +=================== + +1. Make your changes against master or whatever branch you + like. Commit your changes as one patch. When you commit, the Gerrit + hook will add a `Change-Id:` line as the last line of the commit. + + Make sure that your commit message is formatted in the `50/72 style + `_. + +2. Push your changes to the Ceres Gerrit instance: + + .. code-block:: bash + + git push origin HEAD:refs/for/master + + When the push succeeds, the console will display a URL showing the + address of the review. Go to the URL and add at least one of the + maintainers (Sameer Agarwal, Keir Mierle, Alex Stewart or William + Rucklidge) as reviewers. + +3. Wait for a review. + +4. Once review comments come in, address them. Please reply to each + comment in Gerrit, which makes the re-review process easier. After + modifying the code in your ``git`` instance, *don't make a new + commit*. Instead, update the last commit using a command like the + following: + + .. code-block:: bash + + git commit --amend -a + + This will update the last commit, so that it has both the original + patch and your updates as a single commit. You will have a chance + to edit the commit message as well. Push the new commit to Gerrit + as before. + + Gerrit will use the ``Change-Id:`` to match the previous commit + with the new one. The review interface retains your original patch, + but also shows the new patch. + + Publish your responses to the comments, and wait for a new round + of reviews. diff --git a/docs/source/derivatives.rst b/docs/source/derivatives.rst new file mode 100644 index 0000000..bff6a29 --- /dev/null +++ b/docs/source/derivatives.rst @@ -0,0 +1,60 @@ +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +.. _chapter-on_derivatives: + +============== +On Derivatives +============== + +Ceres Solver, like all gradient based optimization algorithms, depends +on being able to evaluate the objective function and its derivatives +at arbitrary points in its domain. Indeed, defining the objective +function and its `Jacobian +`_ is +the principal task that the user is required to perform when solving +an optimization problem using Ceres Solver. The correct and efficient +computation of the Jacobian is the key to good performance. + +Ceres Solver offers considerable flexibility in how the user can +provide derivatives to the solver. She can use: + +#. :ref:`chapter-analytical_derivatives`: The user figures out the + derivatives herself, by hand or using a tool like `Maple + `_ or `Mathematica + `_, and implements them in a + :class:`CostFunction`. +#. :ref:`chapter-numerical_derivatives`: Ceres numerically computes + the derivative using finite differences. +#. :ref:`chapter-automatic_derivatives`: Ceres automatically computes + the analytic derivative using C++ templates and operator + overloading. + +Which of these three approaches (alone or in combination) should be +used depends on the situation and the tradeoffs the user is willing to +make. Unfortunately, numerical optimization textbooks rarely discuss +these issues in detail and the user is left to her own devices. + +The aim of this article is to fill this gap and describe each of these +three approaches in the context of Ceres Solver with sufficient detail +that the user can make an informed choice. + +For the impatient amongst you, here is some high level advice: + +#. Use :ref:`chapter-automatic_derivatives`. +#. In some cases it maybe worth using + :ref:`chapter-analytical_derivatives`. +#. Avoid :ref:`chapter-numerical_derivatives`. Use it as a measure of + last resort, mostly to interface with external libraries. + +For the rest, read on. + +.. toctree:: + :maxdepth: 1 + + spivak_notation + analytical_derivatives + numerical_derivatives + automatic_derivatives + interfacing_with_autodiff diff --git a/docs/source/faqs.rst b/docs/source/faqs.rst new file mode 100644 index 0000000..5a28f41 --- /dev/null +++ b/docs/source/faqs.rst @@ -0,0 +1,29 @@ +.. _chapter-tricks: + +.. default-domain:: cpp + +.. cpp:namespace:: ceres + +=================== +FAQS, Tips & Tricks +=================== + +Answers to frequently asked questions, tricks of the trade and general +wisdom. + +.. toctree:: + :maxdepth: 2 + + modeling_faqs + solving_faqs + + +Further Reading +=============== + +For a short but informative introduction to the subject we recommend +the booklet by [Madsen]_ . For a general introduction to non-linear +optimization we recommend [NocedalWright]_. [Bjorck]_ remains the +seminal reference on least squares problems. [TrefethenBau]_ book is +our favorite text on introductory numerical linear algebra. [Triggs]_ +provides a thorough coverage of the bundle adjustment problem. diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..1f5e91e --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,86 @@ +==== +Why? +==== +.. _chapter-features: + +* **Code Quality** - Ceres Solver has been used in production at + Google for more than four years now. It is clean, extensively tested + and well documented code that is actively developed and supported. + +* **Modeling API** - It is rarely the case that one starts with the + exact and complete formulation of the problem that one is trying to + solve. Ceres's modeling API has been designed so that the user can + easily build and modify the objective function, one term at a + time. And to do so without worrying about how the solver is going to + deal with the resulting changes in the sparsity/structure of the + underlying problem. + + - **Derivatives** Supplying derivatives is perhaps the most tedious + and error prone part of using an optimization library. Ceres + ships with `automatic`_ and `numeric`_ differentiation. So you + never have to compute derivatives by hand (unless you really want + to). Not only this, Ceres allows you to mix automatic, numeric and + analytical derivatives in any combination that you want. + + - **Robust Loss Functions** Most non-linear least squares problems + involve data. If there is data, there will be outliers. Ceres + allows the user to *shape* their residuals using a + :class:`LossFunction` to reduce the influence of outliers. + + - **Local Parameterization** In many cases, some parameters lie on a + manifold other than Euclidean space, e.g., rotation matrices. In + such cases, the user can specify the geometry of the local tangent + space by specifying a :class:`LocalParameterization` object. + +* **Solver Choice** Depending on the size, sparsity structure, time & + memory budgets, and solution quality requiremnts, different + optimization algorithms will suit different needs. To this end, + Ceres Solver comes with a variety of optimization algorithms: + + - **Trust Region Solvers** - Ceres supports Levenberg-Marquardt, + Powell's Dogleg, and Subspace dogleg methods. The key + computational cost in all of these methods is the solution of a + linear system. To this end Ceres ships with a variety of linear + solvers - dense QR and dense Cholesky factorization (using + `Eigen`_ or `LAPACK`_) for dense problems, sparse Cholesky + factorization (`SuiteSparse`_, `CXSparse`_ or `Eigen`_) for large + sparse problems custom Schur complement based dense, sparse, and + iterative linear solvers for `bundle adjustment`_ problems. + + - **Line Search Solvers** - When the problem size is so large that + storing and factoring the Jacobian is not feasible or a low + accuracy solution is required cheaply, Ceres offers a number of + line search based algorithms. This includes a number of variants + of Non-linear Conjugate Gradients, BFGS and LBFGS. + +* **Speed** - Ceres Solver has been extensively optimized, with C++ + templating, hand written linear algebra routines and OpenMP based + multithreading of the Jacobian evaluation and the linear solvers. + +* **Solution Quality** Ceres is the `best performing`_ solver on the NIST + problem set used by Mondragon and Borchers for benchmarking + non-linear least squares solvers. + +* **Covariance estimation** - Evaluate the sensitivity/uncertainty of + the solution by evaluating all or part of the covariance + matrix. Ceres is one of the few solvers that allows you to to do + this analysis at scale. + +* **Community** Since its release as an open source software, Ceres + has developed an active developer community that contributes new + features, bug fixes and support. + +* **Portability** - Runs on *Linux*, *Windows*, *Mac OS X*, *Android* + *and iOS*. + +* **BSD Licensed** The BSD license offers the flexibility to ship your + application + +.. _best performing: https://groups.google.com/forum/#!topic/ceres-solver/UcicgMPgbXw +.. _bundle adjustment: http://en.wikipedia.org/wiki/Bundle_adjustment +.. _SuiteSparse: http://www.cise.ufl.edu/research/sparse/SuiteSparse/ +.. _Eigen: http://eigen.tuxfamily.org/ +.. _LAPACK: http://www.netlib.org/lapack/ +.. _CXSparse: https://www.cise.ufl.edu/research/sparse/CXSparse/ +.. _automatic: http://en.wikipedia.org/wiki/Automatic_differentiation +.. _numeric: http://en.wikipedia.org/wiki/Numerical_differentiation diff --git a/docs/source/forward_central_error.png b/docs/source/forward_central_error.png new file mode 100644 index 0000000000000000000000000000000000000000..56d10b0c797bdb2949ee6375b0e8c6f44705ae3e GIT binary patch literal 57776 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 literal 0 HcmV?d00001 diff --git a/docs/source/forward_central_ridders_error.png b/docs/source/forward_central_ridders_error.png new file mode 100644 index 0000000000000000000000000000000000000000..ecea674eed4cae3f35af7b52c122b972a711ad13 GIT binary patch literal 75579 zcmeFYg;SL88#js~DoT85X@RA?JEWKHPHB+tMwAwiC6?~)?ncC=8)*=bSQ?g&^Wg7& z|AsSj<}f(>;0(`o-&cID`VgU_B!m8j=nWDQ5;|B`QVj{|g#r>1^842>f&bzEeu)Qs zyl@o;FIR?Iit8U7Br;yjHDf@ALjoxXb7^P~?Vb zwQ>R~Q2k#B2PG61hOcN!6%HYBj3(_q9~Zt0=*sjxP zk?b(tlT34>CH+@kcJt0C zO^asA_jT5$lYK9qKVvrTG*DDjWMF1aG<`?AbTMz0HKXs?QQ*As)21gFrB;VYuh}W* z;&9n_+9OU@QmN>y*j=eeJx(@Xe)Q?iVn-0R0*l13E>44$TG@+;cupOx@7^zHgcX#O zVh&rj$(H>ums5EiGZm(U4n4TJxfg0JqF6f4)ke~ImE&oZXAhcIEAQ_7nDy#+itR}; z!g|+_RpGts)g%})&r=h+AE`_;^?IC!PszwhYf;T=?wN5da&OR@5jtxW%*mI- z0PnjlAoAOct)_>^1%1EgURs)o+$YLz(I&0_cH z=;*!0CdY03RalZnYkk#B;lP|Zyv1|b_HBA|!;@`-Flq6jS`MBCNmYEuk(6cwR@Ic* zR`1z%3-;h}O&uLC1?{xc)6?mVFg_BDXcB(4p(JK?E+W9TiA2Q2+#i30J5*dNyvS42 zKRyl|v%e+1xsN1aE^(vB9WgNl-rueJciA7Kf&6Y?c*(ec;)16CCEDmGRWVF4lS%n& zKM}ysNa{prX=Ms+2H^;@hKEST%I|aV8DvbM>^b8=L*8Y#_$3EV&qUv!OCGzf1UGI{ zyGGt5s9-fAQ|kkkqJTCgnWKFVy3AiraZi?FC5Qo+d6IOZ`u2a;#w8S15`gJMcDDrU zy7-h>b1{@5e%Ao4C*M}dznV+9u z4!C!I_di$~IC}qtPW^~6rpmxMUvCM?&$0>-t{k(x!9I7F;cKfc0$ht`j`wG;6@2L1 zmMgu40)}sNn38av!Zk=z8NeGQfhJKFVb^Oj%VDwCk6d;>hFl3do(B|! zBrK!fJsv8I0fq=;O%#koB|7opmAp$?9}LR;^1;}*WFk+7F;3R{{svLv4uBFduY<