diff options
| author | Scott Ettinger <settinger@google.com> | 2013-09-09 12:54:43 -0700 |
|---|---|---|
| committer | Scott Ettinger <settinger@google.com> | 2013-09-10 00:29:21 +0000 |
| commit | 399f7d09e0c45af54b77b4ab9508d6f23759b927 (patch) | |
| tree | abf3b5ab8259679fb37a8e20308e8cd2a8cd439c | |
| parent | 1d2624a10e2c559f8ba9ef89eaa30832c0a83a96 (diff) | |
| download | ceres-solver-399f7d09e0c45af54b77b4ab9508d6f23759b927.tar.gz | |
Update Ceres to the latest versionandroid-sdk-4.4.2_r1.0.1android-sdk-4.4.2_r1android-l-preview_r2android-cts-4.4_r4android-cts-4.4_r1android-4.4w_r1android-4.4_r1.2.0.1android-4.4_r1.2android-4.4_r1.1.0.1android-4.4_r1.1android-4.4_r1.0.1android-4.4_r1android-4.4_r0.9android-4.4_r0.8android-4.4_r0.7android-4.4.4_r2.0.1android-4.4.4_r2android-4.4.4_r1.0.1android-4.4.4_r1android-4.4.3_r1.1.0.1android-4.4.3_r1.1android-4.4.3_r1.0.1android-4.4.3_r1android-4.4.2_r2.0.1android-4.4.2_r2android-4.4.2_r1.0.1android-4.4.2_r1android-4.4.1_r1.0.1android-4.4.1_r1l-previewkitkat-wearkitkat-releasekitkat-mr2.2-releasekitkat-mr2.1-releasekitkat-mr2-releasekitkat-mr1.1-releasekitkat-mr1-releasekitkat-devkitkat-cts-releasekitkat-cts-devidea133-weekly-releaseidea133
Bug: 10673139
Bug: 10621282
Change-Id: Ib740a6e0e29049cc203da9f083b0d4f5734a2741
87 files changed, 2464 insertions, 4117 deletions
@@ -1,3 +1,55 @@ +# Ceres Solver - A fast non-linear least squares minimizer +# Copyright 2010, 2011, 2012 Google Inc. All rights reserved. +# http://code.google.com/p/ceres-solver/ +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# * Neither the name of Google Inc. nor the names of its contributors may be +# used to endorse or promote products derived from this software without +# specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# +# Author: settinger@google.com (Scott Ettinger) +# keir@google.com (Keir Mierle) +# +# Builds Ceres for Android, using the standard toolchain (not standalone). It +# uses STLPort instead of GNU C++. This is useful for anyone wishing to ship +# GPL-free code. This cannot build the tests or other parts of Ceres; only the +# core libraries. If you need a more complete Ceres build, consider using the +# CMake toolchain (noting that the standalone toolchain doesn't work with +# STLPort). +# +# Reducing binary size: +# +# This build includes the Schur specializations, which cause binary bloat. If +# you don't need them for your application, consider adding: +# +# -DCERES_RESTRICT_SCHUR_SPECIALIZATION +# +# to the LOCAL_CFLAGS variable below, and commenting out all the +# generated/schur_eliminator_2_2_2.cc-alike files, leaving only the _d_d_d one. +# +# Similarly if you do not need the line search minimizer, consider adding +# +# -DCERES_NO_LINE_SEARCH_MINIMIZER + LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) @@ -8,25 +60,28 @@ LOCAL_NDK_STL_VARIANT := stlport_static LOCAL_C_INCLUDES := $(LOCAL_PATH)/internal \ $(LOCAL_PATH)/internal/ceres \ - $(LOCAL_PATH)/include \ $(LOCAL_PATH)/internal/ceres/miniglog \ - external/eigen + $(LOCAL_PATH)/include \ + external/eigen \ LOCAL_CPP_EXTENSION := .cc LOCAL_CPPFLAGS := -DCERES_NO_PROTOCOL_BUFFERS \ + -DCERES_NO_LAPACK \ -DCERES_NO_SUITESPARSE \ -DCERES_NO_GFLAGS \ -DCERES_NO_THREADS \ -DCERES_NO_CXSPARSE \ -DCERES_NO_TR1 \ -DCERES_WORK_AROUND_ANDROID_NDK_COMPILER_BUG \ + -DMAX_LOG_LEVEL=-1 \ -O3 -w # On Android NDK 8b, GCC gives spurrious warnings about ABI incompatibility for # which there is no solution. Hide the warning instead. -LOCAL_CPPFLAGS += -Wno-psabi +LOCAL_CFLAGS += -Wno-psabi LOCAL_SRC_FILES := internal/ceres/array_utils.cc \ + internal/ceres/blas.cc \ internal/ceres/block_evaluate_preparer.cc \ internal/ceres/block_jacobian_writer.cc \ internal/ceres/block_jacobi_preconditioner.cc \ @@ -53,6 +108,7 @@ LOCAL_SRC_FILES := internal/ceres/array_utils.cc \ internal/ceres/gradient_checking_cost_function.cc \ internal/ceres/implicit_schur_complement.cc \ internal/ceres/iterative_schur_complement_solver.cc \ + internal/ceres/lapack.cc \ internal/ceres/levenberg_marquardt_strategy.cc \ internal/ceres/line_search.cc \ internal/ceres/line_search_direction.cc \ @@ -63,7 +119,6 @@ LOCAL_SRC_FILES := internal/ceres/array_utils.cc \ internal/ceres/local_parameterization.cc \ internal/ceres/loss_function.cc \ internal/ceres/low_rank_inverse_hessian.cc \ - internal/ceres/miniglog/glog/logging.cc \ internal/ceres/minimizer.cc \ internal/ceres/normal_prior.cc \ internal/ceres/parameter_block_ordering.cc \ diff --git a/CMakeLists.txt b/CMakeLists.txt index db5acba..b89d55a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -83,59 +83,95 @@ SET(CERES_ABI_VERSION 1.7.0) ENABLE_TESTING() -OPTION(BUILD_TESTING - "Enable tests" +OPTION(MINIGLOG "Use a stripped down version of glog" OFF) +OPTION(GFLAGS "Enable Google Flags." 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) - -OPTION(BUILD_ANDROID - "Build for Android. Use build_android.sh instead of setting this." +# Multithreading using OpenMP +OPTION(OPENMP "Enable threaded solving in Ceres (requires OpenMP)" ON) +# TODO(sameeragarwal): Replace this with a positive option instead? +OPTION(DISABLE_TR1 + "Don't use TR1. This replaces some hash tables with sets. Slower." OFF) +# Line search minimizer is useful for large scale problems or when +# sparse linear algebra libraries are not available. If compile time, +# binary size or compiler performance is an issue, consider disabling +# this. +OPTION(LINE_SEARCH_MINIMIZER "Enable the line search minimizer." ON) +OPTION(BUILD_TESTING "Enable tests" ON) +OPTION(BUILD_DOCUMENTATION "Build User's Guide (html)" OFF) +OPTION(BUILD_EXAMPLES "Build examples" ON) -OPTION(BUILD_SHARED - "Build a dynamically linkable version of Ceres Solver." - ON) +# Default locations to search for on various platforms. -# To get a more static build, try the following line on Mac and Linux: -# SET(CMAKE_FIND_LIBRARY_SUFFIXES .a ${CMAKE_FIND_LIBRARY_SUFFIXES}) +# Libraries +LIST(APPEND CMAKE_LIBRARY_PATH /opt/local/lib) +LIST(APPEND CMAKE_LIBRARY_PATH /opt/local/lib/ufsparse) # Mac OS X +LIST(APPEND CMAKE_LIBRARY_PATH /usr/lib) +LIST(APPEND CMAKE_LIBRARY_PATH /usr/lib/atlas) +LIST(APPEND CMAKE_LIBRARY_PATH /usr/lib/suitesparse) # Ubuntu +LIST(APPEND CMAKE_LIBRARY_PATH /usr/lib64/atlas) +LIST(APPEND CMAKE_LIBRARY_PATH /usr/local/homebrew/lib) # Mac OS X +LIST(APPEND CMAKE_LIBRARY_PATH /usr/local/lib) +LIST(APPEND CMAKE_LIBRARY_PATH /usr/local/lib/suitesparse) + +# Headers +LIST(APPEND CMAKE_INCLUDE_PATH /opt/local/include) +LIST(APPEND CMAKE_INCLUDE_PATH /opt/local/include/ufsparse) # Mac OS X +LIST(APPEND CMAKE_INCLUDE_PATH /opt/local/var/macports/software/eigen3/opt/local/include/eigen3) # Mac OS X +LIST(APPEND CMAKE_INCLUDE_PATH /usr/include) +LIST(APPEND CMAKE_INCLUDE_PATH /usr/include/eigen3) # Ubuntu 10.04's default location. +LIST(APPEND CMAKE_INCLUDE_PATH /usr/include/suitesparse) # Ubuntu +LIST(APPEND CMAKE_INCLUDE_PATH /usr/local/homebrew/include) # Mac OS X +LIST(APPEND CMAKE_INCLUDE_PATH /usr/local/homebrew/include/eigen3) # Mac OS X +LIST(APPEND CMAKE_INCLUDE_PATH /usr/local/include) +LIST(APPEND CMAKE_INCLUDE_PATH /usr/local/include/eigen3) +LIST(APPEND CMAKE_INCLUDE_PATH /usr/local/include/suitesparse) -# Default locations to search for on various platforms. -LIST(APPEND SEARCH_LIBS /usr/lib) -LIST(APPEND SEARCH_LIBS /usr/local/lib) -LIST(APPEND SEARCH_LIBS /usr/local/homebrew/lib) # Mac OS X -LIST(APPEND SEARCH_LIBS /opt/local/lib) - -LIST(APPEND SEARCH_HEADERS /usr/include) -LIST(APPEND SEARCH_HEADERS /usr/local/include) -LIST(APPEND SEARCH_HEADERS /usr/local/homebrew/include) # Mac OS X -LIST(APPEND SEARCH_HEADERS /opt/local/include) - -# Locations to search for Eigen -SET(EIGEN_SEARCH_HEADERS ${SEARCH_HEADERS}) -LIST(APPEND EIGEN_SEARCH_HEADERS /usr/include/eigen3) # Ubuntu 10.04's default location. -LIST(APPEND EIGEN_SEARCH_HEADERS /usr/local/include/eigen3) -LIST(APPEND EIGEN_SEARCH_HEADERS /usr/local/homebrew/include/eigen3) # Mac OS X -LIST(APPEND EIGEN_SEARCH_HEADERS /opt/local/var/macports/software/eigen3/opt/local/include/eigen3) # Mac OS X - -# Locations to search for SuiteSparse -SET(SUITESPARSE_SEARCH_LIBS ${SEARCH_LIBS}) -LIST(APPEND SUITESPARSE_SEARCH_LIBS /usr/lib/suitesparse) # Ubuntu -LIST(APPEND SUITESPARSE_SEARCH_LIBS /usr/local/lib/suitesparse) -LIST(APPEND SUITESPARSE_SEARCH_LIBS /opt/local/lib/ufsparse) # Mac OS X - -SET(SUITESPARSE_SEARCH_HEADERS ${SEARCH_HEADERS}) -LIST(APPEND SUITESPARSE_SEARCH_HEADERS /usr/include/suitesparse) # Ubuntu -LIST(APPEND SUITESPARSE_SEARCH_HEADERS /usr/local/include/suitesparse) -LIST(APPEND SUITESPARSE_SEARCH_HEADERS /opt/local/include/ufsparse) # Mac OS X - -SET(CXSPARSE_SEARCH_LIBS ${SEARCH_LIBS}) -SET(CXSPARSE_SEARCH_HEADERS ${SEARCH_HEADERS}) -LIST(APPEND CXSPARSE_SEARCH_HEADERS /usr/include/suitesparse) # Ubuntu +# Eigen +FIND_PATH(EIGEN_INCLUDE NAMES Eigen/Core) +IF (NOT EXISTS ${EIGEN_INCLUDE}) + MESSAGE(FATAL_ERROR "Can't find Eigen. Try passing -DEIGEN_INCLUDE=...") +ELSE (NOT EXISTS ${EIGEN_INCLUDE}) + MESSAGE("-- Found Eigen 3.x: ${EIGEN_INCLUDE}") +ENDIF (NOT EXISTS ${EIGEN_INCLUDE}) + +SET(BLAS_AND_LAPACK_FOUND TRUE) +IF ((NOT DEFINED LAPACK) OR (DEFINED LAPACK AND LAPACK)) + FIND_PACKAGE(LAPACK) + IF (LAPACK_FOUND) + MESSAGE("-- Found LAPACK library: ${LAPACK_LIBRARIES}") + ELSE (LAPACK_FOUND) + MESSAGE("-- Did not find LAPACK library") + SET(BLAS_AND_LAPACK_FOUND FALSE) + ENDIF (LAPACK_FOUND) + + FIND_PACKAGE(BLAS) + IF (BLAS_FOUND) + MESSAGE("-- Found BLAS library: ${BLAS_LIBRARIES}") + ELSE (BLAS_FOUND) + MESSAGE("-- Did not find BLAS library") + SET(BLAS_AND_BLAS_FOUND FALSE) + ENDIF (BLAS_FOUND) + +ELSE ((NOT DEFINED LAPACK) OR (DEFINED LAPACK AND LAPACK)) + SET(BLAS_AND_LAPACK_FOUND FALSE) +ENDIF ((NOT DEFINED LAPACK) OR (DEFINED LAPACK AND LAPACK)) + +IF (NOT BLAS_AND_LAPACK_FOUND) + ADD_DEFINITIONS(-DCERES_NO_LAPACK) +ENDIF (NOT BLAS_AND_LAPACK_FOUND) IF ((NOT DEFINED SUITESPARSE) OR (DEFINED SUITESPARSE AND SUITESPARSE)) # Check for SuiteSparse dependencies SET(AMD_FOUND TRUE) -FIND_LIBRARY(AMD_LIB NAMES amd PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(AMD_LIB NAMES amd) IF (EXISTS ${AMD_LIB}) MESSAGE("-- Found AMD library: ${AMD_LIB}") ELSE (EXISTS ${AMD_LIB}) @@ -143,7 +179,7 @@ ELSE (EXISTS ${AMD_LIB}) SET(AMD_FOUND FALSE) ENDIF (EXISTS ${AMD_LIB}) -FIND_PATH(AMD_INCLUDE NAMES amd.h PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(AMD_INCLUDE NAMES amd.h) IF (EXISTS ${AMD_INCLUDE}) MESSAGE("-- Found AMD header in: ${AMD_INCLUDE}") ELSE (EXISTS ${AMD_INCLUDE}) @@ -152,7 +188,7 @@ ELSE (EXISTS ${AMD_INCLUDE}) ENDIF (EXISTS ${AMD_INCLUDE}) SET(CAMD_FOUND TRUE) -FIND_LIBRARY(CAMD_LIB NAMES camd PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(CAMD_LIB NAMES camd) IF (EXISTS ${CAMD_LIB}) MESSAGE("-- Found CAMD library: ${CAMD_LIB}") ELSE (EXISTS ${CAMD_LIB}) @@ -160,7 +196,7 @@ ELSE (EXISTS ${CAMD_LIB}) SET(CAMD_FOUND FALSE) ENDIF (EXISTS ${CAMD_LIB}) -FIND_PATH(CAMD_INCLUDE NAMES camd.h PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(CAMD_INCLUDE NAMES camd.h) IF (EXISTS ${CAMD_INCLUDE}) MESSAGE("-- Found CAMD header in: ${CAMD_INCLUDE}") ELSE (EXISTS ${CAMD_INCLUDE}) @@ -169,7 +205,7 @@ ELSE (EXISTS ${CAMD_INCLUDE}) ENDIF (EXISTS ${CAMD_INCLUDE}) SET(COLAMD_FOUND TRUE) -FIND_LIBRARY(COLAMD_LIB NAMES colamd PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(COLAMD_LIB NAMES colamd) IF (EXISTS ${COLAMD_LIB}) MESSAGE("-- Found COLAMD library: ${COLAMD_LIB}") ELSE (EXISTS ${COLAMD_LIB}) @@ -177,7 +213,7 @@ ELSE (EXISTS ${COLAMD_LIB}) SET(COLAMD_FOUND FALSE) ENDIF (EXISTS ${COLAMD_LIB}) -FIND_PATH(COLAMD_INCLUDE NAMES colamd.h PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(COLAMD_INCLUDE NAMES colamd.h) IF (EXISTS ${COLAMD_INCLUDE}) MESSAGE("-- Found COLAMD header in: ${COLAMD_INCLUDE}") ELSE (EXISTS ${COLAMD_INCLUDE}) @@ -186,7 +222,7 @@ ELSE (EXISTS ${COLAMD_INCLUDE}) ENDIF (EXISTS ${COLAMD_INCLUDE}) SET(CCOLAMD_FOUND TRUE) -FIND_LIBRARY(CCOLAMD_LIB NAMES ccolamd PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(CCOLAMD_LIB NAMES ccolamd) IF (EXISTS ${CCOLAMD_LIB}) MESSAGE("-- Found CCOLAMD library: ${CCOLAMD_LIB}") ELSE (EXISTS ${CCOLAMD_LIB}) @@ -194,7 +230,7 @@ ELSE (EXISTS ${CCOLAMD_LIB}) SET(CCOLAMD_FOUND FALSE) ENDIF (EXISTS ${CCOLAMD_LIB}) -FIND_PATH(CCOLAMD_INCLUDE NAMES ccolamd.h PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(CCOLAMD_INCLUDE NAMES ccolamd.h) IF (EXISTS ${CCOLAMD_INCLUDE}) MESSAGE("-- Found CCOLAMD header in: ${CCOLAMD_INCLUDE}") ELSE (EXISTS ${CCOLAMD_INCLUDE}) @@ -203,7 +239,7 @@ ELSE (EXISTS ${CCOLAMD_INCLUDE}) ENDIF (EXISTS ${CCOLAMD_INCLUDE}) SET(CHOLMOD_FOUND TRUE) -FIND_LIBRARY(CHOLMOD_LIB NAMES cholmod PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(CHOLMOD_LIB NAMES cholmod) IF (EXISTS ${CHOLMOD_LIB}) MESSAGE("-- Found CHOLMOD library: ${CHOLMOD_LIB}") ELSE (EXISTS ${CHOLMOD_LIB}) @@ -211,7 +247,7 @@ ELSE (EXISTS ${CHOLMOD_LIB}) SET(CHOLMOD_FOUND FALSE) ENDIF (EXISTS ${CHOLMOD_LIB}) -FIND_PATH(CHOLMOD_INCLUDE NAMES cholmod.h PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(CHOLMOD_INCLUDE NAMES cholmod.h) IF (EXISTS ${CHOLMOD_INCLUDE}) MESSAGE("-- Found CHOLMOD header in: ${CHOLMOD_INCLUDE}") ELSE (EXISTS ${CHOLMOD_INCLUDE}) @@ -220,7 +256,7 @@ ELSE (EXISTS ${CHOLMOD_INCLUDE}) ENDIF (EXISTS ${CHOLMOD_INCLUDE}) SET(SUITESPARSEQR_FOUND TRUE) -FIND_LIBRARY(SUITESPARSEQR_LIB NAMES spqr PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(SUITESPARSEQR_LIB NAMES spqr) IF (EXISTS ${SUITESPARSEQR_LIB}) MESSAGE("-- Found SUITESPARSEQR library: ${SUITESPARSEQR_LIB}") ELSE (EXISTS ${SUITESPARSEQR_LIB}) @@ -228,7 +264,7 @@ ELSE (EXISTS ${SUITESPARSEQR_LIB}) SET(SUITESPARSEQR_FOUND FALSE) ENDIF (EXISTS ${SUITESPARSEQR_LIB}) -FIND_PATH(SUITESPARSEQR_INCLUDE NAMES SuiteSparseQR.hpp PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(SUITESPARSEQR_INCLUDE NAMES SuiteSparseQR.hpp) IF (EXISTS ${SUITESPARSEQR_INCLUDE}) MESSAGE("-- Found SUITESPARSEQR header in: ${SUITESPARSEQR_INCLUDE}") ELSE (EXISTS ${SUITESPARSEQR_INCLUDE}) @@ -241,18 +277,14 @@ ENDIF (EXISTS ${SUITESPARSEQR_INCLUDE}) SET(SUITESPARSE_CONFIG_FOUND TRUE) SET(UFCONFIG_FOUND TRUE) -FIND_LIBRARY(SUITESPARSE_CONFIG_LIB - NAMES suitesparseconfig - PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(SUITESPARSE_CONFIG_LIB NAMES suitesparseconfig) IF (EXISTS ${SUITESPARSE_CONFIG_LIB}) MESSAGE("-- Found SuiteSparse_config library: ${SUITESPARSE_CONFIG_LIB}") ELSE (EXISTS ${SUITESPARSE_CONFIG_LIB}) MESSAGE("-- Did not find SuiteSparse_config library") ENDIF (EXISTS ${SUITESPARSE_CONFIG_LIB}) -FIND_PATH(SUITESPARSE_CONFIG_INCLUDE - NAMES SuiteSparse_config.h - PATHS ${SUITESPARSE_SEARCH_HEADERS}) +FIND_PATH(SUITESPARSE_CONFIG_INCLUDE NAMES SuiteSparse_config.h) IF (EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) MESSAGE("-- Found SuiteSparse_config header in: ${SUITESPARSE_CONFIG_INCLUDE}") SET(UFCONFIG_FOUND FALSE) @@ -260,20 +292,20 @@ ELSE (EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) MESSAGE("-- Did not find SuiteSparse_config header") ENDIF (EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) -IF (NOT EXISTS ${SUITESPARSE_CONFIG_LIB} OR NOT EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) +IF (NOT EXISTS ${SUITESPARSE_CONFIG_LIB} OR + NOT EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) SET(SUITESPARSE_CONFIG_FOUND FALSE) - FIND_PATH(UFCONFIG_INCLUDE - NAMES UFconfig.h - PATHS ${SUITESPARSE_SEARCH_HEADERS}) + FIND_PATH(UFCONFIG_INCLUDE NAMES UFconfig.h) IF (EXISTS ${UFCONFIG_INCLUDE}) MESSAGE("-- Found UFconfig header in: ${UFCONFIG_INCLUDE}") ELSE (EXISTS ${UFCONFIG_INCLUDE}) MESSAGE("-- Did not find UFconfig header") SET(UFCONFIG_FOUND FALSE) ENDIF (EXISTS ${UFCONFIG_INCLUDE}) -ENDIF (NOT EXISTS ${SUITESPARSE_CONFIG_LIB} OR NOT EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) +ENDIF (NOT EXISTS ${SUITESPARSE_CONFIG_LIB} OR + NOT EXISTS ${SUITESPARSE_CONFIG_INCLUDE}) -FIND_LIBRARY(METIS_LIB NAMES metis PATHS ${SUITESPARSE_SEARCH_LIBS}) +FIND_LIBRARY(METIS_LIB NAMES metis) IF (EXISTS ${METIS_LIB}) MESSAGE("-- Found METIS library: ${METIS_LIB}") ELSE (EXISTS ${METIS_LIB}) @@ -282,7 +314,7 @@ ENDIF (EXISTS ${METIS_LIB}) # SuiteSparseQR may be compiled with Intel Threading Building Blocks. SET(TBB_FOUND TRUE) -FIND_LIBRARY(TBB_LIB NAMES tbb PATHS ${SEARCH_LIBS}) +FIND_LIBRARY(TBB_LIB NAMES tbb) IF (EXISTS ${TBB_LIB}) MESSAGE("-- Found TBB library: ${TBB_LIB}") ELSE (EXISTS ${TBB_LIB}) @@ -290,7 +322,7 @@ ELSE (EXISTS ${TBB_LIB}) SET(TBB_FOUND FALSE) ENDIF (EXISTS ${TBB_LIB}) -FIND_LIBRARY(TBB_MALLOC_LIB NAMES tbbmalloc PATHS ${SEARCH_LIBS}) +FIND_LIBRARY(TBB_MALLOC_LIB NAMES tbbmalloc) IF (EXISTS ${TBB_MALLOC_LIB}) MESSAGE("-- Found TBB Malloc library: ${TBB_MALLOC_LIB}") ELSE (EXISTS ${TBB_MALLOC_LIB}) @@ -298,32 +330,8 @@ ELSE (EXISTS ${TBB_MALLOC_LIB}) SET(TBB_FOUND FALSE) ENDIF (EXISTS ${TBB_MALLOC_LIB}) -SET(BLAS_AND_LAPACK_FOUND TRUE) -IF (APPLE) - # Mac OS X has LAPACK/BLAS bundled in a framework called - # "vecLib". Search for that instead of for the normal "lapack" - # library. - FIND_LIBRARY(LAPACK_LIB NAMES vecLib) -ELSE (APPLE) - FIND_LIBRARY(BLAS_LIB NAMES blas) - IF (EXISTS ${BLAS_LIB}) - MESSAGE("-- Found BLAS library: ${BLAS_LIB}") - ELSE (EXISTS ${BLAS_LIB}) - MESSAGE("-- Did not find BLAS library") - SET(BLAS_AND_LAPACK_FOUND FALSE) - ENDIF (EXISTS ${BLAS_LIB}) - FIND_LIBRARY(LAPACK_LIB NAMES lapack) -ENDIF (APPLE) - -IF (EXISTS ${LAPACK_LIB}) - MESSAGE("-- Found LAPACK library: ${LAPACK_LIB}") -ELSE (EXISTS ${LAPACK_LIB}) - SET(BLAS_AND_LAPACK_FOUND FALSE) - MESSAGE("-- Did not find LAPACK library") -ENDIF (EXISTS ${LAPACK_LIB}) - -# We don't use SET(SUITESPARSE_FOUND ${AMD_FOUND} ...) in order to -# be able to check whether SuiteSparse is available withou expanding +# We don't use SET(SUITESPARSE_FOUND ${AMD_FOUND} ...) in order to be +# able to check whether SuiteSparse is available without expanding # SUITESPARSE_FOUND with ${}. This means further checks could be: # # IF (SUITESPARSE_FOUND) @@ -373,7 +381,7 @@ ENDIF (DEFINED SUITESPARSE) IF ((NOT DEFINED CXSPARSE) OR (DEFINED CXSPARSE AND CXSPARSE)) SET(CXSPARSE_FOUND ON) -FIND_LIBRARY(CXSPARSE_LIB NAMES cxsparse PATHS ${CXSPARSE_SEARCH_LIBS}) +FIND_LIBRARY(CXSPARSE_LIB NAMES cxsparse) IF (EXISTS ${CXSPARSE_LIB}) MESSAGE("-- Found CXSparse library in: ${CXSPARSE_LIB}") ELSE (EXISTS ${CXSPARSE_LIB}) @@ -381,7 +389,7 @@ ELSE (EXISTS ${CXSPARSE_LIB}) SET(CXSPARSE_FOUND FALSE) ENDIF (EXISTS ${CXSPARSE_LIB}) -FIND_PATH(CXSPARSE_INCLUDE NAMES cs.h PATHS ${CXSPARSE_SEARCH_HEADERS}) +FIND_PATH(CXSPARSE_INCLUDE NAMES cs.h) IF (EXISTS ${CXSPARSE_INCLUDE}) MESSAGE("-- Found CXSparse header in: ${CXSPARSE_INCLUDE}") ELSE (EXISTS ${CXSPARSE_INCLUDE}) @@ -409,20 +417,15 @@ ELSE (DEFINED CXSPARSE) ENDIF (CXSPARSE_FOUND) ENDIF (DEFINED CXSPARSE) -# Google Flags -OPTION(GFLAGS - "Enable Google Flags." - ON) - IF (GFLAGS) - FIND_LIBRARY(GFLAGS_LIB NAMES gflags PATHS ${SEARCH_LIBS}) + FIND_LIBRARY(GFLAGS_LIB NAMES gflags) IF (NOT EXISTS ${GFLAGS_LIB}) MESSAGE(FATAL_ERROR "Can't find Google Flags. Please specify: " "-DGFLAGS_LIB=...") ENDIF (NOT EXISTS ${GFLAGS_LIB}) MESSAGE("-- Found Google Flags library: ${GFLAGS_LIB}") - FIND_PATH(GFLAGS_INCLUDE NAMES gflags/gflags.h PATHS ${SEARCH_HEADERS}) + FIND_PATH(GFLAGS_INCLUDE NAMES gflags/gflags.h) IF (NOT EXISTS ${GFLAGS_INCLUDE}) MESSAGE(FATAL_ERROR "Can't find Google Flags. Please specify: " @@ -434,77 +437,44 @@ ELSE (GFLAGS) ADD_DEFINITIONS(-DCERES_NO_GFLAGS) ENDIF (GFLAGS) -# Google Logging -IF (NOT BUILD_ANDROID) - FIND_LIBRARY(GLOG_LIB NAMES glog PATHS ${SEARCH_LIBS}) - IF (NOT EXISTS ${GLOG_LIB}) - MESSAGE(FATAL_ERROR - "Can't find Google Log. Please specify: " - "-DGLOG_LIB=...") - ENDIF (NOT EXISTS ${GLOG_LIB}) - MESSAGE("-- Found Google Log library: ${GLOG_LIB}") - - FIND_PATH(GLOG_INCLUDE NAMES glog/logging.h PATHS ${SEARCH_HEADERS}) - IF (NOT EXISTS ${GLOG_INCLUDE}) - MESSAGE(FATAL_ERROR - "Can't find Google Log. Please specify: " - "-DGLOG_INCLUDE=...") - ENDIF (NOT EXISTS ${GLOG_INCLUDE}) - MESSAGE("-- Found Google Log header in: ${GLOG_INCLUDE}") -ELSE (NOT BUILD_ANDROID) +IF (MINIGLOG) SET(GLOG_LIB miniglog) - MESSAGE("-- Using minimal Glog substitute for Android (library): ${GLOG_LIB}") + MESSAGE("-- Using minimal Glog substitute (library): ${GLOG_LIB}") SET(GLOG_INCLUDE internal/ceres/miniglog) - MESSAGE("-- Using minimal Glog substitute for Android (include): ${GLOG_INCLUDE}") -ENDIF (NOT BUILD_ANDROID) - -# Eigen -FIND_PATH(EIGEN_INCLUDE NAMES Eigen/Core PATHS ${EIGEN_SEARCH_HEADERS}) -IF (NOT EXISTS ${EIGEN_INCLUDE}) - MESSAGE(FATAL_ERROR "Can't find Eigen. Try passing -DEIGEN_INCLUDE=...") -ELSE (NOT EXISTS ${EIGEN_INCLUDE}) - MESSAGE("-- Found Eigen 3.x: ${EIGEN_INCLUDE}") -ENDIF (NOT EXISTS ${EIGEN_INCLUDE}) + MESSAGE("-- Using minimal Glog substitute (include): ${GLOG_INCLUDE}") +ELSE (MINIGLOG) + FIND_LIBRARY(GLOG_LIB NAMES glog) + IF (EXISTS ${GLOG_LIB}) + MESSAGE("-- Found Google Log library: ${GLOG_LIB}") + ELSE (EXISTS ${GLOG_LIB}) + MESSAGE(FATAL_ERROR + "Can't find Google Log. Please specify: -DGLOG_LIB=...") + ENDIF (EXISTS ${GLOG_LIB}) -# 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) + FIND_PATH(GLOG_INCLUDE NAMES glog/logging.h) + IF (EXISTS ${GLOG_INCLUDE}) + MESSAGE("-- Found Google Log header in: ${GLOG_INCLUDE}") + ELSE (EXISTS ${GLOG_INCLUDE}) + MESSAGE(FATAL_ERROR + "Can't find Google Log. Please specify: -DGLOG_INCLUDE=...") + ENDIF (EXISTS ${GLOG_INCLUDE}) +ENDIF (MINIGLOG) IF (NOT SCHUR_SPECIALIZATIONS) ADD_DEFINITIONS(-DCERES_RESTRICT_SCHUR_SPECIALIZATION) MESSAGE("-- Disabling Schur specializations (faster compiles)") ENDIF (NOT SCHUR_SPECIALIZATIONS) -# Line search minimizer is useful for large scale problems or when -# sparse linear algebra libraries are not available. If compile time, -# binary size or compiler performance is an issue, consider disabling -# this. -OPTION(LINE_SEARCH_MINIMIZER - "Enable the line search minimizer." - ON) - IF (NOT LINE_SEARCH_MINIMIZER) ADD_DEFINITIONS(-DCERES_NO_LINE_SEARCH_MINIMIZER) MESSAGE("-- Disabling line search minimizer") ENDIF (NOT LINE_SEARCH_MINIMIZER) -OPTION(CUSTOM_BLAS - "Use handcoded BLAS routines (usually faster) instead of Eigen." - ON) - IF (NOT CUSTOM_BLAS) ADD_DEFINITIONS(-DCERES_NO_CUSTOM_BLAS) MESSAGE("-- Disabling custom blas") ENDIF (NOT CUSTOM_BLAS) -# Multithreading using OpenMP -OPTION(OPENMP - "Enable threaded solving in Ceres (requires OpenMP)" - ON) - IF (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") SET(OPENMP_FOUND FALSE) ELSE (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") @@ -533,17 +503,6 @@ ELSE (OPENMP_FOUND) ADD_DEFINITIONS(-DCERES_NO_THREADS) ENDIF (OPENMP_FOUND) -# Disable threads in mutex.h. Someday, after there is OpenMP support in -# Android, this can get removed. Also turn on a workaround for an NDK bug. -IF (BUILD_ANDROID) - ADD_DEFINITIONS(-DCERES_NO_THREADS) - ADD_DEFINITIONS(-DCERES_WORK_AROUND_ANDROID_NDK_COMPILER_BUG) -ENDIF (BUILD_ANDROID) - -OPTION(DISABLE_TR1 - "Don't use TR1. This replaces some hash tables with sets. Slower." - OFF) - IF (DISABLE_TR1) MESSAGE("-- Replacing unordered_map/set with map/set (warning: slower!)") ADD_DEFINITIONS(-DCERES_NO_TR1) @@ -637,19 +596,20 @@ SET (CERES_CXX_FLAGS) IF (CMAKE_BUILD_TYPE STREQUAL "Release") IF (CMAKE_COMPILER_IS_GNUCXX) - IF (BUILD_ANDROID) - # TODO(keir): Figure out what flags should go here to make an optimized - # native ARM binary for Android. - ELSE (BUILD_ANDROID) - # Linux - IF (CMAKE_SYSTEM_NAME MATCHES "Linux") - SET (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -march=native -mtune=native") - ENDIF (CMAKE_SYSTEM_NAME MATCHES "Linux") - # Mac OS X - IF (CMAKE_SYSTEM_NAME MATCHES "Darwin") - SET (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -fast -msse3") - ENDIF (CMAKE_SYSTEM_NAME MATCHES "Darwin") - ENDIF (BUILD_ANDROID) + # Linux + IF (CMAKE_SYSTEM_NAME MATCHES "Linux") + SET (CERES_CXX_FLAGS "${CERES_CXX_FLAGS} -march=native -mtune=native") + 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} -dumpversion OUTPUT_VARIABLE GCC_VERSION) + 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) IF (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") # Use of -O4 requires use of gold linker & LLVM-gold plugin, which might @@ -717,10 +677,6 @@ ENDIF () ADD_SUBDIRECTORY(internal/ceres) -OPTION(BUILD_DOCUMENTATION - "Build User's Guide (html)" - OFF) - IF (BUILD_DOCUMENTATION) MESSAGE("-- Documentation building is enabled") @@ -732,8 +688,6 @@ IF (BUILD_DOCUMENTATION) ADD_SUBDIRECTORY(docs) ENDIF (BUILD_DOCUMENTATION) -OPTION(BUILD_EXAMPLES "Build examples" ON) - IF (BUILD_EXAMPLES) MESSAGE("-- Build the examples.") ADD_SUBDIRECTORY(examples) diff --git a/README.google b/README.google index 0bdfe3d..8b8b148 100644 --- a/README.google +++ b/README.google @@ -1,5 +1,5 @@ -URL: https://ceres-solver.googlesource.com/ceres-solver/+/c5bcfc01af37b4f667be075c3c58dc024f3c7f06 -Version: c5bcfc01af37b4f667be075c3c58dc024f3c7f06 +URL: https://ceres-solver.googlesource.com/ceres-solver/+archive/0338f9a8e69582a550ef6d128e447779536d623c.tar.gz +Version: 0338f9a8e69582a550ef6d128e447779536d623c License: New BSD, portions MIT License File: LICENSE @@ -12,4 +12,4 @@ Code : https://ceres-solver.googlesource.com/ceres-solver/ Docs : http://homes.cs.washington.edu/~sagarwal/ceres-solver/ Local modifications: -None +Replaced the implementation of logging.h with the google3 /mobile/base/logging.h diff --git a/cmake/CeresConfig.cmake.in b/cmake/CeresConfig.cmake.in index 8ec5677..d000046 100644 --- a/cmake/CeresConfig.cmake.in +++ b/cmake/CeresConfig.cmake.in @@ -47,4 +47,3 @@ INCLUDE(${currentDir}/depend.cmake) # Set the expected library variable SET(CERES_LIBRARIES ceres) -SET(CERES_LIBRARIES_SHARED ceres_shared) diff --git a/docs/build.tex b/docs/build.tex deleted file mode 100644 index 05bceb4..0000000 --- a/docs/build.tex +++ /dev/null @@ -1,321 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Building Ceres} -\label{chapter:build} -Ceres source code and documentation are hosted at -\url{http://code.google.com/p/ceres-solver/}. - -\section{Dependencies} -Ceres relies on a number of open source libraries, some of which are optional. For details on customizing the build process, please see Section~\ref{sec:custom}. - -\begin{enumerate} -\item{\cmake~\footnote{\url{http://www.cmake.org/}}} is the cross-platform build system used by Ceres. We require that you have a relative recent install of \texttt{cmake} (version 2.8.0 or better). -\item{\eigen~\footnote{\url{http://eigen.tuxfamily.org}}} is used for doing all the low level matrix and - linear algebra operations. - -\item{\glog~\footnote{\url{http://code.google.com/p/google-glog}}} is used for error checking and logging. - - Note: Ceres requires \texttt{glog}\ version 0.3.1 or later. Version 0.3 (which ships with Fedora 16) has a namespace bug which prevents Ceres from building. - -\item{\gflags~\footnote{\url{http://code.google.com/p/gflags}}} is used by the code in - \texttt{examples}. It is also used by some of the tests. Strictly speaking it is not required to build the core library, \textbf{ we do not recommend building Ceres without \texttt{gflags}}. - -\item{\suitesparse~\footnote{\url{http://www.cise.ufl.edu/research/sparse/SuiteSparse/}}} is used for sparse matrix analysis, - ordering and factorization. In particular Ceres uses the - \amd, \colamd\ and \cholmod\ libraries. This is an optional - dependency. - -\item{\texttt{CXSparse}~\footnote{\url{http://www.cise.ufl.edu/research/sparse/CXSparse/}}} is used for sparse matrix analysis, ordering and factorization. While it is similar to \texttt{SuiteSparse} in scope, its performance is a bit worse but is a much simpler library to build and does not have any other dependencies. This is an optional dependency. - -\item{\blas\ and \lapack} are needed by - \suitesparse. We - recommend either - \texttt{GotoBlas2}~\footnote{\url{http://www.tacc.utexas.edu/tacc-projects/gotoblas2}} - or - \texttt{ATLAS}~\footnote{\url{http://math-atlas.sourceforge.net/}}, - both of which ship with \blas\ and \lapack\ routines. - -\item{\texttt{protobuf}~\footnote{\url{http://code.google.com/p/protobuf/}}} is an optional dependency that is used for serializing and deserializing linear least squares problems to disk. This is useful for debugging and testing. Without it, some of the tests will be disabled. -\end{enumerate} - -Currently we support building on Linux and MacOS X. Support for other -platforms is forthcoming. - -\section{Building on Linux} -We will use Ubuntu as our example platform. - -\begin{enumerate} -\item{\cmake} -\begin{minted}{bash} -sudo apt-get install cmake -\end{minted} - -\item{\gflags} can either be installed from source via the \texttt{autoconf} invocation -\begin{minted}{bash} -tar -xvzf gflags-2.0.tar.gz -cd gflags-2.0 -./configure --prefix=/usr/local -make -sudo make install. -\end{minted} -or via the \texttt{deb} or \texttt{rpm} packages available on the \gflags\ website. - -\item{\glog} must be configured to use the previously installed -\gflags, rather than the stripped down version that is bundled with \glog. Assuming you have it installed in \texttt{/usr/local} the following \texttt{autoconf} invocation installs it. -\begin{minted}{bash} -tar -xvzf glog-0.3.2.tar.gz -cd glog-0.3.2 -./configure --with-gflags=/usr/local/ -make -sudo make install -\end{minted} - -\item{\eigen} -\begin{minted}{bash} -sudo apt-get install libeigen3-dev -\end{minted} - -\item{\suitesparse\ and \texttt{CXSparse}} -\begin{minted}{bash} -sudo apt-get install libsuitesparse-dev -\end{minted} -This should automatically bring in the necessary \blas\ and \lapack\ dependencies. By co-incidence on Ubuntu, this also installs \texttt{CXSparse}. - -\item{\texttt{protobuf}} -\begin{minted}{bash} -sudo apt-get install libprotobuf-dev -\end{minted} -\end{enumerate} - - -We are now ready to build and test Ceres. Note that \texttt{cmake} requires the exact path to the \texttt{libglog.a} and \texttt{libgflag.a} - -\begin{minted}{bash} -tar zxf ceres-solver-1.2.1.tar.gz -mkdir ceres-bin -cd ceres-bin -cmake ../ceres-solver-1.2.1 -make -j3 -make test -\end{minted} - -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~\cite{Agarwal10bal}: -\begin{minted}{bash} -bin/simple_bundle_adjuster \ - ../ceres-solver-1.2.1/data/problem-16-22106-pre.txt \ -\end{minted} -This runs Ceres for a maximum of 10 iterations using the \denseschur\ linear solver. The output should look something like this. -\clearpage -\begin{minted}{bash} -0: f: 1.598216e+06 d: 0.00e+00 g: 5.67e+18 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e-04 li: 0 -1: f: 1.116401e+05 d: 1.49e+06 g: 1.42e+18 h: 5.48e+02 rho: 9.50e-01 mu: 3.33e-05 li: 1 -2: f: 4.923547e+04 d: 6.24e+04 g: 8.57e+17 h: 3.21e+02 rho: 6.79e-01 mu: 3.18e-05 li: 1 -3: f: 1.884538e+04 d: 3.04e+04 g: 1.45e+17 h: 1.25e+02 rho: 9.81e-01 mu: 1.06e-05 li: 1 -4: f: 1.807384e+04 d: 7.72e+02 g: 3.88e+16 h: 6.23e+01 rho: 9.57e-01 mu: 3.53e-06 li: 1 -5: f: 1.803397e+04 d: 3.99e+01 g: 1.35e+15 h: 1.16e+01 rho: 9.99e-01 mu: 1.18e-06 li: 1 -6: f: 1.803390e+04 d: 6.16e-02 g: 6.69e+12 h: 7.31e-01 rho: 1.00e+00 mu: 3.93e-07 li: 1 - -Ceres Solver Report -------------------- - Original Reduced -Parameter blocks 22122 22122 -Parameters 66462 66462 -Residual blocks 83718 83718 -Residual 167436 167436 - - Given Used -Linear solver DENSE_SCHUR DENSE_SCHUR -Preconditioner N/A N/A -Threads: 1 1 -Linear Solver Threads: 1 1 - -Cost: -Initial 1.598216e+06 -Final 1.803390e+04 -Change 1.580182e+06 - -Number of iterations: -Successful 6 -Unsuccessful 0 -Total 6 - -Time (in seconds): -Preprocessor 0.000000e+00 -Minimizer 2.000000e+00 -Total 2.000000e+00 -Termination: FUNCTION_TOLERANCE -\end{minted} - -\section{Building on OS X} -On OS X, we recommend using the \texttt{homebrew}~\footnote{\url{http://mxcl.github.com/homebrew/}} package manager. - -\begin{enumerate} -\item{\cmake} -\begin{minted}{bash} -brew install cmake -\end{minted} -\item{\texttt{glog}\ and \texttt{gflags}} - -Installing \texttt{\glog} takes also brings in \texttt{gflags} as a dependency. -\begin{minted}{bash} -brew install glog -\end{minted} -\item{\eigen} -\begin{minted}{bash} -brew install eigen -\end{minted} -\item{\suitesparse\ and \texttt{CXSparse}} -\begin{minted}{bash} -brew install suite-sparse -\end{minted} -\item{\texttt{protobuf}} -\begin{minted}{bash} -brew install protobuf -\end{minted} -\end{enumerate} - -We are now ready to build and test Ceres. -\begin{minted}{bash} -tar zxf ceres-solver-1.2.1.tar.gz -mkdir ceres-bin -cd ceres-bin -cmake ../ceres-solver-1.2.1 -make -j3 -make test -\end{minted} -Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}. - - -\section{Building on Windows with Visual Studio} -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 unavaliability of SuiteSparse and CXSparse. Building is -also more involved since there is no automated way to install the dependencies. - -\begin{enumerate} - \item Make a toplevel directory for deps \& build \& src somewhere: \texttt{ceres/} - \item Get dependencies; unpack them as subdirectories in \texttt{ceres/} - (\texttt{ceres/eigen}, \texttt{ceres/glog}, etc) - \begin{itemize} - \item Eigen 3.1 from eigen.tuxfamily.org (needed on Windows; 3.0.x will not - work). There is no need to build anything; just unpack the source - tarball. - \item Goolge Log. Open up the Visual Studio solution and build it. - \item Goolge Flags. Open up the Visual Studio solution and build it. - \end{itemize} - \item Unpack the Ceres tarball into \texttt{ceres}. For the tarball, you - should get a directory inside \texttt{ceres} similar to - \texttt{ceres-solver-1.3.0}. Alternately, checkout Ceres via git to get - \texttt{ceres-solver.git} inside \texttt{ceres}. - \item Install CMake. - \item Make a dir \texttt{ceres/ceres-bin} (for an out-of-tree build) - \item Run CMake; select the \texttt{ceres-solver-X.Y.Z} or - \texttt{ceres-solver.git} directory for the CMake file. Then select the - \texttt{ceres-bin} for the build dir. - \item Try running "Configure". It won't work. It'll show a bunch of options. - You'll need to set: - \begin{itemize} - \item \texttt{GLOG\_INCLUDE} - \item \texttt{GLOG\_LIB} - \item \texttt{GFLAGS\_LIB} - \item \texttt{GFLAGS\_INCLUDE} - \end{itemize} - to the appropriate place where you unpacked/built them. - \item You may have to tweak some more settings to generate a MSVC project. - After each adjustment, try pressing Configure \& Generate until it - generates successfully. - \item Open the solution and build it in MSVC -\end{enumerate} - -To run the tests, select the \texttt{RUN\_TESTS} target and hit "Build RUN\_TESTS" from the build menu. - -Like the Linux build, you should now be able to run \texttt{bin/simple\_bundle\_adjuster}. - -Notes: -\begin{itemize} -\item The default build is Debug; consider switching it to release mode. -\item Currently \texttt{system\_test} is not working properly. -\item Building Ceres as a DLL is not supported; patches welcome. -\item CMake puts the resulting test binaries in ceres-bin/examples/Debug by - default. -\item The solvers supported on Windows are \texttt{DENSE\_QR}, - \texttt{DENSE\_SCHUR}, \texttt{CGNR}, and \texttt{ITERATIVE\_SCHUR}. -\item We're looking for someone to work with upstream SuiteSparse to port their - build system to something sane like CMake, and get a supported Windows - port. -\end{itemize} - -\section{Building on Android} -\label{sec:android} -Download the Android NDK. Run \texttt{ndk-build} from inside the \texttt{jni} directory. Use the \texttt{libceres.a} that gets created. - -TODO(keir): Expand this section further. - -\section{Compiler Flags to use when building your own applications} -\label{sec:compiler-flags} -TBD - - -\section{Customizing the Build Process} -\label{sec:custom} -It is possible to reduce the libraries needed to build Ceres and -customize the build process by passing appropriate flags to \texttt{cmake}. But unless you really know what you are -doing, we recommend against disabling any of the following flags. - -\begin{enumerate} -\item{\texttt{protobuf}} - - -Protocol Buffers is a big dependency and if you do not care for the tests that depend on it and the logging support it enables, you can turn it off by using -\begin{minted}{bash} --DPROTOBUF=OFF. -\end{minted} - -\item{\suitesparse} - -By default, Ceres will only link to \texttt{SuiteSparse}\ if all its dependencies are present. -To build Ceres without \suitesparse\ use -\begin{minted}{bash} --DSUITESPARSE=OFF. -\end{minted} - This will also disable dependency checking for \lapack\ and \blas. This saves on binary size, but the resulting version of Ceres is not suited -to large scale problems due to the lack of a sparse Cholesky solver. This will reduce Ceres' dependencies down to -\eigen, \gflags\ and \glog. - -\item{\texttt{CXSparse}} - -By default, Ceres will only link to \texttt{CXSparse} if all its dependencies are present. -To build Ceres without \suitesparse\ use -\begin{minted}{bash} --DCXSPARSE=OFF. -\end{minted} - -This saves on binary size, but the resulting version of Ceres is not suited to large scale problems due to the lack of a sparse Cholesky solver. This will reduce Ceres' dependencies down to -\eigen, \gflags\ and \glog. - -\item{\gflags} -To build Ceres without \gflags, use -\begin{minted}{bash} --DGFLAGS=OFF. -\end{minted} -Disabling this flag will prevent some of the example code from building. - -\item{Template Specializations} - - -If you are concerned about binary size/compilation time over some -small (10-20\%) performance gains in the \sparseschur\ solver, you can disable some of the template -specializations by using -\begin{minted}{bash} --DSCHUR_SPECIALIZATIONS=OFF. -\end{minted} - -\item{\texttt{OpenMP}} - - -On certain platforms like Android, multithreading with OpenMP is not supported. OpenMP support can be disabled by using -\begin{minted}{bash} --DOPENMP=OFF. -\end{minted} -\end{enumerate} - diff --git a/docs/bundleadjustment.tex b/docs/bundleadjustment.tex deleted file mode 100644 index ac260a0..0000000 --- a/docs/bundleadjustment.tex +++ /dev/null @@ -1,102 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Bundle Adjustment} -\label{chapter:tutorial:bundleadjustment} -One of the main reasons for writing Ceres was our need to solve large scale bundle adjustment problems~\cite{hartley-zisserman-book-2004,triggs-etal-1999}. - -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 $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 consider the solution of a problem from the BAL~\cite{Agarwal10bal} dataset~\footnote{The code for this example can be found in \texttt{examples/simple\_bundle\_adjuster.cc}.}. - -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 \texttt{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 can are: Three for rotation as a Rodriquez axis-angle vector, three for translation, one for focal length and two for radial distortion. The details of this camera model can be found on Noah -Snavely's Bundler -homepage~\footnote{\url{http://phototour.cs.washington.edu/bundler/}} -and the BAL -homepage~\footnote{\url{http://grail.cs.washington.edu/projects/bal/}}. - - -%\begin{listing}[ht] -\clearpage -\begin{minted}[mathescape]{c++} -struct SnavelyReprojectionError { - SnavelyReprojectionError(double observed_x, double observed_y) - : observed_x(observed_x), observed_y(observed_y) {} - template <typename T> - 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; - } - double observed_x; - double observed_y; -}; -\end{minted} - -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 -our life very simple here. The function \texttt{AngleAxisRotatePoint} and other functions for manipulating rotations can be found in \texttt{include/ceres/rotation.h}. - -Given this functor, the bundle adjustment problem can be constructed as follows: -\begin{minted}{c++} -// 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 = - new ceres::AutoDiffCostFunction<SnavelyReprojectionError, 2, 9, 3>( - new SnavelyReprojectionError( - 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)); -} -\end{minted} -Again note that that the problem construction for bundle adjustment is very similar to the curve fitting example. - -One way to solve this problem is to set \texttt{Solver::Options::linear\_solver\_type} to \texttt{SPARSE\_NORMAL\_CHOLESKY} and call \texttt{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 \texttt{DENSE\_SCHUR}. -\begin{minted}{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"; -\end{minted} - -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 \texttt{examples/bundle\_adjuster.cc}. - diff --git a/docs/ceres-solver.bib b/docs/ceres-solver.bib deleted file mode 100644 index 1bb1996..0000000 --- a/docs/ceres-solver.bib +++ /dev/null @@ -1,264 +0,0 @@ -@article{ruhe-wedin, - title={Algorithms for separable nonlinear least squares problems}, - author={Ruhe, A. and Wedin, P.{\AA}.}, - journal={Siam Review}, - volume={22}, - number={3}, - pages={318--337}, - year={1980}, - publisher={SIAM} -} -@article{golub-pereyra-73, - title={The differentiation of pseudo-inverses and nonlinear least squares problems whose variables separate}, - author={Golub, G.H. and Pereyra, V.}, - journal={SIAM Journal on numerical analysis}, - volume={10}, - number={2}, - pages={413--432}, - year={1973}, - publisher={SIAM} -} - -@inproceedings{wiberg, - title={Computation of principal components when data are missing}, - author={Wiberg, T.}, - booktitle={Proc. Second Symp. Computational Statistics}, - pages={229--236}, - year={1976} -} -@book{conn2000trust, - title={Trust-region methods}, - author={Conn, A.R. and Gould, N.I.M. and Toint, P.L.}, - volume={1}, - year={2000}, - publisher={Society for Industrial Mathematics} -} -@article{byrd1988approximate, - title={Approximate solution of the trust region problem by minimization over two-dimensional subspaces}, - author={Byrd, R.H. and Schnabel, R.B. and Shultz, G.A.}, - journal={Mathematical programming}, - volume={40}, - number={1}, - pages={247--263}, - year={1988}, - publisher={Springer} -} -@article{stigler1981gauss, - title={Gauss and the invention of least squares}, - author={Stigler, S.M.}, - journal={The Annals of Statistics}, - volume={9}, - number={3}, - pages={465--474}, - year={1981}, - publisher={Institute of Mathematical Statistics} -} - -@inproceedings{kushal2012, - title={Visibility Based Preconditioning for Bundle Adjustment}, - author={Kushal, A. and Agarwal, S.}, - booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition}, - year={2012}, -} - -@article{nash1990assessing, - title={Assessing a search direction within a truncated-Newton method}, - author={Nash, S.G. and Sofer, A.}, - journal={Operations Research Letters}, - volume={9}, - number={4}, - pages={219--221}, - year={1990} -} - -@inproceedings{wu2011multicore, - title={Multicore bundle adjustment}, - author={Wu, C. and Agarwal, S. and Curless, B. and Seitz, S.M.}, - booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition}, - pages={3057--3064}, - year={2011}, -} - -@inproceedings{Agarwal10bal, - author = {Agarwal, S. and Snavely, N. and Seitz, S. M. and Szeliski, R.}, - title = {Bundle adjustment in the large}, -booktitle = {Proceedings of the European Conference on Computer Vision}, - year = {2010}, - pages = {29--42}, -} - -@article{li2007miqr, - title={MIQR: A multilevel incomplete QR preconditioner for large sparse least-squares problems}, - author={Li, Na and Saad, Y.}, - journal={SIAM Journal on Matrix Analysis and Applications}, - volume={28}, - number={2}, - pages={524--550}, - year={2007}, - publisher={Society for Industrial and Applied Mathematics} -} - -@article{wright1985inexact, - Author = {Wright, S. J. and Holt, J. N.}, - Journal = {Journal of the Australian Mathematical Society Series B}, - Pages = "387--403", - Title = {{An Inexact Levenberg-Marquardt Method for Large Sparse Nonlinear Least Squares}}, - Volume = 26, - Number = 4, - Year = 1985 -} - -@article{elsner1984note, - Author = {Elsner, L.}, - Journal = {Numer. Math.}, - Number = {1}, - Pages = {127--128}, - Publisher = {Springer}, - Title = {{A note on optimal block-scaling of matrices}}, - Volume = {44}, - Year = {1984}} - -@article{hestenes1952methods, - Author = {Hestenes, M.R. and Stiefel, E.}, - Journal = {Journal of research of the National Bureau of Standards}, - Number = {6}, - Pages = {409--436}, - Title = {{Methods of conjugate gradients for solving linear systems}}, - Volume = {49}, - Year = {1952}} - -@book{mathew2008domain, - Author = {Mathew, T.P.A.}, - Publisher = {Springer Verlag}, - Title = {{Domain decomposition methods for the numerical solution of partial differential equations}}, - Year = {2008}} - -@book{smith2004domain, - Author = {Smith, B.F. and Bjorstad, P.E. and Gropp, W.}, - Publisher = {Cambridge University Press}, - Title = {{Domain decomposition}}, - Year = {2004}} - -@article{demmel1983condition, - Author = {Demmel, J.}, - Journal = {SINUM}, - Number = {3}, - Pages = {599--610}, - Title = {{The condition number of equivalence transformations that block diagonalize matrix pencils}}, - Volume = {20}, - Year = {1983}} - -@article{eisenstat1982optimal, - Author = {Eisenstat, S.C. and Lewis, J.W. and Schultz, M.H.}, - Journal = {Linear Algebra Appl.}, - Pages = {181--186}, - Title = {{Optimal Block Diagonal Scaling of Block 2-Cyclic Matrices.}}, - Volume = {44}, - Year = {1982}} - -@article{mandel1990block, - Author = {Mandel, J.}, - Journal = {Numer. Math.}, - Number = {1}, - Pages = {79--93}, - Publisher = {Springer}, - Title = {{On block diagonal and Schur complement preconditioning}}, - Volume = {58}, - Year = {1990}} - -@book{davis2006direct, - Author = {Davis, T.A.}, - Publisher = {SIAM}, - Title = {{Direct methods for sparse linear systems}}, - Year = {2006}} - -@TechReport{brown-58, - author = {D. C. Brown}, - title = {A solution to the general problem of multiple station analytical stereo triangulation}, - institution = {Patrick Airforce Base}, - year = {1958}, - Tkey = {AFMTC TR 58-8}, - number = {43}, - address = {Florida}, -} - -@book{hartley-zisserman-book-2004, - Author = {Hartley, R.~I. and Zisserman, A.}, - Publisher = {Cambridge University Press}, - Title = {Multiple View Geometry in Computer Vision}, - Year = {2003}} - - -@book{trefethen1997numerical, - Author = {Trefethen, L.N. and Bau, D.}, - Publisher = {SIAM}, - Title = {{Numerical Linear Algebra}}, - Year = {1997}} - -@book{saad2003iterative, - Author = {Saad, Y.}, - Publisher = {SIAM}, - Title = {{Iterative methods for sparse linear systems}}, - Year = {2003}} - - -@book{nocedal2000numerical, - Author = {Nocedal, J. and Wright, S. J.}, - Publisher = {Springer}, - Title = {{Numerical Optimization}}, - Year = {2000}} - -@book{bjorck1996numerical, - Author = {Bj{\"o}rck, A.}, - Publisher = {SIAM}, - Title = {{Numerical methods for least squares problems}}, - Year = {1996}} - -@book{madsen2004methods, - Author = {Madsen, K. and Nielsen, H.B. and Tingleff, O.}, - Title = {{Methods for non-linear least squares problems}}, - Year = {2004}} - - -@article{marquardt1963algorithm, - Author = {Marquardt, D.W.}, - Journal = {J. SIAM}, - Number = {2}, - Pages = {431--441}, - Publisher = {SIAM}, - Title = {{An algorithm for least-squares estimation of nonlinear parameters}}, - Volume = {11}, - Year = {1963}} - -@article{levenberg1944method, - Author = {Levenberg, K.}, - Journal = {Quart. Appl. Math}, - Number = {2}, - Pages = {164--168}, - Title = {{A method for the solution of certain nonlinear problems in least squares}}, - Volume = {2}, - Year = {1944}} - -@article{chen2006acs, - Article = {22}, - Author = {Chen, Y. and Davis, T. A. and Hager, W. W. and Rajamanickam, S.}, - Journal = {TOMS}, - Number = {3}, - Title = {{Algorithm 887: CHOLMOD, Supernodal Sparse {Cholesky} Factorization and Update/Downdate}}, - Volume = {35}, - Year = {2008}} - - -@inproceedings{triggs-etal-1999, - Author = {Triggs, B. and McLauchlan, P. F. and Hartley, R. I. and Fitzgibbon, A. W.}, - Booktitle = {Vision Algorithms}, - Pages = {298-372}, - Title = {{Bundle Adjustment - A Modern Synthesis}}, - Year = {1999}} - - -@article{tennenbaum-director, -Author = {Tennenbaum, J. and Director, B.}, -Title = {{How Gauss Determined the Orbit of Ceres}} -} - diff --git a/docs/ceres-solver.tex b/docs/ceres-solver.tex deleted file mode 100644 index 05cc021..0000000 --- a/docs/ceres-solver.tex +++ /dev/null @@ -1,132 +0,0 @@ -%%% Build instructions -%%% pdflatex -shell-escape ceres && bibtex ceres && pdflatex -shell-escape ceres && pdflatex -shell-escape ceres - -\documentclass[10pt,letterpaper,oneside]{memoir} -\usepackage{fouriernc} -\usepackage[T1]{fontenc} -\usepackage{minted,amsmath,amssymb,amsthm,url,booktabs} -\usepackage[pdftex]{graphicx} -\usepackage[sort&compress]{natbib} -\usepackage[breaklinks=true,letterpaper=true,colorlinks,bookmarks=false]{hyperref} -\usepackage{algorithm} -\usepackage{algorithmic} - -% page dimensions -\addtolength{\textwidth}{1.5in} -\addtolength{\oddsidemargin}{-0.75in} -\addtolength{\evensidemargin}{-0.75in} -\addtolength{\spinemargin}{-0.75in} -\addtolength{\foremargin}{-0.75in} -\setlength{\parindent}{0.0in} -\setlength{\parskip}{0.12in} - -% Our pagestyle -\copypagestyle{ceres}{headings} -\makeevenhead{ceres}{\thepage}{}{\scshape\rightmark} -\makeoddhead{ceres}{\scshape\rightmark}{}{\thepage} - -%% ceres chapter style -\makechapterstyle{ceres}{% -\renewcommand{\chapterheadstart}{}% -\renewcommand{\printchaptername}{}% -\renewcommand{\chapternamenum}{}% -\renewcommand{\printchapternum}{}% -\renewcommand{\afterchapternum}{}% -\renewcommand{\printchaptertitle}[1]{% -\raggedright\Large\scshape\MakeLowercase{##1}}% -\renewcommand{\afterchaptertitle}{% -\vskip\onelineskip \hrule\vskip\onelineskip}% -}% -\renewcommand{\cftchapterfont}{\normalfont}% -\renewcommand{\cftchapterpagefont}{\normalfont}% -\renewcommand{\cftchapterpresnum}{\bfseries}% -\renewcommand{\cftchapterleader}{}% -\renewcommand{\cftchapterafterpnum}{\cftparfillskip}% - - -%% Section title style -\setsecheadstyle{\raggedright\scshape\MakeLowercase}% -\setbeforesecskip{-\onelineskip}% -\setaftersecskip{\onelineskip}% - -%% Subsection title style - -\setsubsecheadstyle{\sethangfrom{\noindent ##1}\raggedright\itshape}% -\setbeforesubsecskip{-\onelineskip}% -\setaftersubsecskip{\onelineskip}% - -\captiontitlefont{\small\sffamily}% -\let\caption\legend - - -\title{\Huge\scshape -\MakeLowercase{Ceres Solver: Tutorial \& Reference} -} -\author{ -\scshape\MakeLowercase{Sameer Agarwal} \\ \texttt{sameeragarwal@google.com} -\and -\scshape\MakeLowercase{Keir Mierle} \\ \texttt{ mierle@gmail.com} -} -\checkandfixthelayout - -\pagestyle{ceres} - -\newcommand{\ceres}{{Ceres }} -\newcommand{\reals}{\mathbb{R} } -\def\eg{\emph{e.g. }} -\def\ie{\emph{i.e. }} -\newcommand{\glog}{\texttt{google-glog}} -\newcommand{\gflags}{\texttt{gflags}} -\newcommand{\eigen}{\texttt{Eigen3}} -\newcommand{\suitesparse}{\texttt{SuiteSparse}} -\newcommand{\cholmod}{\texttt{CHOLMOD}} -\newcommand{\amd}{\texttt{AMD}} -\newcommand{\colamd}{\texttt{COLAMD}} -\newcommand{\lapack}{\texttt{LAPACK}} -\newcommand{\blas}{\texttt{BLAS}} -\newcommand{\denseschur}{\texttt{DENSE\_SCHUR}} -\newcommand{\sparseschur}{\texttt{SPARSE\_SCHUR}} -\newcommand{\iterativeschur}{\texttt{ITERATIVE\_SCHUR}} -\newcommand{\cmake}{\texttt{cmake}} -\newcommand{\protobuf}{\texttt{protobuf}} -\settocdepth{chapter} - -\begin{document} -\chapterstyle{ceres} -\maketitle -\thispagestyle{empty} -\newpage -\pagestyle{ceres} -\tableofcontents -\newpage - -\chapter{A Note to the Reader} -Building this pdf from source requires a relatively recent installation of \texttt{LaTeX}~\footnote{\url{http://www.tug.org/texlive/}}, \texttt{minted.sty}\footnote{\url{http://code.google.com/p/minted/}} and \texttt{pygments}\footnote{\url{http://pygments.org/}}. - -Despite our best efforts, this manual remains a work in progress and the source code for Ceres Solver remains the ultimate reference. -\input{changes} -\input{introduction} -\input{license} -\input{build} - -%% Tutorial -\part{Tutorial} -\label{part:tutorial} -\input{nnlsq} -\input{helloworld} -\input{powell} -\input{curvefitting} -\input{bundleadjustment} - -%% Reference -\part{Reference} -\label{part:reference} -\input{reference-overview} -\input{modeling} -\input{solving} - -\input{faq} -\input{further} -\bibliographystyle{plain} -\bibliography{ceres-solver} -\end{document} diff --git a/docs/ceres.bib b/docs/ceres.bib deleted file mode 100644 index b26a984..0000000 --- a/docs/ceres.bib +++ /dev/null @@ -1,219 +0,0 @@ -@article{stigler1981gauss, - title={Gauss and the invention of least squares}, - author={Stigler, S.M.}, - journal={The Annals of Statistics}, - volume={9}, - number={3}, - pages={465--474}, - year={1981}, - publisher={Institute of Mathematical Statistics} -} - -@inproceedings{kushal2012, - title={Visibility Based Preconditioning for Bundle Adjustment}, - author={Kushal, A. and Agarwal, S.}, - booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition}, - year={2012}, -} - -@article{nash1990assessing, - title={Assessing a search direction within a truncated-Newton method}, - author={Nash, S.G. and Sofer, A.}, - journal={Operations Research Letters}, - volume={9}, - number={4}, - pages={219--221}, - year={1990} -} - -@inproceedings{wu2011multicore, - title={Multicore bundle adjustment}, - author={Wu, C. and Agarwal, S. and Curless, B. and Seitz, S.M.}, - booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition}, - pages={3057--3064}, - year={2011}, -} - -@inproceedings{Agarwal10bal, - author = {Agarwal, S. and Snavely, N. and Seitz, S. M. and Szeliski, R.}, - title = {Bundle adjustment in the large}, -booktitle = {Proceedings of the European Conference on Computer Vision}, - year = {2010}, - pages = {29--42}, -} - -@article{li2007miqr, - title={MIQR: A multilevel incomplete QR preconditioner for large sparse least-squares problems}, - author={Li, Na and Saad, Y.}, - journal={SIAM Journal on Matrix Analysis and Applications}, - volume={28}, - number={2}, - pages={524--550}, - year={2007}, - publisher={Society for Industrial and Applied Mathematics} -} - -@article{wright1985inexact, - Author = {Wright, S. J. and Holt, J. N.}, - Journal = {Journal of the Australian Mathematical Society Series B}, - Pages = "387--403", - Title = {{An Inexact Levenberg-Marquardt Method for Large Sparse Nonlinear Least Squares}}, - Volume = 26, - Number = 4, - Year = 1985 -} - -@article{elsner1984note, - Author = {Elsner, L.}, - Journal = {Numer. Math.}, - Number = {1}, - Pages = {127--128}, - Publisher = {Springer}, - Title = {{A note on optimal block-scaling of matrices}}, - Volume = {44}, - Year = {1984}} - -@article{hestenes1952methods, - Author = {Hestenes, M.R. and Stiefel, E.}, - Journal = {Journal of research of the National Bureau of Standards}, - Number = {6}, - Pages = {409--436}, - Title = {{Methods of conjugate gradients for solving linear systems}}, - Volume = {49}, - Year = {1952}} - -@book{mathew2008domain, - Author = {Mathew, T.P.A.}, - Publisher = {Springer Verlag}, - Title = {{Domain decomposition methods for the numerical solution of partial differential equations}}, - Year = {2008}} - -@book{smith2004domain, - Author = {Smith, B.F. and Bjorstad, P.E. and Gropp, W.}, - Publisher = {Cambridge University Press}, - Title = {{Domain decomposition}}, - Year = {2004}} - -@article{demmel1983condition, - Author = {Demmel, J.}, - Journal = {SINUM}, - Number = {3}, - Pages = {599--610}, - Title = {{The condition number of equivalence transformations that block diagonalize matrix pencils}}, - Volume = {20}, - Year = {1983}} - -@article{eisenstat1982optimal, - Author = {Eisenstat, S.C. and Lewis, J.W. and Schultz, M.H.}, - Journal = {Linear Algebra Appl.}, - Pages = {181--186}, - Title = {{Optimal Block Diagonal Scaling of Block 2-Cyclic Matrices.}}, - Volume = {44}, - Year = {1982}} - -@article{mandel1990block, - Author = {Mandel, J.}, - Journal = {Numer. Math.}, - Number = {1}, - Pages = {79--93}, - Publisher = {Springer}, - Title = {{On block diagonal and Schur complement preconditioning}}, - Volume = {58}, - Year = {1990}} - -@book{davis2006direct, - Author = {Davis, T.A.}, - Publisher = {SIAM}, - Title = {{Direct methods for sparse linear systems}}, - Year = {2006}} - -@TechReport{brown-58, - author = {D. C. Brown}, - title = {A solution to the general problem of multiple station analytical stereo triangulation}, - institution = {Patrick Airforce Base}, - year = {1958}, - Tkey = {AFMTC TR 58-8}, - number = {43}, - address = {Florida}, -} - -@book{hartley-zisserman-book-2004, - Author = {Hartley, R.~I. and Zisserman, A.}, - Publisher = {Cambridge University Press}, - Title = {Multiple View Geometry in Computer Vision}, - Year = {2003}} - - -@book{trefethen1997numerical, - Author = {Trefethen, L.N. and Bau, D.}, - Publisher = {SIAM}, - Title = {{Numerical Linear Algebra}}, - Year = {1997}} - -@book{saad2003iterative, - Author = {Saad, Y.}, - Publisher = {SIAM}, - Title = {{Iterative methods for sparse linear systems}}, - Year = {2003}} - - -@book{nocedal2000numerical, - Author = {Nocedal, J. and Wright, S. J.}, - Publisher = {Springer}, - Title = {{Numerical Optimization}}, - Year = {2000}} - -@book{bjorck1996numerical, - Author = {Bj{\"o}rck, A.}, - Publisher = {SIAM}, - Title = {{Numerical methods for least squares problems}}, - Year = {1996}} - -@book{madsen2004methods, - Author = {Madsen, K. and Nielsen, H.B. and Tingleff, O.}, - Title = {{Methods for non-linear least squares problems}}, - Year = {2004}} - - -@article{marquardt1963algorithm, - Author = {Marquardt, D.W.}, - Journal = {J. SIAM}, - Number = {2}, - Pages = {431--441}, - Publisher = {SIAM}, - Title = {{An algorithm for least-squares estimation of nonlinear parameters}}, - Volume = {11}, - Year = {1963}} - -@article{levenberg1944method, - Author = {Levenberg, K.}, - Journal = {Quart. Appl. Math}, - Number = {2}, - Pages = {164--168}, - Title = {{A method for the solution of certain nonlinear problems in least squares}}, - Volume = {2}, - Year = {1944}} - -@article{chen2006acs, - Article = {22}, - Author = {Chen, Y. and Davis, T. A. and Hager, W. W. and Rajamanickam, S.}, - Journal = {TOMS}, - Number = {3}, - Title = {{Algorithm 887: CHOLMOD, Supernodal Sparse {Cholesky} Factorization and Update/Downdate}}, - Volume = {35}, - Year = {2008}} - - -@inproceedings{triggs-etal-1999, - Author = {Triggs, B. and McLauchlan, P. F. and Hartley, R. I. and Fitzgibbon, A. W.}, - Booktitle = {Vision Algorithms}, - Pages = {298-372}, - Title = {{Bundle Adjustment - A Modern Synthesis}}, - Year = {1999}} - - -@article{tennenbaum-director, -Author = {Tennenbaum, J. and Director, B.}, -Title = {{How Gauss Determined the Orbit of Ceres}} -} - diff --git a/docs/changes.tex b/docs/changes.tex deleted file mode 100644 index 72f7950..0000000 --- a/docs/changes.tex +++ /dev/null @@ -1,266 +0,0 @@ -%!TEX root = ceres-solver.tex - -\chapter{Version History} -\section*{1.5.0} -\subsection{New Features} -\begin{itemize} -\item 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. -\item Speedup the robust loss function correction logic when residual is one dimensional. -\item Changed \texttt{NumericDiffCostFunction} to take functors like \texttt{AutoDiffCostFunction}. -\item Added support for mixing automatic, analytic and numeric differentiation. This is done by adding \texttt{CostFunctionToFunctor} and \texttt{NumericDiffFunctor} objects. -\end{itemize} - -\subsection{Bug Fixes} -\begin{itemize} -\item Fixed varidic evaluation bug in \texttt{AutoDiff}. -\item Fixed \texttt{SolverImpl} tests. -\item Fixed a bug in \texttt{DenseSparseMatrix::ToDenseMatrix()}. -\item Fixed an initialization bug in \texttt{ProgramEvaluator}. -\end{itemize} - -\section*{1.4.0} -\subsection{API Changes} -The new ordering API breaks existing code. Here the common case fixes. -\subsubsection{Before} -\begin{minted}[mathescape]{c++} -options.linear_solver_type = ceres::DENSE_SCHUR -options.ordering_type = ceres::SCHUR -\end{minted} -\subsubsection{After} -\begin{minted}[mathescape]{c++} -options.linear_solver_type = ceres::DENSE_SCHUR -\end{minted} -\subsubsection{Before} -\begin{minted}[mathescape]{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; -\end{minted} -\subsubsection{After} -\begin{minted}[mathescape]{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); -} -\end{minted} -\subsection{New Features} -\begin{itemize} -\item A new richer, more expressive and consistent API for ordering - parameter blocks. -\item 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. -\item An image denoising example using fields of experts. (Petter - Strandmark) -\item Defines for Ceres version and ABI version. -\item Higher precision timer code where available. (Petter Strandmark) -\item Example Makefile for users of Ceres. -\item IterationSummary now informs the user when the step is a - non-monotonic step. -\item Fewer memory allocations when using \texttt{DenseQRSolver}. -\item GradientChecker for testing CostFunctions (William Rucklidge) -\item Add support for cost functions with 10 parameter blocks in - Problem. (Fisher) -\item Add support for 10 parameter blocks in AutoDiffCostFunction. -\end{itemize} - -\subsection{Bug Fixes} -\begin{itemize} -\item static cast to force Eigen::Index to long conversion -\item Change LOG(ERROR) to LOG(WARNING) in \texttt{schur\_complement\_solver.cc}. -\item Remove verbose logging from \texttt{DenseQRSolve}. -\item Fix the Android NDK build. -\item Better handling of empty and constant Problems. -\item Remove an internal header that was leaking into the public API. -\item Memory leak in \texttt{trust\_region\_minimizer.cc} -\item Schur ordering was operating on the wrong object (Ricardo Martin) -\item MSVC fixes (Petter Strandmark) -\item Various fixes to \texttt{nist.cc} (Markus Moll) -\item Fixed a jacobian scaling bug. -\item Numerically robust computation of \texttt{model\_cost\_change}. -\item Signed comparison compiler warning fixes (Ricardo Martin) -\item Various compiler warning fixes all over. -\item Inclusion guard fixes (Petter Strandmark) -\item Segfault in test code (Sergey Popov) -\item Replaced EXPECT/ASSERT\_DEATH with the more portable - EXPECT\_DEATH\_IF\_SUPPORTED macros. -\item Fixed the camera projection model in Ceres' implementation of - Snavely's camera model. (Ricardo Martin) -\end{itemize} - - -\section*{1.3.0} -\subsection{New Features} -\begin{itemize} -\item Android Port (Scott Ettinger also contributed to the port) -\item Windows port. (Changchang Wu and Pierre Moulon also contributed to the port) -\item New subspace Dogleg Solver. (Markus Moll) -\item Trust region algorithm now supports the option of non-monotonic steps. -\item New loss functions \texttt{ArcTanLossFunction, - TolerantLossFunction} and \texttt{ComposedLossFunction}. (James Roseborough). -\item New \texttt{DENSE\_NORMAL\_CHOLESKY} linear solver, which uses Eigen's - LDLT factorization on the normal equations. -\item Cached symbolic factorization when using \texttt{CXSparse}. - (Petter Strandark) -\item New example \texttt{nist.cc} and data from the NIST non-linear - regression test suite. (Thanks to Douglas Bates for suggesting this.) -\item The traditional Dogleg solver now uses an elliptical trust - region (Markus Moll) -\item Support for returning initial and final gradients \& Jacobians. -\item Gradient computation support in the evaluators, with an eye - towards developing first order/gradient based solvers. -\item A better way to compute \texttt{Solver::Summary::fixed\_cost}. (Markus Moll) -\item \texttt{CMake} support for building documentation, separate examples, - installing and uninstalling the library and Gerrit hooks (Arnaud - Gelas) -\item \texttt{SuiteSparse4} support (Markus Moll) -\item Support for building Ceres without \texttt{TR1} (This leads to - slightly slower \texttt{DENSE\_SCHUR} and \texttt{SPARSE\_SCHUR} solvers). -\item \texttt{BALProblem} can now write a problem back to disk. -\item \texttt{bundle\_adjuster} now allows the user to normalize and perturb the - problem before solving. -\item Solver progress logging to file. -\item Added \texttt{Program::ToString} and - \texttt{ParameterBlock::ToString} to help with debugging. -\item Ability to build Ceres as a shared library (MacOS and Linux only), associated versioning and build release script changes. -\item Portable floating point classification API. -\end{itemize} - -\subsection{Bug Fixes} -\begin{itemize} -\item Fix how invalid step evaluations are handled. -\item Change the slop handling around zero for model cost changes to use -relative tolerances rather than absolute tolerances. -\item Fix an inadvertant integer to bool conversion. (Petter Strandmark) -\item Do not link to \texttt{libgomp} when building on - windows. (Petter Strandmark) -\item Include \texttt{gflags.h} in \texttt{test\_utils.cc}. (Petter - Strandmark) -\item Use standard random number generation routines. (Petter Strandmark) -\item \texttt{TrustRegionMinimizer} does not implicitly negate the - steps that it takes. (Markus Moll) -\item Diagonal scaling allows for equal upper and lower bounds. (Markus Moll) -\item TrustRegionStrategy does not misuse LinearSolver:Summary anymore. -\item Fix Eigen3 Row/Column Major storage issue. (Lena Gieseke) -\item QuaternionToAngleAxis now guarantees an angle in $[-\pi, \pi]$. (Guoxuan Zhang) -\item Added a workaround for a compiler bug in the Android NDK to the - Schur eliminator. -\item The sparse linear algebra library is only logged in - Summary::FullReport if it is used. -\item Rename the macro \texttt{CERES\_DONT\_HAVE\_PROTOCOL\_BUFFERS} - to \texttt{CERES\_NO\_PROTOCOL\_BUFFERS} for consistency. -\item Fix how static structure detection for the Schur eliminator logs - its results. -\item Correct example code in the documentation. (Petter Strandmark) -\item Fix \texttt{fpclassify.h} to work with the Android NDK and STLport. -\item Fix a memory leak in the \texttt{levenber\_marquardt\_strategy\_test.cc} -\item Fix an early return bug in the Dogleg solver. (Markus Moll) -\item Zero initialize Jets. -\item Moved \texttt{internal/ceres/mock\_log.h} to \texttt{internal/ceres/gmock/mock-log.h} -\item Unified file path handling in tests. -\item \texttt{data\_fitting.cc} includes \texttt{gflags} -\item Renamed Ceres' Mutex class and associated macros to avoid - namespace conflicts. -\item Close the BAL problem file after reading it (Markus Moll) -\item Fix IsInfinite on Jets. -\item Drop alignment requirements for Jets. -\item Fixed Jet to integer comparison. (Keith Leung) -\item Fix use of uninitialized arrays. (Sebastian Koch \& Markus Moll) -\item Conditionally compile gflag dependencies.(Casey Goodlett) -\item Add \texttt{data\_fitting.cc } to the examples \texttt{CMake} file. -\end{itemize} - -\section*{1.2.3} -\subsection{Bug Fixes} -\begin{itemize} -\item \texttt{suitesparse\_test} is enabled even when \texttt{-DSUITESPARSE=OFF}. -\item \texttt{FixedArray} internal struct did not respect \texttt{Eigen} - alignment requirements (Koichi Akabe \& Stephan Kassemeyer). -\item Fixed \texttt{quadratic.cc} documentation and code mismatch - (Nick Lewycky). -\end{itemize} -\section*{1.2.2} -\subsection{Bug Fixes} -\begin{itemize} -\item Fix constant parameter blocks, and other minor fixes (Markus Moll) -\item Fix alignment issues when combining \texttt{Jet} and - \texttt{FixedArray} in automatic differeniation. -\item Remove obsolete \texttt{build\_defs} file. -\end{itemize} -\section*{1.2.1} -\subsection{New Features} -\begin{itemize} -\item Powell's Dogleg solver -\item Documentation now has a brief overview of Trust Region methods and how the Levenberg-Marquardt and Dogleg methods work. -\end{itemize} -\subsection{Bug Fixes} -\begin{itemize} -\item Destructor for \texttt{TrustRegionStrategy} was not virtual (Markus Moll) -\item Invalid \texttt{DCHECK} in \texttt{suitesparse.cc} (Markus Moll) -\item Iteration callbacks were not properly invoked (Luis Alberto Zarrabeiti) -\item Logging level changes in ConjugateGradientsSolver -\item VisibilityBasedPreconditioner setup does not account for skipped camera pairs. This was debugging code. -\item Enable SSE support on MacOS -\item \texttt{system\_test} was taking too long and too much memory (Koichi Akabe) -\end{itemize} -\section*{1.2.0} -\subsection{New Features} -\begin{itemize} -\item \texttt{CXSparse} support. -\item Block oriented fill reducing orderings. This -reduces the factorization time for sparse -\texttt{CHOLMOD} significantly. -\item 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. -\item \texttt{CMake} file restructuring. Builds in \texttt{Release} mode by default, and now has platform specific tuning flags. -\item Re-organized documentation. No new content, but better organization. -\end{itemize} - -\subsection{Bug Fixes} -\begin{itemize} -\item Fixed integer overflow bug in \texttt{block\_random\_access\_sparse\_matrix.cc}. -\item Renamed some macros to prevent name conflicts. -\item Fixed incorrent input to \texttt{StateUpdatingCallback}. -\item Fixes to AutoDiff tests. -\item Various internal cleanups. -\end{itemize} - -\section*{1.1.1} -\subsection{Bug Fixes} -\begin{itemize} -\item Fix a bug in the handling of constant blocks. (Louis Simard) -\item Add an optional lower bound to the Levenberg-Marquardt regularizer to prevent oscillating between well and ill posed linear problems. -\item Some internal refactoring and test fixes. -\end{itemize} -\section{1.1.0} -\subsection{New Features} -\begin{itemize} -\item New iterative linear solver for general sparse problems - \texttt{CGNR} and a block Jacobi preconditioner for it. -\item Changed the semantics of how \texttt{SuiteSparse} dependencies are checked and used. Now \texttt{SuiteSparse} is built by default, only if all of its dependencies are present. -\item Automatic differentiation now supports dynamic number of residuals. -\item Support for writing the linear least squares problems to disk in text format so that they can loaded into \texttt{MATLAB}. -\item Linear solver results are now checked for nan and infinities. -\item Added \texttt{.gitignore} file. -\item A better more robust build system. -\end{itemize} - -\subsection{Bug Fixes} -\begin{itemize} -\item Fixed a strict weak ordering bug in the schur ordering. -\item Grammar and typos in the documents and code comments. -\item Fixed tests which depended on exact equality between floating point values. -\end{itemize} -\section*{1.0.0} -Initial Release. diff --git a/docs/curvefitting.tex b/docs/curvefitting.tex deleted file mode 100644 index c4bacc2..0000000 --- a/docs/curvefitting.tex +++ /dev/null @@ -1,78 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Fitting a Curve to Data} -\label{chapter:tutorial:curvefitting} -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\footnote{The full code and data for this example can be found in -\texttt{examples/data\_fitting.cc}. It contains data generated by sampling the curve $y = e^{0.3x + 0.1}$ and adding Gaussian noise with standard deviation $\sigma = 0.2$.}. Let us fit some data to the curve -\begin{equation} - y = e^{mx + c}. -\end{equation} - -We begin by defining a templated object to evaluate the residual. There will be a residual for each observation. -\begin{minted}[mathescape]{c++} -class ExponentialResidual { - public: - ExponentialResidual(double x, double y) - : x_(x), y_(y) {} - - template <typename T> bool operator()(const T* const m, - const T* const c, - T* residual) const { - // $y - e^{mx + c}$ - residual[0] = T(y_) - exp(m[0] * T(x_) + c[0]); - return true; - } - - private: - // Observations for a sample. - const double x_; - const double y_; -}; -\end{minted} -%\caption{Templated functor to compute the residual for the exponential model fitting problem. Note that one instance of the functor is responsible for computing the residual for one observation.} -%\label{listing:exponentialresidual} -%\end{listing} -Assuming the observations are in a $2n$ sized array called \texttt{data}, the problem construction is a simple matter of creating a \texttt{CostFunction} for every observation. -\clearpage -\begin{minted}{c++} -double m = 0.0; -double c = 0.0; - -Problem problem; -for (int i = 0; i < kNumObservations; ++i) { - problem.AddResidualBlock( - new AutoDiffCostFunction<ExponentialResidual, 1, 1, 1>( - new ExponentialResidual(data[2 * i], data[2 * i + 1])), - NULL, - &m, &c); -} -\end{minted} -Compiling and running \texttt{data\_fitting.cc} gives us -\begin{minted}{bash} - 0: f: 1.211734e+02 d: 0.00e+00 g: 3.61e+02 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e-04 li: 0 - 1: f: 1.211734e+02 d:-2.21e+03 g: 3.61e+02 h: 7.52e-01 rho:-1.87e+01 mu: 2.00e-04 li: 1 - 2: f: 1.211734e+02 d:-2.21e+03 g: 3.61e+02 h: 7.51e-01 rho:-1.86e+01 mu: 8.00e-04 li: 1 - 3: f: 1.211734e+02 d:-2.19e+03 g: 3.61e+02 h: 7.48e-01 rho:-1.85e+01 mu: 6.40e-03 li: 1 - 4: f: 1.211734e+02 d:-2.02e+03 g: 3.61e+02 h: 7.22e-01 rho:-1.70e+01 mu: 1.02e-01 li: 1 - 5: f: 1.211734e+02 d:-7.34e+02 g: 3.61e+02 h: 5.78e-01 rho:-6.32e+00 mu: 3.28e+00 li: 1 - 6: f: 3.306595e+01 d: 8.81e+01 g: 4.10e+02 h: 3.18e-01 rho: 1.37e+00 mu: 1.09e+00 li: 1 - 7: f: 6.426770e+00 d: 2.66e+01 g: 1.81e+02 h: 1.29e-01 rho: 1.10e+00 mu: 3.64e-01 li: 1 - 8: f: 3.344546e+00 d: 3.08e+00 g: 5.51e+01 h: 3.05e-02 rho: 1.03e+00 mu: 1.21e-01 li: 1 - 9: f: 1.987485e+00 d: 1.36e+00 g: 2.33e+01 h: 8.87e-02 rho: 9.94e-01 mu: 4.05e-02 li: 1 -10: f: 1.211585e+00 d: 7.76e-01 g: 8.22e+00 h: 1.05e-01 rho: 9.89e-01 mu: 1.35e-02 li: 1 -11: f: 1.063265e+00 d: 1.48e-01 g: 1.44e+00 h: 6.06e-02 rho: 9.97e-01 mu: 4.49e-03 li: 1 -12: f: 1.056795e+00 d: 6.47e-03 g: 1.18e-01 h: 1.47e-02 rho: 1.00e+00 mu: 1.50e-03 li: 1 -13: f: 1.056751e+00 d: 4.39e-05 g: 3.79e-03 h: 1.28e-03 rho: 1.00e+00 mu: 4.99e-04 li: 1 -Ceres Solver Report: Iterations: 13, Initial cost: 1.211734e+02, \ -Final cost: 1.056751e+00, Termination: FUNCTION_TOLERANCE. -Initial m: 0 c: 0 -Final m: 0.291861 c: 0.131439 -\end{minted} - -\begin{figure}[t] - \begin{center} - \includegraphics[width=\textwidth]{fit.pdf} - \caption{Least squares data fitting to the curve $y = e^{0.3x + 0.1}$. Observations were generated by sampling this curve uniformly in the interval $x=(0,5)$ and adding Gaussian noise with $\sigma = 0.2$.\label{fig:exponential}} -\end{center} -\end{figure} - -Starting from parameter values $m = 0, c=0$ with an initial objective function value of $121.173$ Ceres finds a solution $m= 0.291861, c = 0.131439$ with an objective function value of $1.05675$. These values are a a bit different than the parameters of the original model $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 $m=0.3, c=0.1$, the fit is worse with an objective function value of 1.082425. Figure~\ref{fig:exponential} illustrates the fit. diff --git a/docs/faq.tex b/docs/faq.tex deleted file mode 100644 index 162668a..0000000 --- a/docs/faq.tex +++ /dev/null @@ -1,69 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Frequently Asked Questions} -\label{chapter:faq} -\newcomment{Question} -\newcomment{Answer} -\commentsoff{Question} -\commentsoff{Answer} - -\begin{enumerate} -\item \begin{Question} -Why does Ceres use blocks (ParameterBlocks and ResidualBlocks) ? -\end{Question}\\ \\ -\begin{Answer} -Most non-linear solvers we are aware of, define the problem and residuals in terms of scalars and it is possible to do this with Ceres also. However, it is our experience that in most 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. Same is true for residuals, where it is common to have small vectors of residuals rather than just scalars. There are a number of advantages of using blocks. It saves on indexing information, which for large problems can be substantial. Blocks translate into contiguous storage in memory which is more cache friendly and last but not the least, it allows us to use SIMD/SSE based BLAS routines to significantly speed up various matrix operations. -\end{Answer} - -\item \begin{Question} - What is a good ParameterBlock? -\end{Question}\\ \\ -\begin{Answer} -In most problems there is a natural parameter block structure, as there is a semantic meaning associated with groups of scalars -- mean vector of a distribution, color of a pixel etc. To group two scalar variables, ask yourself if residual blocks will always use these two variables together. If the answer is yes, then the two variables belong to the same parameter block. -\end{Answer} - -\item \begin{Question} - What is a good ResidualBlock? -\end{Question}\\ \\ -\begin{Answer} -While it is often the case that problems have a natural blocking of parameters into parameter blocks, it is not always clear what a good residual block structure is. One rule of thumb for non-linear least squares problems since they often come from data fitting problems is to create one residual block per observation. So if you are solving a Structure from Motion problem, one 2 dimensional residual block per 2d image projection is a good idea. - -The flips side is that sometimes, when modeling the problem it is tempting to group a large number of residuals together into a single residual block as it reduces the number of CostFunctions you have to define. - -For example consider the following residual block of size 18 which depends on four parameter blocks of size 4 each. Shown below is the Jacobian structure of this residual block, the numbers in the columns indicate the size, and the numbers in the rows show a grouping of the matrix that best capture its sparsity structure. \texttt{X} indicates a non-zero block, the rest of the blocks are zero. - -\begin{equation*} -\begin{matrix} - & 4 & 4 & 4 & 4 \\ - 2 & \texttt{X} & \texttt{X} & \texttt{X} & \texttt{X} \\ - 4 & \texttt{X} & & & \\ - 4 & & \texttt{X} & & \\ - 4 & & & \texttt{X} & \\ - 4 & & & & \texttt{X} \\ -\end{matrix} -\end{equation*} - -Notice that out of the 20 cells, only 8 are non-zero, in fact out of the 288 entries only 48 entries are non-zero, thus we are hiding substantial sparsity from the solver, and using up much more memory. It is much better to break this up into 5 residual blocks. One residual block of size 2 that depends on all four parameter block and four residual blocks of size 4 each that depend on one parameter block at a time. -\end{Answer} - -\item \begin{Question} -Can I set part of a parameter block constant? -\end{Question}\\ \\ -\begin{Answer} -Yes, use \texttt{SubsetParameterization} as a local parameterization for the parameter block of interest. See \texttt{local\_parameterization.h} for more details. -\end{Answer} - - -\item \begin{Question} -Can Ceres solve constrained non-linear least squares? -\end{Question}\\ \\ -\begin{Answer} -Not at this time. We have some ideas on how to do this, but we have not had very many requests to justify the effort involved. If you have a problem that requires such a functionality we would like to hear about it as it will help us decide directions for future work. In the meanwhile, if you are interested in solving bounds constrained problems, consider using some of the tricks described by John D'Errico in his fminsearchbnd toolkit~\footnote{\url{http://www.mathworks.com/matlabcentral/fileexchange/8277-fminsearchbnd}}. -\end{Answer} - -\item \begin{Question} -Can Ceres solve problems that cannot be written as robustified non-linear least squares? -\end{Question}\\ \\ -\begin{Answer} -No. Ceres was designed from the grounds up to be a non-linear least squares solver. Currently we have no plans of extending it into a general purpose non-linear solver. -\end{Answer} -\end{enumerate} diff --git a/docs/fit.pdf b/docs/fit.pdf Binary files differdeleted file mode 100644 index 8714f69..0000000 --- a/docs/fit.pdf +++ /dev/null diff --git a/docs/further.tex b/docs/further.tex deleted file mode 100644 index 67f8227..0000000 --- a/docs/further.tex +++ /dev/null @@ -1,4 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Further Reading} -\label{chapter:further} - For a short but informative introduction to the subject we recommend the booklet by Madsel et al.~\cite{madsen2004methods}. For a general introduction to non-linear optimization we recommend the text by Nocedal \& Wright~\cite{nocedal2000numerical}. Bj{\"o}rck's book remains the seminal reference on least squares problems~\cite{bjorck1996numerical}. Trefethen \& Bau's book is our favourite text on introductory numerical linear algebra~\cite{trefethen1997numerical}. Triggs et al., provide a thorough coverage of the bundle adjustment problem~\cite{triggs-etal-1999}. diff --git a/docs/helloworld.tex b/docs/helloworld.tex deleted file mode 100644 index 938ecba..0000000 --- a/docs/helloworld.tex +++ /dev/null @@ -1,71 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Hello World!} -\label{chapter:tutorial:helloworld} -To get started, let us consider the problem of finding the minimum of the function -\begin{equation} - \frac{1}{2}(10 -x)^2. -\end{equation} -This is a trivial problem, whose minimum is located at $x = 10$, but it is a good place to start to illustrate the basics of solving a problem with Ceres\footnote{Full working code for this and other examples in this manual can be found in the \texttt{examples} directory. Code for this example can be found in \texttt{examples/quadratic.cc}}. - - -Let us write this problem as a non-linear least squares problem by defining the scalar residual function $f_1(x) = 10 - x$. Then $F(x) = [f_1(x)]$ is a residual vector with exactly one component. - -When solving a problem with Ceres, the first thing to do is to define a subclass of \texttt{CostFunction}. It is responsible for computing the value of the residual function and its derivative (also known as the Jacobian) with respect to $x$. -\begin{minted}[mathescape]{c++} -class SimpleCostFunction - : public ceres::SizedCostFunction<1 /* number of residuals */, - 1 /* size of first parameter */> { - public: - virtual ~SimpleCostFunction() {} - virtual bool Evaluate(double const* const* parameters, - double* residuals, - double** jacobians) const { - const double x = parameters[0][0]; - residuals[0] = 10 - x; // $f(x) = 10 - x$ - // Compute the Jacobian if asked for. - if (jacobians != NULL && jacobians[0] != NULL) { - jacobians[0][0] = -1; - } - return true; - } -}; -\end{minted} -\texttt{SimpleCostFunction} is provided with an input array of parameters, an output array for residuals and an optional output array for Jacobians. In our example, there is just one parameter and one residual and this is known at compile time, therefore we can save some code and instead of inheriting from \texttt{CostFunction}, we can instaed inherit from the templated \texttt{SizedCostFunction} class. - - -The \texttt{jacobians} array is optional, \texttt{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. - -Once we have a way of computing the residual vector, it is now time to construct a Non-linear least squares problem using it and have Ceres solve it. -\begin{minted}{c++} -int main(int argc, char** argv) { - double x = 5.0; - ceres::Problem problem; - - // The problem object takes ownership of the newly allocated - // SimpleCostFunction and uses it to optimize the value of x. - problem.AddResidualBlock(new SimpleCostFunction, NULL, &x); - - // Run the solver! - Solver::Options options; - options.max_num_iterations = 10; - 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 : 5.0 -> " << x << "\n"; - return 0; -} -\end{minted} - -Compiling and running this program gives us -\begin{minted}{bash} -0: f: 1.250000e+01 d: 0.00e+00 g: 5.00e+00 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e-04 li: 0 -1: f: 1.249750e-07 d: 1.25e+01 g: 5.00e-04 h: 5.00e+00 rho: 1.00e+00 mu: 3.33e-05 li: 1 -2: f: 1.388518e-16 d: 1.25e-07 g: 1.67e-08 h: 5.00e-04 rho: 1.00e+00 mu: 1.11e-05 li: 1 -Ceres Solver Report: Iterations: 2, Initial cost: 1.250000e+01, \ -Final cost: 1.388518e-16, Termination: PARAMETER_TOLERANCE. -x : 5 -> 10 -\end{minted} - -Starting from a $x=5$, the solver in two iterations goes to 10~\footnote{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.}. 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. diff --git a/docs/introduction.tex b/docs/introduction.tex deleted file mode 100644 index e9b845b..0000000 --- a/docs/introduction.tex +++ /dev/null @@ -1,40 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Introduction} -\label{chapter:introduction} -Ceres Solver\footnote{For brevity, in the rest of this document we will just use the term Ceres.} is a non-linear least squares solver developed at Google. It is designed to solve small and large sparse problems accurately and efficiently~\footnote{For a gentle but brief introduction to non-liner least squares problems, please start by reading the~\hyperref[part:tutorial]{Tutorial}}. Amongst its various features is a simple but expressive API with support for automatic differentiation, robust norms, local parameterizations, automatic gradient checking, multithreading and automatic problem structure detection. - -The key computational cost when solving a non-linear least squares problem is the solution of a linear least squares problem in each iteration. To this end Ceres supports a number of different linear solvers suited for different needs. This includes dense QR factorization (using \eigen) for small scale problems, sparse Cholesky factorization (using \texttt{SuiteSparse}) for general sparse problems and specialized Schur complement based solvers for problems that arise in multi-view geometry~\cite{hartley-zisserman-book-2004}. - -Ceres has been used for solving a variety of problems in computer vision and machine learning at Google with sizes that range from a tens of variables and objective functions with a few hundred terms to problems with millions of variables and objective functions with tens of millions of terms. - - -\section{What's in a name?} -While there is some debate as to who invented of the method of Least Squares~\cite{stigler1981gauss}. There is no debate that it was Carl Friedrich Gauss's prediction of the orbit of the newly discovered asteroid Ceres based on just 41 days of observations that brought it to the attention of the world~\cite{tennenbaum-director}. We named our solver after Ceres to celebrate this seminal event in the history of astronomy, statistics and optimization. - -\section{Contributing to Ceres Solver} - -We welcome contributions to Ceres, whether they are new features, bug fixes or tests. The Ceres mailing list\footnote{\url{http://groups.google.com/group/ceres-solver}} 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 mailinglist 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~\footnote{\url{http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml}} and use \texttt{git} for version control. - -\section{Citing Ceres Solver} -If you use Ceres for an academic publication, please cite this manual. e.g., -\begin{verbatim} -@manual{ceres-manual, - Author = {Sameer Agarwal and Keir Mierle}, - Title = {Ceres Solver: Tutorial \& Reference}, - Organization = {Google Inc.} -} -\end{verbatim} - - -\section{Acknowledgements} -A number of people have helped with the development and open sourcing of Ceres. - -Fredrik Schaffalitzky when he was at Google started the development of Ceres, and even though much has changed since then, many of the ideas from his original design are still present in the current code. - -Amongst Ceres' users at Google two deserve special mention: William Rucklidge and James Roseborough. William was the first user of Ceres. He bravely took on the task of porting production code to an as-yet unproven optimization library, reporting bugs and helping fix them along the way. James is perhaps the most sophisticated user of Ceres at Google. He has reported and fixed bugs and helped evolve the API for the better. - -Nathan Wiegand contributed the MacOS port. - - diff --git a/docs/license.tex b/docs/license.tex deleted file mode 100644 index 602f6f8..0000000 --- a/docs/license.tex +++ /dev/null @@ -1,35 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{License} -Ceres Solver is licensed under the New BSD license, whose terms are as follows. - -\begin{quotation} - -\noindent -Copyright (c) 2010, 2011, 2012, 2013 Google Inc. All rights reserved. - -\noindent -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: -\begin{enumerate} -\item Redistributions of source code must retain the above copyright notice, - this list of conditions and the following disclaimer. -\item Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. -\item Neither the name of Google Inc., nor the names of its contributors may - be used to endorse or promote products derived from this software without - specific prior written permission. -\end{enumerate} - -\noindent -This software is provided by the copyright holders and contributors "AS IS" and -any express or implied warranties, including, but not limited to, the implied -warranties of merchantability and fitness for a particular purpose are -disclaimed. In no event shall Google Inc. be liable for any direct, indirect, -incidental, special, exemplary, or consequential damages (including, but not -limited to, procurement of substitute goods or services; loss of use, data, or -profits; or business interruption) however caused and on any theory of -liability, whether in contract, strict liability, or tort (including negligence -or otherwise) arising in any way out of the use of this software, even if -advised of the possibility of such damage. -\end{quotation} diff --git a/docs/loss.pdf b/docs/loss.pdf Binary files differdeleted file mode 100644 index c99965e..0000000 --- a/docs/loss.pdf +++ /dev/null diff --git a/docs/modeling.tex b/docs/modeling.tex deleted file mode 100644 index 40fc844..0000000 --- a/docs/modeling.tex +++ /dev/null @@ -1,495 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Modeling} -\label{chapter:api} - -\section{Introduction} -Ceres solves robustified non-linear least squares problems of the form -\begin{equation} -\frac{1}{2}\sum_{i=1} \rho_i\left(\left\|f_i\left(x_{i_1},\hdots,x_{i_k}\right)\right\|^2\right). -\label{eq:ceresproblem} -\end{equation} -The term -$\rho_i\left(\left\|f_i\left(x_{i_1},\hdots,x_{i_k}\right)\right\|^2\right)$ -is known as a Residual Block, where $f_i(\cdot)$ is a cost function -that depends on the parameter blocks $\left[x_{i_1}, \hdots , - x_{i_k}\right]$ and $\rho_i$ is a loss function. 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 -\texttt{ParameterBlock}. Of course a \texttt{ParameterBlock} can just -have a single parameter. - -\section{\texttt{CostFunction}} -\label{sec:costfunction} -Given parameter blocks $\left[x_{i_1}, \hdots , x_{i_k}\right]$, a -\texttt{CostFunction} is responsible for computing -a vector of residuals and if asked a vector of Jacobian matrices, i.e., given $\left[x_{i_1}, \hdots , x_{i_k}\right]$, compute the vector $f_i\left(x_{i_1},\hdots,x_{i_k}\right)$ and the matrices - -\begin{equation} -J_{ij} = \frac{\partial}{\partial x_{i_j}}f_i\left(x_{i_1},\hdots,x_{i_k}\right),\quad \forall j \in \{i_1,\hdots, i_k\} -\end{equation} -\begin{minted}{c++} -class CostFunction { - public: - virtual bool Evaluate(double const* const* parameters, - double* residuals, - double** jacobians) = 0; - const vector<int16>& parameter_block_sizes(); - int num_residuals() const; - - protected: - vector<int16>* mutable_parameter_block_sizes(); - void set_num_residuals(int num_residuals); -}; -\end{minted} - -The signature of the function (number and sizes of input parameter blocks and number of outputs) -is stored in \texttt{parameter\_block\_sizes\_} and \texttt{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 \texttt{Problem::AddResidualBlock}. - -The most important method here is \texttt{Evaluate}. It implements the residual and Jacobian computation. - -\texttt{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\_. - - -\texttt{residuals} is an array of size \texttt{num\_residuals\_}. - - -\texttt{jacobians} is an array of size \texttt{parameter\_block\_sizes\_} containing pointers to storage for Jacobian matrices corresponding to each parameter block. The Jacobian matrices are in the same order as \texttt{parameter\_block\_sizes\_}. \texttt{jacobians[i]} is an array that contains \texttt{num\_residuals\_} $\times$ \texttt{parameter\_block\_sizes\_[i]} elements. Each Jacobian matrix is stored in row-major order, i.e., - -\begin{equation} -\texttt{jacobians[i][r * parameter\_block\_size\_[i] + c]} = -%\frac{\partial}{\partial x_{ic}} f_{r}\left(x_{1},\hdots, x_{k}\right) -\frac{\partial \texttt{residual[r]}}{\partial \texttt{parameters[i][c]}} -\end{equation} - -If \texttt{jacobians} is \texttt{NULL}, then no derivatives are returned; this is the case when computing cost only. If \texttt{jacobians[i]} is \texttt{NULL}, then the Jacobian matrix corresponding to the $i^{\textrm{th}}$ parameter block must not be returned, this is the case when the a parameter block is marked constant. - -\section{\texttt{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), Ceres provides \texttt{SizedCostFunction}, where these values can be specified as template parameters. -\begin{minted}{c++} -template<int kNumResiduals, - int N0 = 0, int N1 = 0, int N2 = 0, int N3 = 0, int N4 = 0, int N5 = 0> -class SizedCostFunction : public CostFunction { - public: - virtual bool Evaluate(double const* const* parameters, - double* residuals, - double** jacobians) = 0; -}; -\end{minted} -In this case the user only needs to implement the \texttt{Evaluate} method. - -\section{\texttt{AutoDiffCostFunction}} -But even defining the \texttt{SizedCostFunction} can be a tedious affair if complicated derivative computations are involved. To this end Ceres provides automatic differentiation. - -To get an auto differentiated cost function, you must define a class with a - templated \texttt{operator()} (a functor) that computes the cost function in terms of - the template parameter \texttt{T}. The autodiff framework substitutes appropriate - \texttt{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-\texttt{const} one) and return true to indicate success. - - For example, consider a scalar error $e = k - x^\top y$, where both $x$ and $y$ are - two-dimensional vector parameters 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^\top 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^\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 -\begin{minted}{c++} -class MyScalarCostFunction { - MyScalarCostFunction(double k): k_(k) {} - template <typename T> - 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_; -}; -\end{minted} - -Note that in the declaration of \texttt{operator()} the input parameters \texttt{x} and \texttt{y} come - first, and are passed as const pointers to arrays of \texttt{T}. If there were three - input parameters, then the third input parameter would come after \texttt{y}. The - output is always the last parameter, and is also a pointer to an array. In - the example above, \texttt{e} is a scalar, so only \texttt{e[0]} is set. - - Then given this class definition, the auto differentiated cost function for - it can be constructed as follows. - -\begin{minted}{c++} -CostFunction* cost_function - = new AutoDiffCostFunction<MyScalarCostFunction, 1, 2, 2>( - new MyScalarCostFunction(1.0)); ^ ^ ^ - | | | - Dimension of residual ------+ | | - Dimension of x ----------------+ | - Dimension of y -------------------+ -\end{minted} - -In this example, there is usually an instance for each measurement of k. - -In the instantiation above, the template parameters following - \texttt{MyScalarCostFunction}, \texttt{<1, 2, 2>} describe the functor as computing a - 1-dimensional output from two arguments, both 2-dimensional. - - The framework can currently accommodate cost functions of up to 6 independent - variables, and there is no limit on the dimensionality of each of them. - - \textbf{WARNING 1} Since the functor will get instantiated with different types for - \texttt{T}, you must convert from other numeric types to \texttt{T} before mixing - computations with other variables of type \texttt{T}. In the example above, this is - seen where instead of using \texttt{k\_} directly, \texttt{k\_} is wrapped with \texttt{T(k\_)}. - - \textbf{WARNING 2} A common beginner's error when first using \texttt{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 {\em every parameter block}. In the - example above, that would be \texttt{<MyScalarCostFunction, 1, 2>}, which is missing - the 2 as the last template argument. - -\subsection{Theory \& Implementation} -TBD - -\section{\texttt{NumericDiffCostFunction}} -To get a numerically differentiated cost function, define a subclass of -\texttt{CostFunction} such that the \texttt{Evaluate} function ignores the jacobian -parameter. The numeric differentiation wrapper will fill in the jacobians array - if necessary by repeatedly calling the \texttt{Evaluate} method 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 \texttt{CostFunction} interface. -\begin{minted}{c++} -template <typename CostFunctionNoJacobian, - NumericDiffMethod method = CENTRAL, int M = 0, - int N0 = 0, int N1 = 0, int N2 = 0, int N3 = 0, int N4 = 0, int N5 = 0> -class NumericDiffCostFunction - : public SizedCostFunction<M, N0, N1, N2, N3, N4, N5> { -}; -\end{minted} - -The numerically differentiated version of a cost function for a cost function -can be constructed as follows: -\begin{minted}{c++} -CostFunction* cost_function - = new NumericDiffCostFunction<MyCostFunction, CENTRAL, 1, 4, 8>( - new MyCostFunction(...), TAKE_OWNERSHIP); -\end{minted} -where \texttt{MyCostFunction} has 1 residual and 2 parameter blocks with sizes 4 and 8 -respectively. Look at the tests for a more detailed example. - -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. - -\section{\texttt{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. - -\begin{minted}{c++} -class LossFunction { - public: - virtual void Evaluate(double s, double out[3]) const = 0; -}; -\end{minted} - -The key method is \texttt{Evaluate}, which given a non-negative scalar \texttt{s}, computes -\begin{align} - \texttt{out} = \begin{bmatrix}\rho(s), & \rho'(s), & \rho''(s)\end{bmatrix} -\end{align} - -Here the convention is that the contribution of a term to the cost function is given by $\frac{1}{2}\rho(s)$, where $s = \|f_i\|^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: -\begin{align} - \rho(0) &= 0\\ - \rho'(0) &= 1\\ - \rho'(s) &< 1 \text{ in the outlier region}\\ - \rho''(s) &< 0 \text{ in the outlier region} -\end{align} -so that they mimic the squared cost for small residuals. - -\subsection{Scaling} -Given one robustifier $\rho(s)$ - one can change the length scale at which robustification takes - place, by adding a scale factor $a > 0$ which gives us $\rho(s,a) = a^2 \rho(s / a^2)$ and the first and second derivatives as $\rho'(s / a^2)$ and $(1 / a^2) \rho''(s / a^2)$ respectively. - - -\begin{figure}[hbt] -\includegraphics[width=\textwidth]{loss.pdf} -\caption{Shape of the various common loss functions.} -\label{fig:loss} -\end{figure} - - -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. - -Here are some common loss functions implemented in Ceres. For simplicity we described their unscaled versions. Figure~\ref{fig:loss} illustrates their shape graphically. - -\begin{align} - \rho(s)&=s \tag{\texttt{NullLoss}}\\ - \rho(s) &= \begin{cases} - s & s \le 1\\ - 2 \sqrt{s} - 1 & s > 1 - \end{cases} \tag{\texttt{HuberLoss}}\\ - \rho(s) &= 2 (\sqrt{1+s} - 1) \tag{\texttt{SoftLOneLoss}}\\ - \rho(s) &= \log(1 + s) \tag{\texttt{CauchyLoss}} -\end{align} - -Ceres includes a number of other loss functions, the descriptions and -documentation for which can be found in \texttt{loss\_function.h}. - -\subsection{Theory \& Implementation} -Let us consider a problem with a single problem and a single parameter -block. -\begin{align} -\min_x \frac{1}{2}\rho(f^2(x)) -\end{align} - -Then, the robustified gradient and the Gauss-Newton Hessian are -\begin{align} - 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) -\end{align} -where the terms involving the second derivatives of $f(x)$ have been ignored. Note that $H(x)$ is indefinite if $\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 $\alpha$ be a root of -\begin{equation} - \frac{1}{2}\alpha^2 - \alpha - \frac{\rho''}{\rho'}\|f(x)\|^2 = 0. -\end{equation} -Then, define the rescaled residual and Jacobian as -\begin{align} - \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) -\end{align} -In the case $2 \rho''\left\|f(x)\right\|^2 + \rho' \lesssim 0$, we limit $\alpha \le 1- \epsilon$ for some small $\epsilon$. For more details see Triggs et al~\cite{triggs-etal-1999}. - -With this simple rescaling, one can use any Jacobian based non-linear least squares algorithm to robustifed non-linear least squares problems. - -\section{\texttt{LocalParameterization}} -Sometimes the parameters $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 $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 $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 $\Delta x$ in the -tangent space at the point on the sphere point and then "move" to -the point $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 -\begin{equation} - x' = \boxplus(x, \Delta x), -\end{equation} -where $x'$ has the same size as $x$, and $\Delta x$ is of size less -than or equal to $x$. The function $\boxplus$, generalizes the -definition of vector addition. Thus it satisfies the identity -\begin{equation} - \boxplus(x, 0) = x,\quad \forall x. -\end{equation} - -Instances of \texttt{LocalParameterization} implement the $\boxplus$ operation and its derivative with respect to $\Delta x$ at $\Delta x = 0$. - -\begin{minted}{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 int GlobalSize() const = 0; - virtual int LocalSize() const = 0; -}; -\end{minted} - -\texttt{GlobalSize} is the dimension of the ambient space in which the parameter block $x$ lives. \texttt{LocalSize} is the size of the tangent space that $\Delta x$ lives in. \texttt{Plus} implements $\boxplus(x,\Delta x)$ and $\texttt{ComputeJacobian}$ computes the Jacobian matrix -\begin{equation} - J = \left . \frac{\partial }{\partial \Delta x} \boxplus(x,\Delta x)\right|_{\Delta x = 0} -\end{equation} -in row major form. - -A trivial version of $\boxplus$ is when delta is of the same size as $x$ -and - -\begin{equation} - \boxplus(x, \Delta x) = x + \Delta x -\end{equation} - -A more interesting case if $x$ is a two dimensional vector, and the -user wishes to hold the first coordinate constant. Then, $\Delta x$ is a -scalar and $\boxplus$ is defined as - -\begin{equation} - \boxplus(x, \Delta x) = x + \left[ \begin{array}{c} 0 \\ 1 - \end{array} \right] \Delta x -\end{equation} - -\texttt{SubsetParameterization} generalizes this construction to hold any part of a parameter block constant. - - -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 $\Delta x$ be a 3 -dimensional vector and define $\boxplus$ to be - -\begin{equation} - \boxplus(x, \Delta x) = -\left[ -\cos(|\Delta x|), \frac{\sin\left(|\Delta x|\right)}{|\Delta x|} \Delta x -\right] * x -\label{eq:quaternion} -\end{equation} -The multiplication between the two 4-vectors on the right hand -side is the standard quaternion product. \texttt{QuaternionParameterization} is an implementation of~\eqref{eq:quaternion}. - -\clearpage - -\section{\texttt{Problem}} -\begin{minted}{c++} -class Problem { - public: - struct Options { - Options(); - Ownership cost_function_ownership; - Ownership loss_function_ownership; - Ownership local_parameterization_ownership; - }; - - Problem(); - explicit Problem(const Options& options); - ~Problem(); - - ResidualBlockId AddResidualBlock(CostFunction* cost_function, - LossFunction* loss_function, - const vector<double*>& parameter_blocks); - - void AddParameterBlock(double* values, int size); - void AddParameterBlock(double* values, - int size, - LocalParameterization* local_parameterization); - - void SetParameterBlockConstant(double* values); - void SetParameterBlockVariable(double* values); - void SetParameterization(double* values, - LocalParameterization* local_parameterization); - - int NumParameterBlocks() const; - int NumParameters() const; - int NumResidualBlocks() const; - int NumResiduals() const; -}; -\end{minted} - -The \texttt{Problem} objects holds the robustified non-linear least squares problem~\eqref{eq:ceresproblem}. To create a least squares problem, use the \texttt{Problem::AddResidualBlock} and \texttt{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: - -\begin{minted}{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); -\end{minted} - - -\texttt{AddResidualBlock} as the name implies, adds a residual block to the problem. It adds a cost function, an optional loss function, and connects the cost function to a set of parameter blocks. - -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 \texttt{parameter\_blocks}. The - program aborts if a mismatch is detected. \texttt{loss\_function} can be - \texttt{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 \texttt{AddParameterBlock}. This causes additional correctness - checking; however, \texttt{AddResidualBlock} implicitly adds the parameter - blocks if they are not present, so calling \texttt{AddParameterBlock} - explicitly is not required. - - - \texttt{Problem} by default takes ownership of the - \texttt{cost\_function} and \texttt{loss\_function pointers}. These objects remain - live for the life of the \texttt{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 \texttt{Options} struct. - - - Note that even though the Problem takes ownership of \texttt{cost\_function} - and \texttt{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 \texttt{cost\_function} or \texttt{loss\_function} pointer only once, - regardless of how many residual blocks refer to them. - -\texttt{AddParameterBlock} explicitly adds a parameter block to the \texttt{Problem}. Optionally it allows the user to associate a 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 behaviour. - -You can set any parameter block to be constant using \texttt{SetParameterBlockConstant} and undo this using \texttt{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. - -\subsubsection{Ownership} - \texttt{Problem} by default takes ownership of the - \texttt{cost\_function}, \texttt{loss\_function} and \\ \texttt{local\_parameterization} pointers. These objects remain - live for the life of the \texttt{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 \texttt{Options} struct. - -Even though \texttt{Problem} takes ownership of these pointers, it does not preclude the user from re-using them in another residual or parameter block. The destructor takes care to call - delete on each pointer only once. diff --git a/docs/nnlsq.tex b/docs/nnlsq.tex deleted file mode 100644 index 02d6b9e..0000000 --- a/docs/nnlsq.tex +++ /dev/null @@ -1,23 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Non-linear Least Squares} -\label{chapter:tutorial:nonlinsq} -Let $x \in \reals^n$ be an $n$-dimensional vector of variables, and -$F(x) = \left[f_1(x); \hdots ; f_k(x)\right]$ be a vector of residuals $f_i(x)$. -The function $f_i(x)$ can be a scalar or a vector valued -function. Then, -\begin{equation} - \arg \min_x \frac{1}{2} \sum_{i=1}^k \|f_i(x)\|^2. -\end{equation} -is a Non-linear least squares problem~\footnote{Ceres can solve a more general version of this problem, but for pedagogical reasons, we will restrict ourselves to this class of problems for now. See section~\ref{chapter:overview} for a full description of the problems that Ceres can solve}. Here $\|\cdot\|$ denotes the Euclidean norm of a vector. - -Such optimization problems arise in almost every area of science and engineering. Whenever there is data to be analyzed, curves to be fitted, there is usually a linear or a non-linear least squares problem lurking in there somewhere. - -Perhaps the simplest example of such a problem is the problem of Ordinary Linear Regression, where given observations $(x_1,y_1),\hdots, (x_k,y_k)$, we wish to find the line $y = mx + c$, that best explains $y$ as a function of $x$. One way to solve this problem is to find the solution to the following optimization problem -\begin{equation} - \arg\min_{m,c} \sum_{i=1}^k (y_i - m x_i - c)^2. -\end{equation} -With a little bit of calculus, this problem can be solved easily by hand. But what if, instead of a line we were interested in a more complicated relationship between $x$ and $y$, say for example $y = e^{mx + c}$. Then the optimization problem becomes -\begin{equation} - \arg\min_{m,c} \sum_{i=1}^k \left(y_i - e^{m x_i + c}\right)^2. -\end{equation} -This is a non-linear regression problem and solving it by hand is much more tedious. Ceres is designed to help you model and solve problems like this easily and efficiently.
\ No newline at end of file diff --git a/docs/powell.tex b/docs/powell.tex deleted file mode 100644 index ad86a42..0000000 --- a/docs/powell.tex +++ /dev/null @@ -1,129 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Powell's Function} -\label{chapter:tutorial:powell} -Consider now a slightly more complicated example -- the minimization of Powell's function. Let $x = \left[x_1, x_2, x_3, x_4 \right]$ and -\begin{align} - f_1(x) &= x_1 + 10*x_2 \\ - f_2(x) &= \sqrt{5} * (x_3 - x_4)\\ - f_3(x) &= (x_2 - 2*x_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} -$F(x)$ is a function of four parameters, and has four residuals. Now, -one way to solve this problem would be to define four -\texttt{CostFunction} objects that compute the residual and Jacobians. \eg the following code shows the implementation for $f_4(x)$. -\begin{minted}[mathescape]{c++} -class F4 : public ceres::SizedCostFunction<1, 4> { - public: - virtual ~F4() {} - virtual bool Evaluate(double const* const* parameters, - double* residuals, - double** jacobians) const { - double x1 = parameters[0][0]; - double x4 = parameters[0][3]; - // $f_4 = \sqrt{10} * (x_1 - x_4)^2$ - residuals[0] = sqrt(10.0) * (x1 - x4) * (x1 - x4) - if (jacobians != NULL) { - jacobians[0][0] = 2.0 * sqrt(10.0) * (x1 - x4); // $\partial_{x_1}f_4(x)$ - jacobians[0][1] = 0.0; // $\partial_{x_2}f_4(x)$ - jacobians[0][2] = 0.0; // $\partial_{x_3}f_4(x)$ - jacobians[0][3] = -2.0 * sqrt(10.0) * (x1 - x4); // $\partial_{x_4}f_4(x)$ - } - return true; - } -}; -\end{minted} - -But this can get painful very quickly, especially for residuals involving complicated multi-variate terms. Ceres provides two ways around this problem. Numeric and automatic symbolic differentiation. - -\section{Automatic Differentiation} -\label{sec:tutorial:autodiff} -With its automatic differentiation support, Ceres allows you to define templated objects/functors that will compute the residual and it takes care of computing the Jacobians as needed and filling the \texttt{jacobians} arrays with them. For example, for $f_4(x)$ we define -\begin{minted}[mathescape]{c++} -class F4 { - public: - template <typename T> bool operator()(const T* const x1, - const T* const x4, - T* residual) const { - // $f_4 = \sqrt{10} * (x_1 - x_4)^2$ - residual[0] = T(sqrt(10.0)) * (x1[0] - x4[0]) * (x1[0] - x4[0]); - return true; - } -}; -\end{minted} - -The important thing to note here is that \texttt{operator()} is a -templated method, which assumes that all its inputs and outputs are of -some type \texttt{T}. The reason for using templates here is because Ceres will call \texttt{F4::operator<T>()}, with $\texttt{T=double}$ when just the residual is needed, and with a special type $T=\texttt{Jet}$ when the Jacobians are needed. - -Note also that the parameters are not packed -into a single array, they are instead passed as separate arguments to -\texttt{operator()}. Similarly we can define classes \texttt{F1,F2} -and \texttt{F4}. Then let us consider the construction and solution of the problem. For brevity we only describe the relevant bits of code~\footnote{The full source code for this example can be found in \texttt{examples/powell.cc}.} -\begin{minted}[mathescape]{c++} -double x1 = 3.0; double x2 = -1.0; double x3 = 0.0; double x4 = 1.0; -// Add residual terms to the problem using the using the autodiff -// wrapper to get the derivatives automatically. -problem.AddResidualBlock( - new ceres::AutoDiffCostFunction<F1, 1, 1, 1>(new F1), NULL, &x1, &x2); -problem.AddResidualBlock( - new ceres::AutoDiffCostFunction<F2, 1, 1, 1>(new F2), NULL, &x3, &x4); -problem.AddResidualBlock( - new ceres::AutoDiffCostFunction<F3, 1, 1, 1>(new F3), NULL, &x2, &x3) -problem.AddResidualBlock( - new ceres::AutoDiffCostFunction<F4, 1, 1, 1>(new F4), NULL, &x1, &x4); -\end{minted} -A few things are worth noting in the code above. First, the object -being added to the \texttt{Problem} is an -\texttt{AutoDiffCostFunction} with \texttt{F1}, \texttt{F2}, \texttt{F3} and \texttt{F4} as template parameters. Second, each \texttt{ResidualBlock} only depends on the two parameters that the corresponding residual object depends on and not on all four parameters. - - -Compiling and running \texttt{powell.cc} gives us: -\begin{minted}{bash} -Initial x1 = 3, x2 = -1, x3 = 0, x4 = 1 - 0: f: 1.075000e+02 d: 0.00e+00 g: 1.55e+02 h: 0.00e+00 rho: 0.00e+00 mu: 1.00e-04 li: 0 - 1: f: 5.036190e+00 d: 1.02e+02 g: 2.00e+01 h: 2.16e+00 rho: 9.53e-01 mu: 3.33e-05 li: 1 - 2: f: 3.148168e-01 d: 4.72e+00 g: 2.50e+00 h: 6.23e-01 rho: 9.37e-01 mu: 1.11e-05 li: 1 - 3: f: 1.967760e-02 d: 2.95e-01 g: 3.13e-01 h: 3.08e-01 rho: 9.37e-01 mu: 3.70e-06 li: 1 - 4: f: 1.229900e-03 d: 1.84e-02 g: 3.91e-02 h: 1.54e-01 rho: 9.37e-01 mu: 1.23e-06 li: 1 - 5: f: 7.687123e-05 d: 1.15e-03 g: 4.89e-03 h: 7.69e-02 rho: 9.37e-01 mu: 4.12e-07 li: 1 - 6: f: 4.804625e-06 d: 7.21e-05 g: 6.11e-04 h: 3.85e-02 rho: 9.37e-01 mu: 1.37e-07 li: 1 - 7: f: 3.003028e-07 d: 4.50e-06 g: 7.64e-05 h: 1.92e-02 rho: 9.37e-01 mu: 4.57e-08 li: 1 - 8: f: 1.877006e-08 d: 2.82e-07 g: 9.54e-06 h: 9.62e-03 rho: 9.37e-01 mu: 1.52e-08 li: 1 - 9: f: 1.173223e-09 d: 1.76e-08 g: 1.19e-06 h: 4.81e-03 rho: 9.37e-01 mu: 5.08e-09 li: 1 - 10: f: 7.333425e-11 d: 1.10e-09 g: 1.49e-07 h: 2.40e-03 rho: 9.37e-01 mu: 1.69e-09 li: 1 - 11: f: 4.584044e-12 d: 6.88e-11 g: 1.86e-08 h: 1.20e-03 rho: 9.37e-01 mu: 5.65e-10 li: 1 -Ceres Solver Report: Iterations: 12, Initial cost: 1.075000e+02, \ -Final cost: 2.865573e-13, Termination: GRADIENT_TOLERANCE. -Final x1 = 0.000583994, x2 = -5.83994e-05, x3 = 9.55401e-05, x4 = 9.55401e-05 -\end{minted} -It is easy to see that the optimal solution to this problem is at $x_1=0, x_2=0, x_3=0, x_4=0$ with an objective function value of $0$. In 10 iterations, Ceres finds a solution with an objective function value of $4\times 10^{-12}$. - -\section{Numeric Differentiation} -In some cases, its not possible to define a templated cost functor. In such a situation, numerical differentiation can be used. The user defines a functor which computes the residual value and construct a \texttt{NumericDiffCostFunction} using it. e.g., for \texttt{F4}, the corresponding functor would be -\begin{minted}[mathescape]{c++} -class F4 { - public: - bool operator()(const double* const x1, - const double* const x4, - double* residual) const { - // $f_4 = \sqrt{10} * (x_1 - x_4)^2$ - residual[0] = sqrt(10.0) * (x1[0] - x4[0]) * (x1[0] - x4[0]); - return true; - } -}; -\end{minted} - -Which can then be wrapped \texttt{NumericDiffCostFunction} and added to the \texttt{Problem} object as follows - -\begin{minted}[mathescape]{c++} -problem.AddResidualBlock( - new ceres::NumericDiffCostFunction<F4, ceres::CENTRAL, 1, 1, 1>(new F4), NULL, &x1, &x4); -\end{minted} - -The construction looks almost identical to the 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. \texttt{examples/quadratic\_numeric\_diff.cc} shows a numerically differentiated implementation of \texttt{examples/quadratic.cc}. - -\textbf{We recommend that if possible, automatic differentiation should be used. The use of -\texttt{C++} templates makes automatic differentiation extremely efficient, -whereas numeric differentiation can be quite expensive, prone to -numeric errors and leads to slower convergence.} diff --git a/docs/reference-overview.tex b/docs/reference-overview.tex deleted file mode 100644 index 23ab82b..0000000 --- a/docs/reference-overview.tex +++ /dev/null @@ -1,18 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Overview} -\label{chapter:overview} - -Solving problems using Ceres consists of two steps. -\begin{description} -\item{\textbf{Modeling}} Constructing an optimization problem by - specifying its parameters and the terms in the objective function. -\item{\textbf{Solving}} Configuring and running the solver. -\end{description} - -The two steps are mostly independent of each other. This is by -design. Modeling the optimization problem should not depend on how the -solver works. The user should be able model the problem once, and then -switch between various solver settings and strategies without touching -the problem. - -In the next two chapters we will consider each of these steps in detail. diff --git a/docs/solving.tex b/docs/solving.tex deleted file mode 100644 index ee8a3b8..0000000 --- a/docs/solving.tex +++ /dev/null @@ -1,767 +0,0 @@ -%!TEX root = ceres-solver.tex -\chapter{Solving} -Effective use of Ceres requires some familiarity with the basic components of a nonlinear least squares solver, so before we describe how to configure the solver, we will begin by taking a brief look at how some of the core optimization algorithms in Ceres work and the various linear solvers and preconditioners that power it. - -\section{Trust Region Methods} -\label{sec:trust-region} -Let $x \in \mathbb{R}^{n}$ be an $n$-dimensional vector of variables, and -$ F(x) = \left[f_1(x), \hdots, f_{m}(x) \right]^{\top}$ be a $m$-dimensional function of $x$. We are interested in solving the following optimization problem~\footnote{At the level of the non-linear solver, the block and residual structure is not relevant, therefore our discussion here is in terms of an optimization problem defined over a state vector of size $n$.}, -\begin{equation} - \arg \min_x \frac{1}{2}\|F(x)\|^2\ . - \label{eq:nonlinsq} -\end{equation} -Here, the Jacobian $J(x)$ of $F(x)$ is an $m\times n$ matrix, where $J_{ij}(x) = \partial_j f_i(x)$ and the gradient vector $g(x) = \nabla \frac{1}{2}\|F(x)\|^2 = J(x)^\top F(x)$. Since the efficient global optimization of~\eqref{eq:nonlinsq} for general $F(x)$ is an intractable problem, we will have to settle for finding a local minimum. - -The general strategy when solving non-linear optimization problems is to solve a sequence of approximations to the original problem~\cite{nocedal2000numerical}. At each iteration, the approximation is solved to determine a correction $\Delta x$ to the vector $x$. For non-linear least squares, an approximation can be constructed by using the linearization $F(x+\Delta x) \approx F(x) + J(x)\Delta x$, which leads to the following linear least squares problem: -\begin{equation} - \min_{\Delta x} \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 - \label{eq:linearapprox} -\end{equation} -Unfortunately, na\"ively solving a sequence of these problems and -updating $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 $\Delta x$. And this is where the idea of a trust-region -comes in. Algorithm~\ref{alg:trust-region} describes the basic trust-region loop for non-linear least squares problems. - -\begin{algorithm} -\caption{The basic trust-region algorithm.\label{alg:trust-region}} -\begin{algorithmic} -\REQUIRE Initial point $x$ and a trust region radius $\mu$. -\LOOP -\STATE{Solve $\arg \min_{\Delta x} \frac{1}{2}\|J(x)\Delta x + F(x)\|^2$ s.t. $\|D(x)\Delta x\|^2 \le \mu$} -\STATE{$\rho = \frac{\displaystyle \|F(x + \Delta x)\|^2 - \|F(x)\|^2}{\displaystyle \|J(x)\Delta x + F(x)\|^2 - \|F(x)\|^2}$} -\IF {$\rho > \epsilon$} -\STATE{$x = x + \Delta x$} -\ENDIF -\IF {$\rho > \eta_1$} -\STATE{$\rho = 2 * \rho$} -\ELSE -\IF {$\rho < \eta_2$} -\STATE {$\rho = 0.5 * \rho$} -\ENDIF -\ENDIF -\ENDLOOP -\end{algorithmic} -\end{algorithm} - -Here, $\mu$ is the trust region radius, $D(x)$ is some matrix used to define a metric on the domain of $F(x)$ and $\rho$ measures the quality of the step $\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 $\rho$. - -The key computational step in a trust-region algorithm is the solution of the constrained optimization problem -\begin{align} - \arg\min_{\Delta x}& \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 \\ - \text{such that}&\quad \|D(x)\Delta x\|^2 \le \mu -\label{eq:trp} -\end{align} - -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. - -\subsection{Levenberg-Marquardt} -The Levenberg-Marquardt algorithm~\cite{levenberg1944method, marquardt1963algorithm} is the most popular algorithm for solving non-linear least squares problems. It was also the first trust region algorithm to be developed~\cite{levenberg1944method,marquardt1963algorithm}. Ceres implements an exact step~\cite{madsen2004methods} and an inexact step variant of the Levenberg-Marquardt algorithm~\cite{wright1985inexact,nash1990assessing}. - -It can be shown, that the solution to~\eqref{eq:trp} can be obtained by solving an unconstrained optimization of the form -\begin{align} - \arg\min_{\Delta x}& \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 +\lambda \|D(x)\Delta x\|^2 -\end{align} -Where, $\lambda$ is a Lagrange multiplier that is inverse related to $\mu$. In Ceres, we solve for -\begin{align} - \arg\min_{\Delta x}& \frac{1}{2}\|J(x)\Delta x + F(x)\|^2 + \frac{1}{\mu} \|D(x)\Delta x\|^2 -\label{eq:lsqr} -\end{align} -The matrix $D(x)$ is a non-negative diagonal matrix, typically the square root of the diagonal of the matrix $J(x)^\top J(x)$. - -Before going further, let us make some notational simplifications. We will assume that the matrix $\sqrt{\mu} D$ has been concatenated at the bottom of the matrix $J$ and similarly a vector of zeros has been added to the bottom of the vector $f$ and the rest of our discussion will be in terms of $J$ and $f$, \ie the linear least squares problem. -\begin{align} - \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + f(x)\|^2 . - \label{eq:simple} -\end{align} -For all but the smallest problems the solution of~\eqref{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~\eqref{eq:simple}. There are two major classes of methods - factorization and iterative. - -The factorization methods are based on computing an exact solution of~\eqref{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~\eqref{eq:lsqr} is necessary at each step of the LM algorithm to solve~\eqref{eq:nonlinsq}. In fact, we have already seen evidence that this may not be the case, as~\eqref{eq:lsqr} is itself a regularized version of~\eqref{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~\cite{nocedal2000numerical}. - -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~\cite{nocedal2000numerical}. Second, a termination rule for the iterative solver. A typical termination rule is of the form -\begin{equation} - \|H(x) \Delta x + g(x)\| \leq \eta_k \|g(x)\|. \label{eq:inexact} -\end{equation} -Here, $k$ indicates the Levenberg-Marquardt iteration number and $0 < \eta_k <1$ is known as the forcing sequence. Wright \& Holt \cite{wright1985inexact} prove that a truncated Levenberg-Marquardt algorithm that uses an inexact Newton step based on~\eqref{eq:inexact} converges for any sequence $\eta_k \leq \eta_0 < 1$ and the rate of convergence depends on the choice of the forcing sequence $\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. - -\subsection{Dogleg} -\label{sec:dogleg} -Another strategy for solving the trust region problem~\eqref{eq:trp} was introduced by M. J. D. Powell. The key idea there is to compute two vectors -\begin{align} - \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). -\end{align} -Note that the vector $\Delta x^{\text{Gauss-Newton}}$ is the solution -to~\eqref{eq:linearapprox} and $\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 $\Delta x$ defined by $\Delta -x^{\text{Gauss-Newton}}$ and $\Delta x^{\text{Cauchy}}$ that solves -the trust region problem. Ceres supports two -variants. - -\texttt{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~\cite{madsen2004methods}. - - \texttt{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\cite{byrd1988approximate}. - -The key advantage of the Dogleg over Levenberg Marquardt is that if the step computation for a particular choice of $\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 $\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 $\mu$. - -The Dogleg method can only be used with the exact factorization based linear solvers. - -\subsection{Inner Iterations} -\label{sec:inner} -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 - -\begin{equation} - y = a_1 e^{b_1 x} + a_2 e^{b_3 x^2 + c_1} -\end{equation} - -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 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$. It's possible to analytically eliminate the variables -$a_1$ and $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~\cite{golub-pereyra-73}. - -Similar structure can be found in the matrix factorization with -missing data problem. There the corresponding algorithm is -known as Wiberg's algorithm~\cite{wiberg}. - -Ruhe \& Wedin present an analysis of -various algorithms for solving separable non-linear least -squares problems and refer to {\em Variable Projection} as -Algorithm I in their paper~\cite{ruhe-wedin}. - -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 $a_1$ and $a_2$ exactly after -computing a successful Newton step. - - -This idea can be generalized to cases where the residual is not -linear in $a_1$ and $a_2$, i.e., - -\begin{equation} - y = f_1(a_1, e^{b_1 x}) + f_2(a_2, e^{b_3 x^2 + c_1}) -\end{equation} - -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 $a_1$ and $a_2$ optimization problems will do. The only constraint -on $a_1$ and $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 $(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 \texttt{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 \texttt{Solver::Options::num\_threads} to the maximum number -possible is highly recommended. - -\subsection{Non-monotonic Steps} -\label{sec:non-monotonic} -Note that the basic trust-region algorithm described in -Algorithm~\ref{alg:trust-region} is a descent algorithm in that they -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 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 \texttt{Solver::Options::use\_nonmonotonic\_steps} to \texttt{true} -enables the non-monotonic trust region algorithm as described by -Conn, Gould \& Toint in~\cite{conn2000trust}. - -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 is available for all trust region -strategies. - -\section{\texttt{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 -\begin{align} - \min_{\Delta x} \frac{1}{2} \|J(x)\Delta x + f(x)\|^2 . - \label{eq:simple2} -\end{align} - - -Let $H(x)= J(x)^\top J(x)$ and $g(x) = -J(x)^\top f(x)$. For notational convenience let us also drop the dependence on $x$. Then it is easy to see that solving~\eqref{eq:simple2} is equivalent to solving the {\em normal equations} -\begin{align} -H \Delta x &= g \label{eq:normal} -\end{align} - -Ceres provides a number of different options for solving~\eqref{eq:normal}. - -\subsection{\texttt{DENSE\_QR}} -For small problems (a couple of hundred parameters and a few thousand residuals) with relatively dense Jacobians, \texttt{DENSE\_QR} is the method of choice~\cite{bjorck1996numerical}. Let $J = QR$ be the QR-decomposition of $J$, where $Q$ is an orthonormal matrix and $R$ is an upper triangular matrix~\cite{trefethen1997numerical}. Then it can be shown that the solution to~\eqref{eq:normal} is given by -\begin{align} - \Delta x^* = -R^{-1}Q^\top f -\end{align} -Ceres uses \texttt{Eigen}'s dense QR factorization routines. - -\subsection{\texttt{DENSE\_NORMAL\_CHOLESKY} \& \texttt{SPARSE\_NORMAL\_CHOLESKY}} -Large non-linear least square problems are usually sparse. In such cases, using a dense QR factorization is inefficient. Let $H = R^\top R$ be the Cholesky factorization of the normal equations, where $R$ is an upper triangular matrix, then the solution to ~\eqref{eq:normal} is given by -\begin{equation} - \Delta x^* = R^{-1} R^{-\top} g. -\end{equation} -The observant reader will note that the $R$ in the Cholesky -factorization of $H$ is the same upper triangular matrix $R$ in the QR -factorization of $J$. Since $Q$ is an orthonormal matrix, $J=QR$ -implies that $J^\top J = R^\top Q^\top Q R = R^\top R$. There are two variants of Cholesky factorization -- sparse and -dense. - -\texttt{DENSE\_NORMAL\_CHOLESKY} as the name implies performs a dense -Cholesky factorization of the normal equations. Ceres uses -\texttt{Eigen}'s dense LDLT factorization routines. - -\texttt{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' \texttt{SuiteSparse} or -\texttt{CXSparse} packages~\cite{chen2006acs}. - -\subsection{\texttt{DENSE\_SCHUR} \& \texttt{SPARSE\_SCHUR}} -While it is possible to use \texttt{SPARSE\_NORMAL\_CHOLESKY} to solve bundle adjustment problems, bundle adjustment problem have a special structure, and a more efficient scheme for solving~\eqref{eq:normal} can be constructed. - -Suppose that the SfM problem consists of $p$ cameras and $q$ points and the variable vector $x$ has the block structure $x = [y_{1},\hdots,y_{p},z_{1},\hdots,z_{q}]$. Where, $y$ and $z$ correspond to camera and point parameters, respectively. Further, let the camera blocks be of size $c$ and the point blocks be of size $s$ (for most problems $c$ = $6$--$9$ and $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 $f_{i}$ that includes two or more point blocks. This in turn implies that the matrix $H$ is of the form -\begin{equation} - H = \left[ - \begin{matrix} B & E\\ E^\top & C - \end{matrix} - \right]\ , -\label{eq:hblock} -\end{equation} -where, $B \in \reals^{pc\times pc}$ is a block sparse matrix with $p$ blocks of size $c\times c$ and $C \in \reals^{qs\times qs}$ is a block diagonal matrix with $q$ blocks of size $s\times s$. $E \in \reals^{pc\times qs}$ is a general block sparse matrix, with a block of size $c\times s$ for each observation. Let us now block partition $\Delta x = [\Delta y,\Delta z]$ and $g=[v,w]$ to restate~\eqref{eq:normal} as the block structured linear system -\begin{equation} - \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{eq:linear2} -\end{equation} -and apply Gaussian elimination to it. As we noted above, $C$ is a block diagonal matrix, with small diagonal blocks of size $s\times s$. -Thus, calculating the inverse of $C$ by inverting each of these blocks is cheap. This allows us to eliminate $\Delta z$ by observing that $\Delta z = C^{-1}(w - E^\top \Delta y)$, giving us -\begin{equation} - \left[B - EC^{-1}E^\top\right] \Delta y = v - EC^{-1}w\ . \label{eq:schur} -\end{equation} -The matrix -\begin{equation} -S = B - EC^{-1}E^\top\ , -\end{equation} -is the Schur complement of $C$ in $H$. It is also known as the {\em reduced camera matrix}, because the only variables participating in~\eqref{eq:schur} are the ones corresponding to the cameras. $S \in \reals^{pc\times pc}$ is a block structured symmetric positive definite matrix, with blocks of size $c\times c$. The block $S_{ij}$ corresponding to the pair of images $i$ and $j$ is non-zero if and only if the two images observe at least one common point. - -Now, \eqref{eq:linear2}~can be solved by first forming $S$, solving for $\Delta y$, and then back-substituting $\Delta y$ to obtain the value of $\Delta z$. -Thus, the solution of what was an $n\times n$, $n=pc+qs$ linear system is reduced to the inversion of the block diagonal matrix $C$, a few matrix-matrix and matrix-vector multiplies, and the solution of block sparse $pc\times pc$ linear system~\eqref{eq:schur}. For almost all problems, the number of cameras is much smaller than the number of points, $p \ll q$, thus solving~\eqref{eq:schur} is significantly cheaper than solving~\eqref{eq:linear2}. This is the {\em Schur complement trick}~\cite{brown-58}. - -This still leaves open the question of solving~\eqref{eq:schur}. The -method of choice for solving symmetric positive definite systems -exactly is via the Cholesky -factorization~\cite{trefethen1997numerical} and depending upon the -structure of the matrix, there are, in general, two options. The first -is direct factorization, where we store and factor $S$ as a dense -matrix~\cite{trefethen1997numerical}. This method has $O(p^2)$ space complexity and $O(p^3)$ time -complexity and is only practical for problems with up to a few hundred -cameras. Ceres implements this strategy as the \texttt{DENSE\_SCHUR} solver. - - - But, $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 $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~\cite{chen2006acs}. -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 \texttt{SPARSE\_SCHUR} solver. - -\subsection{\texttt{CGNR}} -For general sparse problems, if the problem is too large for \texttt{CHOLMOD} or a sparse linear algebra library is not linked into Ceres, another option is the \texttt{CGNR} solver. This solver uses the Conjugate Gradients solver on the {\em normal equations}, but without forming the normal equations explicitly. It exploits the relation -\begin{align} - H x = J^\top J x = J^\top(J x) -\end{align} -When the user chooses \texttt{ITERATIVE\_SCHUR} as the linear solver, Ceres automatically switches from the exact step algorithm to an inexact step algorithm. - -\subsection{\texttt{ITERATIVE\_SCHUR}} -Another option for bundle adjustment problems is to apply PCG to the reduced camera matrix $S$ instead of $H$. One reason to do this is that $S$ is a much smaller matrix than $H$, but more importantly, it can be shown that $\kappa(S)\leq \kappa(H)$. Ceres implements PCG on $S$ as the \texttt{ITERATIVE\_SCHUR} solver. When the user chooses \texttt{ITERATIVE\_SCHUR} as the linear solver, Ceres automatically switches from the exact step algorithm to an inexact step algorithm. - -The cost of forming and storing the Schur complement $S$ can be prohibitive for large problems. Indeed, for an inexact Newton solver that computes $S$ and runs PCG on it, almost all of its time is spent in constructing $S$; the time spent inside the PCG algorithm is negligible in comparison. Because PCG only needs access to $S$ via its product with a vector, one way to evaluate $Sx$ is to observe that -\begin{align} - x_1 &= E^\top x \notag \\ - x_2 &= C^{-1} x_1 \notag\\ - x_3 &= Ex_2 \notag\\ - x_4 &= Bx \notag\\ - Sx &= x_4 - x_3\ .\label{eq:schurtrick1} -\end{align} -Thus, we can run PCG on $S$ with the same computational effort per iteration as PCG on $H$, while reaping the benefits of a more powerful preconditioner. In fact, we do not even need to compute $H$, \eqref{eq:schurtrick1} can be implemented using just the columns of $J$. - -Equation~\eqref{eq:schurtrick1} is closely related to {\em 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~\cite{saad2003iterative,mathew2008domain}. - -\section{Preconditioner} -The convergence rate of Conjugate Gradients for solving~\eqref{eq:normal} depends on the distribution of eigenvalues of $H$~\cite{saad2003iterative}. A useful upper bound is $\sqrt{\kappa(H)}$, where, $\kappa(H)$f is the condition number of the matrix $H$. For most bundle adjustment problems, $\kappa(H)$ is high and a direct application of Conjugate Gradients to~\eqref{eq:normal} results in extremely poor performance. - -The solution to this problem is to replace~\eqref{eq:normal} with a {\em preconditioned} system. Given a linear system, $Ax =b$ and a preconditioner $M$ the preconditioned system is given by $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 {\em preconditioned} matrix $\kappa(M^{-1}A)$. - -The computational cost of using a preconditioner $M$ is the cost of computing $M$ and evaluating the product $M^{-1}y$ for arbitrary vectors $y$. Thus, there are two competing factors to consider: How much of $H$'s structure is captured by $M$ so that the condition number $\kappa(HM^{-1})$ is low, and the computational cost of constructing and using $M$. The ideal preconditioner would be one for which $\kappa(M^{-1}A) =1$. $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 $M$ has about $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, \ie, $M=\operatorname{diag}(A)$, which for block structured matrices like $H$ can be generalized to the block Jacobi preconditioner. - -For \texttt{ITERATIVE\_SCHUR} there are two obvious choices for block diagonal preconditioners for $S$. The block diagonal of the matrix $B$~\cite{mandel1990block} and the block diagonal $S$, \ie the block Jacobi preconditioner for $S$. Ceres's implements both of these preconditioners and refers to them as \texttt{JACOBI} and \texttt{SCHUR\_JACOBI} respectively. - -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~\cite{kushal2012}. Ceres implements the two visibility based preconditioners described by Kushal \& Agarwal as \texttt{CLUSTER\_JACOBI} and \texttt{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} -\label{sec: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 -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 \texttt{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 {\em 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. e.g. Consider the linear system - -\begin{align} -x + y &= 3\\ - 2x + 3y &= 7 -\end{align} - -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. - -\begin{enumerate} -\item $\{0: x\}, \{1: y\}$: Eliminate $x$ first. -\item $\{0: y\}, \{1: x\}$: Eliminate $y$ first. -\item $\{0: x, y\}$: Solver gets to decide the elimination order. -\end{enumerate} - -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 (\texttt{DENSE\_SCHUR}, -\texttt{SPARSE\_SCHUR},\ \texttt{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~\cite{li2007miqr} . -\section{\texttt{Solver::Options}} - -\texttt{Solver::Options} controls the overall behavior of the -solver. We list the various settings and their default values below. - -\begin{enumerate} - -\item{\texttt{trust\_region\_strategy\_type }} - (\texttt{LEVENBERG\_MARQUARDT}) The trust region step computation - algorithm used by Ceres. Currently \texttt{LEVENBERG\_MARQUARDT } - and \texttt{DOGLEG} are the two valid choices. - -\item{\texttt{dogleg\_type}} (\texttt{TRADITIONAL\_DOGLEG}) Ceres - supports two different dogleg strategies. - \texttt{TRADITIONAL\_DOGLEG} method by Powell and the - \texttt{SUBSPACE\_DOGLEG} method described by Byrd et al. -~\cite{byrd1988approximate}. See Section~\ref{sec:dogleg} for more details. - -\item{\texttt{use\_nonmonotoic\_steps}} (\texttt{false}) -Relax the requirement that the trust-region algorithm take strictly -decreasing steps. See Section~\ref{sec:non-monotonic} for more details. - -\item{\texttt{max\_consecutive\_nonmonotonic\_steps}} (5) -The window size used by the step selection algorithm to accept -non-monotonic steps. - -\item{\texttt{max\_num\_iterations }}(\texttt{50}) Maximum number of - iterations for Levenberg-Marquardt. - -\item{\texttt{max\_solver\_time\_in\_seconds }} ($10^9$) Maximum - amount of time for which the solver should run. - -\item{\texttt{num\_threads }}(\texttt{1}) Number of threads used by - Ceres to evaluate the Jacobian. - -\item{\texttt{initial\_trust\_region\_radius } ($10^4$)} The size of - the initial trust region. When the \texttt{LEVENBERG\_MARQUARDT} - strategy is used, the reciprocal of this number is the initial - regularization parameter. - -\item{\texttt{max\_trust\_region\_radius } ($10^{16}$)} The trust - region radius is not allowed to grow beyond this value. - -\item{\texttt{min\_trust\_region\_radius } ($10^{-32}$)} The solver - terminates, when the trust region becomes smaller than this value. - -\item{\texttt{min\_relative\_decrease }}($10^{-3}$) Lower threshold - for relative decrease before a Levenberg-Marquardt step is acceped. - -\item{\texttt{lm\_min\_diagonal } ($10^6$)} The - \texttt{LEVENBERG\_MARQUARDT} strategy, uses a diagonal matrix to - regularize the the trust region step. This is the lower bound on the - values of this diagonal matrix. - -\item{\texttt{lm\_max\_diagonal } ($10^{32}$)} The - \texttt{LEVENBERG\_MARQUARDT} strategy, uses a diagonal matrix to - regularize the the trust region step. This is the upper bound on the - values of this diagonal matrix. - -\item{\texttt{max\_num\_consecutive\_invalid\_steps } (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. - -\item{\texttt{function\_tolerance }}($10^{-6}$) Solver terminates if -\begin{align} -\frac{|\Delta \text{cost}|}{\text{cost}} < \texttt{function\_tolerance} -\end{align} -where, $\Delta \text{cost}$ is the change in objective function value -(up or down) in the current iteration of Levenberg-Marquardt. - -\item \texttt{Solver::Options::gradient\_tolerance } Solver terminates if -\begin{equation} - \frac{\|g(x)\|_\infty}{\|g(x_0)\|_\infty} < \texttt{gradient\_tolerance} -\end{equation} -where $\|\cdot\|_\infty$ refers to the max norm, and $x_0$ is the vector of initial parameter values. - -\item{\texttt{parameter\_tolerance }}($10^{-8}$) Solver terminates if -\begin{equation} - \frac{\|\Delta x\|}{\|x\| + \texttt{parameter\_tolerance}} < \texttt{parameter\_tolerance} -\end{equation} -where $\Delta x$ is the step computed by the linear solver in the current iteration of Levenberg-Marquardt. - -\item{\texttt{linear\_solver\_type }(\texttt{SPARSE\_NORMAL\_CHOLESKY})} - -\item{\texttt{linear\_solver\_type - }}(\texttt{SPARSE\_NORMAL\_CHOLESKY}/\texttt{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 build with \suitesparse linked in then the - default is \texttt{SPARSE\_NORMAL\_CHOLESKY}, it is - \texttt{DENSE\_QR} otherwise. - -\item{\texttt{preconditioner\_type }}(\texttt{JACOBI}) The - preconditioner used by the iterative linear solver. The default is - the block Jacobi preconditioner. Valid values are (in increasing - order of complexity) \texttt{IDENTITY},\texttt{JACOBI}, - \texttt{SCHUR\_JACOBI}, \texttt{CLUSTER\_JACOBI} and - \texttt{CLUSTER\_TRIDIAGONAL}. - -\item{\texttt{sparse\_linear\_algebra\_library } - (\texttt{SUITE\_SPARSE})} Ceres supports the use of two sparse - linear algebra libraries, \texttt{SuiteSparse}, which is enabled by - setting this parameter to \texttt{SUITE\_SPARSE} and - \texttt{CXSparse}, which can be selected by setting this parameter - to $\texttt{CX\_SPARSE}$. \texttt{SuiteSparse} is a sophisticated - and complex sparse linear algebra library and should be used in - general. If your needs/platforms prevent you from using - \texttt{SuiteSparse}, consider using \texttt{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 - \texttt{SuiteSparse}. - - -\item{\texttt{num\_linear\_solver\_threads }}(\texttt{1}) Number of - threads used by the linear solver. - -\item{\texttt{use\_inner\_iterations} (\texttt{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 the discussion in ~\ref{sec:inner} - -\item{\texttt{inner\_iteration\_ordering} (\texttt{NULL})} If - \texttt{Solver::Options::inner\_iterations} is true, then the user - has two choices. - -\begin{enumerate} -\item Let the solver heuristically decide which parameter blocks to - optimize in each inner iteration. To do this, set - \texttt{inner\_iteration\_ordering} to {\texttt{NULL}}. - -\item 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. -\end{enumerate} - -\item{\texttt{linear\_solver\_ordering} (\texttt{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 \texttt{NULL}, the solver is free to choose an ordering that it - thinks is best. Note: currently, this option only has an effect on - the Schur type solvers, support for the - \texttt{SPARSE\_NORMAL\_CHOLESKY} solver is forth coming. - -\item{\texttt{use\_block\_amd } (\texttt{true})} By virtue of the - modeling layer in Ceres being block oriented, all the matrices used - by Ceres are also block oriented. When doing sparse direct - factorization of these matrices, the fill-reducing ordering - algorithms can either be run on the block or the scalar form of - these matrices. Running it on the block form exposes more of the - super-nodal structure of the matrix to the Cholesky factorization - routines. This leads to substantial gains in factorization - performance. Setting this parameter to true, enables the use of a - block oriented Approximate Minimum Degree ordering - algorithm. Settings it to \texttt{false}, uses a scalar AMD - algorithm. This option only makes sense when using - \texttt{sparse\_linear\_algebra\_library = SUITE\_SPARSE} as it uses - the \texttt{AMD} package that is part of \texttt{SuiteSparse}. - -\item{\texttt{linear\_solver\_min\_num\_iterations }}(\texttt{1}) - Minimum number of iterations used by the linear solver. This only - makes sense when the linear solver is an iterative solver, e.g., - \texttt{ITERATIVE\_SCHUR}. - -\item{\texttt{linear\_solver\_max\_num\_iterations }}(\texttt{500}) - Minimum number of iterations used by the linear solver. This only - makes sense when the linear solver is an iterative solver, e.g., - \texttt{ITERATIVE\_SCHUR}. - -\item{\texttt{eta }} ($10^{-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 -\begin{equation} -\frac{Q_i - Q_{i-1}}{Q_i} < \frac{\eta}{i} -\end{equation} - -\item{\texttt{jacobi\_scaling }}(\texttt{true}) \texttt{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. - -\item{\texttt{logging\_type }}(\texttt{PER\_MINIMIZER\_ITERATION}) - - -\item{\texttt{minimizer\_progress\_to\_stdout }}(\texttt{false}) -By default the Minimizer progress is logged to \texttt{STDERR} -depending on the \texttt{vlog} level. If this flag is -set to true, and \texttt{logging\_type } is not \texttt{SILENT}, the -logging output -is sent to \texttt{STDOUT}. - -\item{\texttt{return\_initial\_residuals }}(\texttt{false}) -\item{\texttt{return\_final\_residuals }}(\texttt{false}) -If true, the vectors \texttt{Solver::Summary::initial\_residuals } and -\texttt{Solver::Summary::final\_residuals } are filled with the -residuals before and after the optimization. The entries of these -vectors are in the order in which ResidualBlocks were added to the -Problem object. - -\item{\texttt{return\_initial\_gradient }}(\texttt{false}) -\item{\texttt{return\_final\_gradient }}(\texttt{false}) -If true, the vectors \texttt{Solver::Summary::initial\_gradient } and -\texttt{Solver::Summary::final\_gradient } are filled with the -gradient before and after the optimization. The entries of these -vectors are in the order in which ParameterBlocks were added to the -Problem object. - -Since \texttt{AddResidualBlock } adds ParameterBlocks to the -\texttt{Problem } automatically if they do not already exist, if you -wish to have explicit control over the ordering of the vectors, then -use \texttt{Problem::AddParameterBlock } to explicitly add the -ParameterBlocks in the order desired. - -\item{\texttt{return\_initial\_jacobian }}(\texttt{false}) -\item{\texttt{return\_initial\_jacobian }}(\texttt{false}) -If true, the Jacobian matrices before and after the optimization are -returned in \texttt{Solver::Summary::initial\_jacobian } and -\texttt{Solver::Summary::final\_jacobian } respectively. - -The rows of these matrices are in the same order in which the -ResidualBlocks were added to the Problem object. The columns are in -the same order in which the ParameterBlocks were added to the Problem -object. - -Since \texttt{AddResidualBlock } adds ParameterBlocks to the -\texttt{Problem } automatically if they do not already exist, if you -wish to have explicit control over the column ordering of the matrix, -then use \texttt{Problem::AddParameterBlock } to explicitly add the -ParameterBlocks in the order desired. - -The Jacobian matrices are stored as compressed row sparse -matrices. Please see \texttt{ceres/crs\_matrix.h } for more details of -the format. - -\item{\texttt{lsqp\_iterations\_to\_dump }} List of iterations at - which the optimizer should dump the linear least squares problem to - disk. Useful for testing and benchmarking. If empty (default), no - problems are dumped. - -\item{\texttt{lsqp\_dump\_directory }} (\texttt{/tmp}) - If \texttt{lsqp\_iterations\_to\_dump} is non-empty, then this - setting determines the directory to which the files containing the - linear least squares problems are written to. - - -\item{\texttt{lsqp\_dump\_format }}(\texttt{TEXTFILE}) The format in - which linear least squares problems should be logged -when \texttt{lsqp\_iterations\_to\_dump} is non-empty. There are three options -\begin{itemize} -\item{\texttt{CONSOLE }} prints the linear least squares problem in a human readable format - to \texttt{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. -\item{\texttt{PROTOBUF }} - Write out the linear least squares problem to the directory - pointed to by \texttt{lsqp\_dump\_directory} as a protocol - buffer. \texttt{linear\_least\_squares\_problems.h/cc} contains routines for - loading these problems. For details on the on disk format used, - see \texttt{matrix.proto}. The files are named - \texttt{lm\_iteration\_???.lsqp}. This requires that - \texttt{protobuf} be linked into Ceres Solver. -\item{\texttt{TEXTFILE }} - Write out the linear least squares problem to the directory - pointed to by \texttt{lsqp\_dump\_directory} as text files - which can be read into \texttt{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 \texttt{MATLAB/Octave} script called \texttt{lm\_iteration\_???.m} is also output, - which can be used to parse and load the problem into memory. -\end{itemize} - - - -\item{\texttt{check\_gradients }}(\texttt{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, details - are printed to the log. - -\item{\texttt{gradient\_check\_relative\_precision }} ($10^{-8}$) - 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. - -\item{\texttt{numeric\_derivative\_relative\_step\_size }} ($10^{-6}$) - Relative shift used for taking numeric derivatives. For finite - differencing, each dimension is evaluated at slightly shifted - values, \eg for forward differences, the numerical derivative is - -\begin{align} - \delta &= \texttt{numeric\_derivative\_relative\_step\_size}\\ - \Delta f &= \frac{f((1 + \delta) x) - f(x)}{\delta x} -\end{align} - -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. $10^9$) and when the -values are small (e.g. $10^{-5}$). It is possible to construct -"torture cases" which break this finite difference heuristic, -but they do not come up often in practice. - -\item{\texttt{callbacks }} - Callbacks that are executed at the end of each iteration of the -\texttt{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 -\texttt{Minimizer} terminates. This behavior is controlled by -\texttt{update\_state\_every\_variable}. If the user wishes to have access -to the update parameter blocks when his/her callbacks are -executed, then set \texttt{update\_state\_every\_iteration} to true. - -The solver does NOT take ownership of these pointers. - -\item{\texttt{update\_state\_every\_iteration }}(\texttt{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 \texttt{IterationCallback}. - -\item{\texttt{solver\_log}} If non-empty, a summary of the execution of the solver is - recorded to this file. This file is used for recording and Ceres' - performance. Currently, only the iteration number, total - time and the objective function value are logged. The format of this - file is expected to change over time as the performance evaluation - framework is fleshed out. -\end{enumerate} - -\section{\texttt{Solver::Summary}} -TBD diff --git a/docs/source/solving.rst b/docs/source/solving.rst index d8b9f4a..f17c695 100644 --- a/docs/source/solving.rst +++ b/docs/source/solving.rst @@ -1147,7 +1147,23 @@ elimination group [LiSaad]_. ``CLUSTER_JACOBI`` and ``CLUSTER_TRIDIAGONAL``. See :ref:`section-preconditioner` for more details. -.. member:: SparseLinearAlgebraLibrary Solver::Options::sparse_linear_algebra_library +.. 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:``SUITE_SPARSE`` @@ -1837,7 +1853,8 @@ elimination group [LiSaad]_. TrustRegionStrategyType trust_region_strategy_type; DoglegType dogleg_type; - SparseLinearAlgebraLibraryType sparse_linear_algebra_library; + DenseLinearAlgebraLibraryType dense_linear_algebra_library_type; + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; LineSearchDirectionType line_search_direction_type; LineSearchType line_search_type; diff --git a/docs/source/version_history.rst b/docs/source/version_history.rst index 5e1a150..f9bc273 100644 --- a/docs/source/version_history.rst +++ b/docs/source/version_history.rst @@ -7,6 +7,12 @@ Version History 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 ------------ @@ -15,9 +21,17 @@ New Features #. ``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) @@ -27,17 +41,31 @@ New Features #. 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 erros in documentation (Pablo Speciale) +#. Minor errors in documentation (Pablo Speciale) #. Updated depend.cmake to follow CMake IF convention. (Joydeep Biswas) #. Stablize the schur ordering algorithm. @@ -97,17 +125,12 @@ New Features #. 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) @@ -183,7 +206,6 @@ New Features 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. @@ -196,23 +218,17 @@ New Features - ``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``. @@ -221,33 +237,22 @@ New Features - 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. @@ -255,55 +260,34 @@ New Features 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) @@ -364,32 +348,22 @@ 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``. @@ -397,40 +371,23 @@ 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) @@ -442,57 +399,37 @@ 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. @@ -500,73 +437,44 @@ 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. @@ -577,10 +485,8 @@ 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). @@ -591,10 +497,8 @@ 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 @@ -604,7 +508,6 @@ 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. @@ -612,17 +515,11 @@ 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 @@ -632,17 +529,12 @@ 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. - +#. ``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. @@ -651,13 +543,9 @@ 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. @@ -668,10 +556,8 @@ 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 @@ -682,20 +568,14 @@ 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. @@ -703,9 +583,7 @@ 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 diff --git a/examples/bundle_adjuster.cc b/examples/bundle_adjuster.cc index c060aed..224ad74 100644 --- a/examples/bundle_adjuster.cc +++ b/examples/bundle_adjuster.cc @@ -84,6 +84,8 @@ DEFINE_string(preconditioner, "jacobi", "Options are: " "cluster_tridiagonal."); 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 " @@ -125,7 +127,10 @@ void SetLinearSolver(Solver::Options* options) { &options->preconditioner_type)); CHECK(StringToSparseLinearAlgebraLibraryType( FLAGS_sparse_linear_algebra_library, - &options->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; } diff --git a/google3/gflags/gflags.h b/google3/gflags/gflags.h new file mode 100644 index 0000000..adaff17 --- /dev/null +++ b/google3/gflags/gflags.h @@ -0,0 +1,35 @@ +// Copyright 2012 Google Inc. All Rights Reserved. +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// This shim file serves two purposes. +// +// 1. Translate the gflags includes used by the OSS version of Ceres +// so that it links into the google3 version. +// +// 2. Call InitGoogle when ParseCommandLineFlags is called. This is +// needed because while google3 binaries call InitGoogle and that call +// initializes the logging and command line handling amongst other +// things, the open source versions of gflags and glog are distributed +// separately and require separate initialization. By hijacking this +// function, and calling InitGoogle, we can compile all the example +// code that ships with Ceres without any modifications. This +// modification will have no impact on google3 binaries using Ceres, +// as they will never call google::ParseCommandLineFlags. + +#ifndef GFLAGS_GFLAGS_H_ +#define GFLAGS_GFLAGS_H_ + +#include "base/init_google.h" +#include "base/commandlineflags.h" + +namespace google { + +inline void ParseCommandLineFlags(int* argc, + char*** argv, + const bool remove_flags) { + InitGoogle(**argv, argc, argv, remove_flags); +} + +} // namespace google + +#endif // GFLAGS_GFLAGS_H_ diff --git a/google3/glog/logging.h b/google3/glog/logging.h new file mode 100644 index 0000000..07804b7 --- /dev/null +++ b/google3/glog/logging.h @@ -0,0 +1,21 @@ +// Copyright 2012 Google Inc. All Rights Reserved. +// Author: keir@google.com (Keir Mierle) +// +// This is a shim header that redirects the Ceres includes of "glog/logging.h" +// to the google3 logging headers. + +#ifndef GLOG_LOGGING_H_ +#define GLOG_LOGGING_H_ + +#include "base/logging.h" + +namespace google { + +inline void InitGoogleLogging(const char* argv0) { + // The gflags shim in //third_party/ceres/google/gflags/gflags.h + // already calls InitGoogle, which gets the logging initialized. +} + +} // namespace google + +#endif // GLOG_LOGGING_H_ diff --git a/google3/gmock/gmock.h b/google3/gmock/gmock.h new file mode 100644 index 0000000..c45c576 --- /dev/null +++ b/google3/gmock/gmock.h @@ -0,0 +1,12 @@ +// Copyright 2012 Google Inc. All Rights Reserved. +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Shim file to translate the paths from the OSS version to the +// google3 version of gmock. + +#ifndef GMOCK_GMOCK_H_ +#define GMOCK_GMOCK_H_ + +#include "testing/base/public/gmock.h" + +#endif // GMOCK_GMOCK_H_ diff --git a/google3/gmock/mock-log.h b/google3/gmock/mock-log.h new file mode 100644 index 0000000..0ed4e4a --- /dev/null +++ b/google3/gmock/mock-log.h @@ -0,0 +1,12 @@ +// Copyright 2012 Google Inc. All Rights Reserved. +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Shim file to translate the paths from the OSS version to the +// google3 version of mock-log.h + +#ifndef GMOCK_MOCK_LOG_H_ +#define GMOCK_MOCK_LOG_H_ + +#include "testing/base/public/mock-log.h" + +#endif // GMOCK_MOCK_LOG_H_ diff --git a/google3/gtest/gtest.h b/google3/gtest/gtest.h new file mode 100644 index 0000000..94e22ab --- /dev/null +++ b/google3/gtest/gtest.h @@ -0,0 +1,12 @@ +// Copyright 2012 Google Inc. All Rights Reserved. +// Author: sameeragarwal@google.com (Sameer Agarwal) +// +// Shim file to translate the paths from the OSS version to the +// google3 version of gunit. + +#ifndef GTEST_GTEST_H_ +#define GTEST_GTEST_H_ + +#include "testing/base/public/gunit.h" + +#endif // GTEST_GTEST_H_ diff --git a/google3/jet_traits.h b/google3/jet_traits.h new file mode 100644 index 0000000..5f58075 --- /dev/null +++ b/google3/jet_traits.h @@ -0,0 +1,82 @@ +// Type traits for google3's custom MathUtil traits class. This is needed to +// enable embedding Jet objects inside the Quaternion class, found in +// util/math/quaternion.h. Including this file makes it possible to use +// quaternions inside Ceres cost functions which are automatically +// differentiated; for example: +// +// struct MyCostFunction { +// template<T> +// bool Map(const T* const quaternion_parameters, T* residuals) { +// Quaternion<T> quaternion(quaternion_parameters); +// ... +// } +// } +// +// NOTE(keir): This header must be included before quaternion.h or other +// file relying on traits. Adding a direct dependency on this header from +// mathlimits.h is a bad idea, so it is up to clients to use the correct include +// order. + +#ifndef JET_TRAITS_H +#define JET_TRAITS_H + +#include "ceres/jet.h" +#include "util/math/mathlimits.h" + +template<typename T, int N> +struct MathLimits<ceres::Jet<T, N> > { + typedef ceres::Jet<T, N> Type; + typedef ceres::Jet<T, N> UnsignedType; + static const bool kIsSigned = true; + static const bool kIsInteger = false; + static const Type kPosMin; + static const Type kPosMax; + static const Type kMin; + static const Type kMax; + static const Type kNegMin; + static const Type kNegMax; + static const int kMin10Exp; + static const int kMax10Exp; + static const Type kEpsilon; + static const Type kStdError; + static const int kPrecisionDigits; + static const Type kNaN; + static const Type kPosInf; + static const Type kNegInf; + static bool IsFinite(const Type x) { return isfinite(x); } + static bool IsNaN (const Type x) { return isnan(x); } + static bool IsInf (const Type x) { return isinf(x); } + static bool IsPosInf(const Type x) { + bool found_inf = MathLimits<T>::IsPosInf(x.a); + for (int i = 0; i < N && !found_inf; ++i) { + found_inf = MathLimits<T>::IsPosInf(x.v[i]); + } + return found_inf; + } + static bool IsNegInf(const Type x) { + bool found_inf = MathLimits<T>::IsNegInf(x.a); + for (int i = 0; i < N && !found_inf; ++i) { + found_inf = MathLimits<T>::IsNegInf(x.v[i]); + } + return found_inf; + } +}; + +// Since every one of these items is a simple forward to the scalar type +// underlying the jet, use a tablular format which makes the structure clear. +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kPosMin = ceres::Jet<T, N>(MathLimits<T>::kPosMin); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kPosMax = ceres::Jet<T, N>(MathLimits<T>::kPosMax); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kMin = ceres::Jet<T, N>(MathLimits<T>::kMin); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kMax = ceres::Jet<T, N>(MathLimits<T>::kMax); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kNegMin = ceres::Jet<T, N>(MathLimits<T>::kNegMin); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kNegMax = ceres::Jet<T, N>(MathLimits<T>::kNegMax); // NOLINT +template<typename T, int N> const int MathLimits<ceres::Jet<T, N> >::kMin10Exp = MathLimits<T>::kMin10Exp; // NOLINT +template<typename T, int N> const int MathLimits<ceres::Jet<T, N> >::kMax10Exp = MathLimits<T>::kMax10Exp; // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kEpsilon = ceres::Jet<T, N>(MathLimits<T>::kEpsilon); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kStdError = ceres::Jet<T, N>(MathLimits<T>::kStdError); // NOLINT +template<typename T, int N> const int MathLimits<ceres::Jet<T, N> >::kPrecisionDigits = MathLimits<T>::kPrecisionDigits; // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kNaN = ceres::Jet<T, N>(MathLimits<T>::kNaN); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kPosInf = ceres::Jet<T, N>(MathLimits<T>::kPosInf); // NOLINT +template<typename T, int N> const ceres::Jet<T, N> MathLimits<ceres::Jet<T, N> >::kNegInf = ceres::Jet<T, N>(MathLimits<T>::kNegInf); // NOLINT + +#endif // JET_TRAITS_H diff --git a/import_ceres_upstream.sh b/import_ceres_upstream.sh index 96e68c1..0203b7e 100644 --- a/import_ceres_upstream.sh +++ b/import_ceres_upstream.sh @@ -39,7 +39,7 @@ cd third_party/ceres declare -r temp_readme="/tmp/README.google" rm -f $temp_readme -echo "URL: https://ceres-solver.googlesource.com/ceres-solver/+/$commit" >> $temp_readme +echo "URL: https://ceres-solver.googlesource.com/ceres-solver/+archive/$commit.tar.gz" >> $temp_readme echo "Version: $commit" >> $temp_readme tail -n +3 README.google >> $temp_readme cp $temp_readme README.google diff --git a/include/ceres/solver.h b/include/ceres/solver.h index e7b8d09..25b762a 100644 --- a/include/ceres/solver.h +++ b/include/ceres/solver.h @@ -73,7 +73,6 @@ class Solver { 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; @@ -100,11 +99,13 @@ class Solver { preconditioner_type = JACOBI; - sparse_linear_algebra_library = SUITE_SPARSE; + dense_linear_algebra_library_type = EIGEN; + sparse_linear_algebra_library_type = SUITE_SPARSE; #if defined(CERES_NO_SUITESPARSE) && !defined(CERES_NO_CXSPARSE) - sparse_linear_algebra_library = CX_SPARSE; + sparse_linear_algebra_library_type = CX_SPARSE; #endif + num_linear_solver_threads = 1; linear_solver_ordering = NULL; use_postordering = false; @@ -384,11 +385,24 @@ class Solver { // Type of preconditioner to use with the iterative linear solvers. PreconditionerType preconditioner_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; + 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 @@ -783,7 +797,8 @@ class Solver { TrustRegionStrategyType trust_region_strategy_type; DoglegType dogleg_type; - SparseLinearAlgebraLibraryType sparse_linear_algebra_library; + DenseLinearAlgebraLibraryType dense_linear_algebra_library_type; + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; LineSearchDirectionType line_search_direction_type; LineSearchType line_search_type; diff --git a/include/ceres/types.h b/include/ceres/types.h index a967541..ffa743a 100644 --- a/include/ceres/types.h +++ b/include/ceres/types.h @@ -126,6 +126,11 @@ enum SparseLinearAlgebraLibraryType { CX_SPARSE }; +enum DenseLinearAlgebraLibraryType { + EIGEN, + LAPACK +}; + enum LinearSolverTerminationType { // Termination criterion was met. For factorization based solvers // the tolerance is assumed to be zero. Any user provided values are @@ -401,6 +406,12 @@ bool StringToSparseLinearAlgebraLibraryType( string value, SparseLinearAlgebraLibraryType* type); +const char* DenseLinearAlgebraLibraryTypeToString( + DenseLinearAlgebraLibraryType type); +bool StringToDenseLinearAlgebraLibraryType( + string value, + DenseLinearAlgebraLibraryType* type); + const char* TrustRegionStrategyTypeToString(TrustRegionStrategyType type); bool StringToTrustRegionStrategyType(string value, TrustRegionStrategyType* type); @@ -444,7 +455,8 @@ const char* SolverTerminationTypeToString(SolverTerminationType type); bool IsSchurType(LinearSolverType type); bool IsSparseLinearAlgebraLibraryTypeAvailable( SparseLinearAlgebraLibraryType type); - +bool IsDenseLinearAlgebraLibraryTypeAvailable( + DenseLinearAlgebraLibraryType type); } // namespace ceres diff --git a/internal/ceres/CMakeLists.txt b/internal/ceres/CMakeLists.txt index 9e2e1ae..610e816 100644 --- a/internal/ceres/CMakeLists.txt +++ b/internal/ceres/CMakeLists.txt @@ -30,6 +30,7 @@ SET(CERES_INTERNAL_SRC array_utils.cc + blas.cc block_evaluate_preparer.cc block_jacobi_preconditioner.cc block_jacobian_writer.cc @@ -64,6 +65,7 @@ SET(CERES_INTERNAL_SRC incomplete_lq_factorization.cc iterative_schur_complement_solver.cc levenberg_marquardt_strategy.cc + lapack.cc line_search.cc line_search_direction.cc line_search_minimizer.cc @@ -130,20 +132,14 @@ ELSE (SCHUR_SPECIALIZATIONS) ENDIF (SCHUR_SPECIALIZATIONS) # For Android, use the internal Glog implementation. -IF (BUILD_ANDROID) - ADD_LIBRARY(miniglog STATIC - miniglog/glog/logging.cc) - - # The Android logging library that defines e.g. __android_log_print is - # creatively named "log". - TARGET_LINK_LIBRARIES(miniglog log) - +IF (MINIGLOG) + ADD_LIBRARY(miniglog STATIC miniglog/glog/logging.cc) INSTALL(TARGETS miniglog EXPORT CeresExport RUNTIME DESTINATION bin LIBRARY DESTINATION lib${LIB_SUFFIX} ARCHIVE DESTINATION lib${LIB_SUFFIX}) -ENDIF (BUILD_ANDROID) +ENDIF (MINIGLOG) SET(CERES_LIBRARY_DEPENDENCIES ${GLOG_LIB}) @@ -166,18 +162,20 @@ IF (SUITESPARSE_FOUND) LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${METIS_LIB}) ENDIF (EXISTS ${METIS_LIB}) - LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${LAPACK_LIB}) - - IF (EXISTS ${BLAS_LIB}) - LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${BLAS_LIB}) - ENDIF (EXISTS ${BLAS_LIB}) - IF (TBB_FOUND) LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${TBB_LIB}) LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${TBB_MALLOC_LIB}) ENDIF (TBB_FOUND) ENDIF (SUITESPARSE_FOUND) +IF (CXSPARSE_FOUND) + LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${CXSPARSE_LIB}) +ENDIF (CXSPARSE_FOUND) + +IF (BLAS_AND_LAPACK_FOUND) + LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${LAPACK_LIBRARIES}) + LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${BLAS_LIBRARIES}) +ENDIF (BLAS_AND_LAPACK_FOUND) IF (CXSPARSE_FOUND) LIST(APPEND CERES_LIBRARY_DEPENDENCIES ${CXSPARSE_LIB}) @@ -194,7 +192,11 @@ SET(CERES_LIBRARY_SOURCE ${CERES_INTERNAL_HDRS} ${CERES_INTERNAL_SCHUR_FILES}) -ADD_LIBRARY(ceres STATIC ${CERES_LIBRARY_SOURCE}) +ADD_LIBRARY(ceres ${CERES_LIBRARY_SOURCE}) +SET_TARGET_PROPERTIES(ceres PROPERTIES + VERSION ${CERES_VERSION} + SOVERSION ${CERES_VERSION_MAJOR} +) TARGET_LINK_LIBRARIES(ceres ${CERES_LIBRARY_DEPENDENCIES}) INSTALL(TARGETS ceres @@ -203,23 +205,6 @@ INSTALL(TARGETS ceres LIBRARY DESTINATION lib${LIB_SUFFIX} ARCHIVE DESTINATION lib${LIB_SUFFIX}) -# Don't build a DLL on MSVC. Supporting Ceres as a DLL on Windows involves -# nontrivial changes that we haven't made yet. -IF (NOT MSVC AND NOT BUILD_ANDROID AND BUILD_SHARED) - ADD_LIBRARY(ceres_shared SHARED ${CERES_LIBRARY_SOURCE}) - TARGET_LINK_LIBRARIES(ceres_shared ${CERES_LIBRARY_DEPENDENCIES}) - SET_TARGET_PROPERTIES(ceres_shared PROPERTIES - VERSION ${CERES_VERSION} - SOVERSION ${CERES_ABI_VERSION}) - - INSTALL(TARGETS ceres_shared - EXPORT CeresExport - RUNTIME DESTINATION bin - LIBRARY DESTINATION lib${LIB_SUFFIX} - ARCHIVE DESTINATION lib${LIB_SUFFIX}) - -ENDIF (NOT MSVC AND NOT BUILD_ANDROID AND BUILD_SHARED) - IF (BUILD_TESTING AND GFLAGS) ADD_LIBRARY(gtest gmock_gtest_all.cc gmock_main.cc) ADD_LIBRARY(test_util @@ -228,6 +213,7 @@ IF (BUILD_TESTING AND GFLAGS) test_util.cc) TARGET_LINK_LIBRARIES(gtest ${GFLAGS_LIB} ${GLOG_LIB}) + TARGET_LINK_LIBRARIES(test_util ceres gtest ${GLOG_LIB}) MACRO (CERES_TEST NAME) ADD_EXECUTABLE(${NAME}_test ${NAME}_test.cc) @@ -242,7 +228,6 @@ IF (BUILD_TESTING AND GFLAGS) CERES_TEST(autodiff) CERES_TEST(autodiff_cost_function) CERES_TEST(autodiff_local_parameterization) - CERES_TEST(blas) CERES_TEST(block_random_access_crs_matrix) CERES_TEST(block_random_access_dense_matrix) CERES_TEST(block_random_access_sparse_matrix) @@ -285,6 +270,7 @@ IF (BUILD_TESTING AND GFLAGS) CERES_TEST(runtime_numeric_diff_cost_function) CERES_TEST(schur_complement_solver) CERES_TEST(schur_eliminator) + CERES_TEST(small_blas) CERES_TEST(solver_impl) # TODO(sameeragarwal): This test should ultimately be made diff --git a/internal/ceres/miniglog/glog/logging.cc b/internal/ceres/blas.cc index 32a78ce..f79b1eb 100644 --- a/internal/ceres/miniglog/glog/logging.cc +++ b/internal/ceres/blas.cc @@ -1,5 +1,5 @@ // Ceres Solver - A fast non-linear least squares minimizer -// Copyright 2012 Google Inc. All rights reserved. +// Copyright 2013 Google Inc. All rights reserved. // http://code.google.com/p/ceres-solver/ // // Redistribution and use in source and binary forms, with or without @@ -26,14 +26,53 @@ // 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) +// Author: sameeragarwal@google.com (Sameer Agarwal) +#include "ceres/blas.h" #include "glog/logging.h" -namespace google { +extern "C" void dsyrk_(char* uplo, + char* trans, + int* n, + int* k, + double* alpha, + double* a, + int* lda, + double* beta, + double* c, + int* ldc); -// This is the set of log sinks. This must be in a separate library to ensure -// that there is only one instance of this across the entire program. -std::set<google::LogSink *> log_sinks_global; +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<double*>(a), + &lda, + &beta, + c, + &ldc); +#endif +} + +} // namespace internal } // namespace ceres diff --git a/internal/ceres/blas.h b/internal/ceres/blas.h index 9629b3d..2ab6663 100644 --- a/internal/ceres/blas.h +++ b/internal/ceres/blas.h @@ -28,377 +28,28 @@ // // Author: sameeragarwal@google.com (Sameer Agarwal) // -// Simple blas functions for use in the Schur Eliminator. These are -// fairly basic implementations which already yield a significant -// speedup in the eliminator performance. +// Wrapper functions around BLAS functions. #ifndef CERES_INTERNAL_BLAS_H_ #define CERES_INTERNAL_BLAS_H_ -#include "ceres/internal/eigen.h" -#include "glog/logging.h" - namespace ceres { namespace internal { -// Remove the ".noalias()" annotation from the matrix matrix -// mutliplies to produce a correct build with the Android NDK, -// including versions 6, 7, 8, and 8b, when built with STLPort and the -// non-standalone toolchain (i.e. ndk-build). This appears to be a -// compiler bug; if the workaround is not in place, the line -// -// block.noalias() -= A * B; -// -// gets compiled to -// -// block.noalias() += A * B; -// -// which breaks schur elimination. Introducing a temporary by removing the -// .noalias() annotation causes the issue to disappear. Tracking this -// issue down was tricky, since the test suite doesn't run when built with -// the non-standalone toolchain. -// -// TODO(keir): Make a reproduction case for this and send it upstream. -#ifdef CERES_WORK_AROUND_ANDROID_NDK_COMPILER_BUG -#define CERES_MAYBE_NOALIAS -#else -#define CERES_MAYBE_NOALIAS .noalias() -#endif - -// The following three macros are used to share code and reduce -// template junk across the various GEMM variants. -#define CERES_GEMM_BEGIN(name) \ - template<int kRowA, int kColA, int kRowB, int kColB, int kOperation> \ - inline void name(const double* A, \ - const int num_row_a, \ - const int num_col_a, \ - const double* B, \ - const int num_row_b, \ - const int num_col_b, \ - double* C, \ - const int start_row_c, \ - const int start_col_c, \ - const int row_stride_c, \ - const int col_stride_c) - -#define CERES_GEMM_NAIVE_HEADER \ - DCHECK_GT(num_row_a, 0); \ - DCHECK_GT(num_col_a, 0); \ - DCHECK_GT(num_row_b, 0); \ - DCHECK_GT(num_col_b, 0); \ - DCHECK_GE(start_row_c, 0); \ - DCHECK_GE(start_col_c, 0); \ - DCHECK_GT(row_stride_c, 0); \ - DCHECK_GT(col_stride_c, 0); \ - DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); \ - DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); \ - DCHECK((kRowB == Eigen::Dynamic) || (kRowB == num_row_b)); \ - DCHECK((kColB == Eigen::Dynamic) || (kColB == num_col_b)); \ - const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); \ - const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); \ - const int NUM_ROW_B = (kColB != Eigen::Dynamic ? kRowB : num_row_b); \ - const int NUM_COL_B = (kColB != Eigen::Dynamic ? kColB : num_col_b); - -#define CERES_GEMM_EIGEN_HEADER \ - const typename EigenTypes<kRowA, kColA>::ConstMatrixRef \ - Aref(A, num_row_a, num_col_a); \ - const typename EigenTypes<kRowB, kColB>::ConstMatrixRef \ - Bref(B, num_row_b, num_col_b); \ - MatrixRef Cref(C, row_stride_c, col_stride_c); \ - -#define CERES_CALL_GEMM(name) \ - name<kRowA, kColA, kRowB, kColB, kOperation>( \ - A, num_row_a, num_col_a, \ - B, num_row_b, num_col_b, \ - C, start_row_c, start_col_c, row_stride_c, col_stride_c); - - -// For the matrix-matrix functions below, there are three variants for -// each functionality. Foo, FooNaive and FooEigen. Foo is the one to -// be called by the user. FooNaive is a basic loop based -// implementation and FooEigen uses Eigen's implementation. Foo -// chooses between FooNaive and FooEigen depending on how many of the -// template arguments are fixed at compile time. Currently, FooEigen -// is called if all matrix dimensions are compile time -// constants. FooNaive is called otherwise. This leads to the best -// performance currently. -// -// The MatrixMatrixMultiply variants compute: -// -// C op A * B; -// -// The MatrixTransposeMatrixMultiply variants compute: -// -// C op A' * B -// -// where op can be +=, -=, or =. -// -// The template parameters (kRowA, kColA, kRowB, kColB) allow -// specialization of the loop at compile time. If this information is -// not available, then Eigen::Dynamic should be used as the template -// argument. -// -// kOperation = 1 -> C += A * B -// kOperation = -1 -> C -= A * B -// kOperation = 0 -> C = A * B -// -// The functions can write into matrices C which are larger than the -// matrix A * B. This is done by specifying the true size of C via -// row_stride_c and col_stride_c, and then indicating where A * B -// should be written into by start_row_c and start_col_c. -// -// Graphically if row_stride_c = 10, col_stride_c = 12, start_row_c = -// 4 and start_col_c = 5, then if A = 3x2 and B = 2x4, we get -// -// ------------ -// ------------ -// ------------ -// ------------ -// -----xxxx--- -// -----xxxx--- -// -----xxxx--- -// ------------ -// ------------ -// ------------ -// -CERES_GEMM_BEGIN(MatrixMatrixMultiplyEigen) { - CERES_GEMM_EIGEN_HEADER - Eigen::Block<MatrixRef, kRowA, kColB> - block(Cref, start_row_c, start_col_c, num_row_a, num_col_b); - - if (kOperation > 0) { - block CERES_MAYBE_NOALIAS += Aref * Bref; - } else if (kOperation < 0) { - block CERES_MAYBE_NOALIAS -= Aref * Bref; - } else { - block CERES_MAYBE_NOALIAS = Aref * Bref; - } -} - -CERES_GEMM_BEGIN(MatrixMatrixMultiplyNaive) { - CERES_GEMM_NAIVE_HEADER - DCHECK_EQ(NUM_COL_A, NUM_ROW_B); - - const int NUM_ROW_C = NUM_ROW_A; - const int NUM_COL_C = NUM_COL_B; - DCHECK_LE(start_row_c + NUM_ROW_C, row_stride_c); - DCHECK_LE(start_col_c + NUM_COL_C, col_stride_c); - - for (int row = 0; row < NUM_ROW_C; ++row) { - for (int col = 0; col < NUM_COL_C; ++col) { - double tmp = 0.0; - for (int k = 0; k < NUM_COL_A; ++k) { - tmp += A[row * NUM_COL_A + k] * B[k * NUM_COL_B + col]; - } - - const int index = (row + start_row_c) * col_stride_c + start_col_c + col; - if (kOperation > 0) { - C[index] += tmp; - } else if (kOperation < 0) { - C[index] -= tmp; - } else { - C[index] = tmp; - } - } - } -} - -CERES_GEMM_BEGIN(MatrixMatrixMultiply) { -#ifdef CERES_NO_CUSTOM_BLAS - - CERES_CALL_GEMM(MatrixMatrixMultiplyEigen) - return; - -#else - - if (kRowA != Eigen::Dynamic && kColA != Eigen::Dynamic && - kRowB != Eigen::Dynamic && kColB != Eigen::Dynamic) { - CERES_CALL_GEMM(MatrixMatrixMultiplyEigen) - } else { - CERES_CALL_GEMM(MatrixMatrixMultiplyNaive) - } - -#endif -} - -CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiplyEigen) { - CERES_GEMM_EIGEN_HEADER - Eigen::Block<MatrixRef, kColA, kColB> block(Cref, - start_row_c, start_col_c, - num_col_a, num_col_b); - if (kOperation > 0) { - block CERES_MAYBE_NOALIAS += Aref.transpose() * Bref; - } else if (kOperation < 0) { - block CERES_MAYBE_NOALIAS -= Aref.transpose() * Bref; - } else { - block CERES_MAYBE_NOALIAS = Aref.transpose() * Bref; - } -} - -CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiplyNaive) { - CERES_GEMM_NAIVE_HEADER - DCHECK_EQ(NUM_ROW_A, NUM_ROW_B); - - const int NUM_ROW_C = NUM_COL_A; - const int NUM_COL_C = NUM_COL_B; - DCHECK_LE(start_row_c + NUM_ROW_C, row_stride_c); - DCHECK_LE(start_col_c + NUM_COL_C, col_stride_c); - - for (int row = 0; row < NUM_ROW_C; ++row) { - for (int col = 0; col < NUM_COL_C; ++col) { - double tmp = 0.0; - for (int k = 0; k < NUM_ROW_A; ++k) { - tmp += A[k * NUM_COL_A + row] * B[k * NUM_COL_B + col]; - } - - const int index = (row + start_row_c) * col_stride_c + start_col_c + col; - if (kOperation > 0) { - C[index]+= tmp; - } else if (kOperation < 0) { - C[index]-= tmp; - } else { - C[index]= tmp; - } - } - } -} - -CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiply) { -#ifdef CERES_NO_CUSTOM_BLAS - - CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyEigen) - return; - -#else - - if (kRowA != Eigen::Dynamic && kColA != Eigen::Dynamic && - kRowB != Eigen::Dynamic && kColB != Eigen::Dynamic) { - CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyEigen) - } else { - CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyNaive) - } - -#endif -} - -// Matrix-Vector multiplication -// -// c op A * b; -// -// where op can be +=, -=, or =. -// -// The template parameters (kRowA, kColA) allow specialization of the -// loop at compile time. If this information is not available, then -// Eigen::Dynamic should be used as the template argument. -// -// kOperation = 1 -> c += A' * b -// kOperation = -1 -> c -= A' * b -// kOperation = 0 -> c = A' * b -template<int kRowA, int kColA, int kOperation> -inline void MatrixVectorMultiply(const double* A, - const int num_row_a, - const int num_col_a, - const double* b, - double* c) { -#ifdef CERES_NO_CUSTOM_BLAS - const typename EigenTypes<kRowA, kColA>::ConstMatrixRef - Aref(A, num_row_a, num_col_a); - const typename EigenTypes<kColA>::ConstVectorRef bref(b, num_col_a); - typename EigenTypes<kRowA>::VectorRef cref(c, num_row_a); - - // lazyProduct works better than .noalias() for matrix-vector - // products. - if (kOperation > 0) { - cref += Aref.lazyProduct(bref); - } else if (kOperation < 0) { - cref -= Aref.lazyProduct(bref); - } else { - cref = Aref.lazyProduct(bref); - } -#else - - DCHECK_GT(num_row_a, 0); - DCHECK_GT(num_col_a, 0); - DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); - DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); - - const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); - const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); - - for (int row = 0; row < NUM_ROW_A; ++row) { - double tmp = 0.0; - for (int col = 0; col < NUM_COL_A; ++col) { - tmp += A[row * NUM_COL_A + col] * b[col]; - } - - if (kOperation > 0) { - c[row] += tmp; - } else if (kOperation < 0) { - c[row] -= tmp; - } else { - c[row] = tmp; - } - } -#endif // CERES_NO_CUSTOM_BLAS -} - -// Similar to MatrixVectorMultiply, except that A is transposed, i.e., -// -// c op A' * b; -template<int kRowA, int kColA, int kOperation> -inline void MatrixTransposeVectorMultiply(const double* A, - const int num_row_a, - const int num_col_a, - const double* b, - double* c) { -#ifdef CERES_NO_CUSTOM_BLAS - const typename EigenTypes<kRowA, kColA>::ConstMatrixRef - Aref(A, num_row_a, num_col_a); - const typename EigenTypes<kRowA>::ConstVectorRef bref(b, num_row_a); - typename EigenTypes<kColA>::VectorRef cref(c, num_col_a); - - // lazyProduct works better than .noalias() for matrix-vector - // products. - if (kOperation > 0) { - cref += Aref.transpose().lazyProduct(bref); - } else if (kOperation < 0) { - cref -= Aref.transpose().lazyProduct(bref); - } else { - cref = Aref.transpose().lazyProduct(bref); - } -#else - - DCHECK_GT(num_row_a, 0); - DCHECK_GT(num_col_a, 0); - DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); - DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); - - const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); - const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); - - for (int row = 0; row < NUM_COL_A; ++row) { - double tmp = 0.0; - for (int col = 0; col < NUM_ROW_A; ++col) { - tmp += A[col * NUM_COL_A + row] * b[col]; - } - - if (kOperation > 0) { - c[row] += tmp; - } else if (kOperation < 0) { - c[row] -= tmp; - } else { - c[row] = tmp; - } - } -#endif // CERES_NO_CUSTOM_BLAS -} - - -#undef CERES_MAYBE_NOALIAS -#undef CERES_GEMM_BEGIN -#undef CERES_GEMM_EIGEN_HEADER -#undef CERES_GEMM_NAIVE_HEADER -#undef CERES_CALL_GEMM +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 diff --git a/internal/ceres/block_jacobi_preconditioner.cc b/internal/ceres/block_jacobi_preconditioner.cc index 749e0b6..29974d4 100644 --- a/internal/ceres/block_jacobi_preconditioner.cc +++ b/internal/ceres/block_jacobi_preconditioner.cc @@ -111,7 +111,7 @@ bool BlockJacobiPreconditioner::UpdateImpl(const BlockSparseMatrix& A, } block = block.selfadjointView<Eigen::Upper>() - .ldlt() + .llt() .solve(Matrix::Identity(size, size)); } return true; diff --git a/internal/ceres/block_sparse_matrix.cc b/internal/ceres/block_sparse_matrix.cc index fdd762c..a487262 100644 --- a/internal/ceres/block_sparse_matrix.cc +++ b/internal/ceres/block_sparse_matrix.cc @@ -33,9 +33,9 @@ #include <cstddef> #include <algorithm> #include <vector> -#include "ceres/blas.h" #include "ceres/block_structure.h" #include "ceres/internal/eigen.h" +#include "ceres/small_blas.h" #include "ceres/triplet_sparse_matrix.h" #include "glog/logging.h" diff --git a/internal/ceres/c_api.cc b/internal/ceres/c_api.cc index 02bc129..1fd01c9 100644 --- a/internal/ceres/c_api.cc +++ b/internal/ceres/c_api.cc @@ -49,7 +49,8 @@ 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. - google::InitGoogleLogging("<unknown>"); + char message[] = "<unknown>"; + google::InitGoogleLogging(message); } ceres_problem_t* ceres_create_problem() { @@ -172,7 +173,7 @@ ceres_residual_block_id_t* ceres_problem_add_residual_block( void ceres_solve(ceres_problem_t* c_problem) { Problem* problem = reinterpret_cast<Problem*>(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. diff --git a/internal/ceres/compressed_col_sparse_matrix_utils.h b/internal/ceres/compressed_col_sparse_matrix_utils.h index afabf1c..c8de2a1 100644 --- a/internal/ceres/compressed_col_sparse_matrix_utils.h +++ b/internal/ceres/compressed_col_sparse_matrix_utils.h @@ -61,6 +61,81 @@ void BlockOrderingToScalarOrdering(const vector<int>& blocks, const vector<int>& block_ordering, vector<int>* scalar_ordering); +// Solve the linear system +// +// R * solution = rhs +// +// Where R is an upper triangular compressed column sparse matrix. +template <typename IntegerType> +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 <typename IntegerType> +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 <typename IntegerType> +void SolveRTRWithSparseRHS(IntegerType num_cols, + const IntegerType* rows, + const IntegerType* cols, + const double* values, + const int rhs_nonzero_index, + double* solution) { + 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 diff --git a/internal/ceres/compressed_col_sparse_matrix_utils_test.cc b/internal/ceres/compressed_col_sparse_matrix_utils_test.cc index e810837..3faf06c 100644 --- a/internal/ceres/compressed_col_sparse_matrix_utils_test.cc +++ b/internal/ceres/compressed_col_sparse_matrix_utils_test.cc @@ -193,5 +193,92 @@ TEST(_, ScalarMatrixToBlockMatrix) { ss.Free(ccsm.release()); } +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<int> cols; + vector<int> rows; + vector<double> 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<int>(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<int>(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<int>(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/covariance_impl.cc b/internal/ceres/covariance_impl.cc index 1befde7..19d545c 100644 --- a/internal/ceres/covariance_impl.cc +++ b/internal/ceres/covariance_impl.cc @@ -38,6 +38,7 @@ #include <utility> #include <vector> #include "Eigen/SVD" +#include "ceres/compressed_col_sparse_matrix_utils.h" #include "ceres/compressed_row_sparse_matrix.h" #include "ceres/covariance.h" #include "ceres/crs_matrix.h" @@ -48,7 +49,6 @@ #include "ceres/suitesparse.h" #include "ceres/wall_time.h" #include "glog/logging.h" -#include "SuiteSparseQR.hpp" namespace ceres { namespace internal { @@ -56,6 +56,7 @@ namespace { // Per thread storage for SuiteSparse. #ifndef CERES_NO_SUITESPARSE + struct PerThreadContext { explicit PerThreadContext(int num_rows) : solution(NULL), @@ -81,6 +82,7 @@ struct PerThreadContext { cholmod_dense* rhs; SuiteSparse ss; }; + #endif } // namespace @@ -604,16 +606,8 @@ bool CovarianceImpl::ComputeCovarianceValuesUsingSparseQR() { const int num_cols = jacobian.num_cols; const int num_nonzeros = jacobian.values.size(); - // UF_long is deprecated but SuiteSparse_long is only available in - // newer versions of SuiteSparse. -#if (SUITESPARSE_VERSION < 4002) - vector<UF_long> transpose_rows(num_cols + 1, 0); - vector<UF_long> transpose_cols(num_nonzeros, 0); -#else vector<SuiteSparse_long> transpose_rows(num_cols + 1, 0); vector<SuiteSparse_long> transpose_cols(num_nonzeros, 0); -#endif - vector<double> transpose_values(num_nonzeros, 0); for (int idx = 0; idx < num_nonzeros; ++idx) { @@ -658,23 +652,49 @@ bool CovarianceImpl::ComputeCovarianceValuesUsingSparseQR() { cholmod_common cc; cholmod_l_start(&cc); - SuiteSparseQR_factorization<double>* factor = - SuiteSparseQR_factorize<double>(SPQR_ORDERING_BESTAMD, - SPQR_DEFAULT_TOL, - &cholmod_jacobian, - &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<double>(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); - const int rank = cc.SPQR_istat[4]; if (rank < cholmod_jacobian.ncol) { LOG(WARNING) << "Jacobian matrix is rank deficient." << "Number of columns: " << cholmod_jacobian.ncol << " rank: " << rank; - SuiteSparseQR_free(&factor, &cc); + delete []permutation; + cholmod_l_free_sparse(&R, &cc); cholmod_l_finish(&cc); return false; } + vector<int> 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(); @@ -688,35 +708,39 @@ bool CovarianceImpl::ComputeCovarianceValuesUsingSparseQR() { // // Since the covariance matrix is symmetric, the i^th row and column // are equal. + const int num_threads = options_.num_threads; + scoped_array<double> workspace(new double[num_threads * num_cols]); - cholmod_dense* rhs = cholmod_l_zeros(num_cols, 1, CHOLMOD_REAL, &cc); - double* rhs_x = reinterpret_cast<double*>(rhs->x); - +#pragma omp parallel for num_threads(num_threads) schedule(dynamic) for (int r = 0; r < num_cols; ++r) { - int row_begin = rows[r]; - int row_end = rows[r + 1]; + const int row_begin = rows[r]; + const int row_end = rows[r + 1]; if (row_end == row_begin) { continue; } - rhs_x[r] = 1.0; - - cholmod_dense* y1 = SuiteSparseQR_solve<double>(SPQR_RTX_EQUALS_ETB, factor, rhs, &cc); - cholmod_dense* solution = SuiteSparseQR_solve<double>(SPQR_RETX_EQUALS_B, factor, y1, &cc); +# ifdef CERES_USE_OPENMP + int thread_id = omp_get_thread_num(); +# else + int thread_id = 0; +# endif - double* solution_x = reinterpret_cast<double*>(solution->x); + double* solution = workspace.get() + thread_id * num_cols; + SolveRTRWithSparseRHS<SuiteSparse_long>( + num_cols, + static_cast<SuiteSparse_long*>(R->i), + static_cast<SuiteSparse_long*>(R->p), + static_cast<double*>(R->x), + inverse_permutation[r], + solution); for (int idx = row_begin; idx < row_end; ++idx) { - const int c = cols[idx]; - values[idx] = solution_x[c]; + const int c = cols[idx]; + values[idx] = solution[inverse_permutation[c]]; } - - cholmod_l_free_dense(&y1, &cc); - cholmod_l_free_dense(&solution, &cc); - rhs_x[r] = 0.0; } - cholmod_l_free_dense(&rhs, &cc); - SuiteSparseQR_free(&factor, &cc); + delete []permutation; + cholmod_l_free_sparse(&R, &cc); cholmod_l_finish(&cc); event_logger.AddEvent("Inversion"); return true; diff --git a/internal/ceres/covariance_test.cc b/internal/ceres/covariance_test.cc index e7d25a1..f3a5051 100644 --- a/internal/ceres/covariance_test.cc +++ b/internal/ceres/covariance_test.cc @@ -499,6 +499,9 @@ TEST_F(CovarianceTest, ConstantParameterBlock) { #ifndef CERES_NO_SUITESPARSE options.algorithm_type = SPARSE_CHOLESKY; ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); #endif options.algorithm_type = DENSE_SVD; @@ -552,6 +555,9 @@ TEST_F(CovarianceTest, LocalParameterization) { #ifndef CERES_NO_SUITESPARSE options.algorithm_type = SPARSE_CHOLESKY; ComputeAndCompareCovarianceBlocks(options, expected_covariance); + + options.algorithm_type = SPARSE_QR; + ComputeAndCompareCovarianceBlocks(options, expected_covariance); #endif options.algorithm_type = DENSE_SVD; @@ -776,6 +782,7 @@ class LargeScaleCovarianceTest : public ::testing::Test { TEST_F(LargeScaleCovarianceTest, Parallel) { ComputeAndCompare(SPARSE_CHOLESKY, 4); + ComputeAndCompare(SPARSE_QR, 4); } #endif // !defined(CERES_NO_SUITESPARSE) && defined(CERES_USE_OPENMP) diff --git a/internal/ceres/cxsparse.h b/internal/ceres/cxsparse.h index 6004301..cd87908 100644 --- a/internal/ceres/cxsparse.h +++ b/internal/ceres/cxsparse.h @@ -125,6 +125,11 @@ class CXSparse { } // namespace internal } // namespace ceres +#else // CERES_NO_CXSPARSE + +class CXSparse {}; +typedef void cs_dis; + #endif // CERES_NO_CXSPARSE #endif // CERES_INTERNAL_CXSPARSE_H_ diff --git a/internal/ceres/dense_normal_cholesky_solver.cc b/internal/ceres/dense_normal_cholesky_solver.cc index 96f5511..fbf3cbe 100644 --- a/internal/ceres/dense_normal_cholesky_solver.cc +++ b/internal/ceres/dense_normal_cholesky_solver.cc @@ -33,9 +33,11 @@ #include <cstddef> #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" @@ -52,6 +54,18 @@ LinearSolver::Summary DenseNormalCholeskySolver::SolveImpl( 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(); @@ -62,6 +76,7 @@ LinearSolver::Summary DenseNormalCholeskySolver::SolveImpl( lhs.setZero(); event_logger.AddEvent("Setup"); + // lhs += A'A // // Using rankUpdate instead of GEMM, exposes the fact that its the @@ -76,16 +91,66 @@ LinearSolver::Summary DenseNormalCholeskySolver::SolveImpl( 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 = TOLERANCE; VectorRef(x, num_cols) = - lhs.selfadjointView<Eigen::Upper>().ldlt().solve(rhs); + lhs.selfadjointView<Eigen::Upper>().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"); + + const int info = LAPACK::SolveInPlaceUsingCholesky(num_cols, lhs.data(), x); + event_logger.AddEvent("Solve"); + + LinearSolver::Summary summary; + summary.num_iterations = 1; + summary.termination_type = info == 0 ? TOLERANCE : FAILURE; + + event_logger.AddEvent("TearDown"); + return summary; +} } // namespace internal } // namespace ceres diff --git a/internal/ceres/dense_normal_cholesky_solver.h b/internal/ceres/dense_normal_cholesky_solver.h index de47740..e35053f 100644 --- a/internal/ceres/dense_normal_cholesky_solver.h +++ b/internal/ceres/dense_normal_cholesky_solver.h @@ -85,6 +85,18 @@ class DenseNormalCholeskySolver: public DenseSparseMatrixSolver { 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); }; diff --git a/internal/ceres/dense_qr_solver.cc b/internal/ceres/dense_qr_solver.cc index 1fb9709..d76d58b 100644 --- a/internal/ceres/dense_qr_solver.cc +++ b/internal/ceres/dense_qr_solver.cc @@ -30,12 +30,13 @@ #include "ceres/dense_qr_solver.h" -#include <cstddef> +#include <cstddef> #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" @@ -44,13 +45,87 @@ namespace ceres { namespace internal { DenseQRSolver::DenseQRSolver(const LinearSolver::Options& options) - : 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); + } + + const int info = LAPACK::SolveUsingQR(lhs_.rows(), + lhs_.cols(), + lhs_.data(), + work_.rows(), + work_.data(), + rhs_.data()); + event_logger.AddEvent("Solve"); + + LinearSolver::Summary summary; + summary.num_iterations = 1; + if (info == 0) { + VectorRef(x, num_cols) = rhs_.head(num_cols); + summary.termination_type = TOLERANCE; + } else { + summary.termination_type = FAILURE; + } + + 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(); @@ -73,7 +148,7 @@ LinearSolver::Summary DenseQRSolver::SolveImpl( event_logger.AddEvent("Setup"); // Solve the system. - VectorRef(x, num_cols) = A->matrix().colPivHouseholderQr().solve(rhs_); + VectorRef(x, num_cols) = A->matrix().householderQr().solve(rhs_); event_logger.AddEvent("Solve"); if (per_solve_options.D != NULL) { diff --git a/internal/ceres/dense_qr_solver.h b/internal/ceres/dense_qr_solver.h index f78fa72..e745c63 100644 --- a/internal/ceres/dense_qr_solver.h +++ b/internal/ceres/dense_qr_solver.h @@ -90,8 +90,22 @@ class DenseQRSolver: public DenseSparseMatrixSolver { 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); }; diff --git a/internal/ceres/implicit_schur_complement.cc b/internal/ceres/implicit_schur_complement.cc index 7c934fb..32722bb 100644 --- a/internal/ceres/implicit_schur_complement.cc +++ b/internal/ceres/implicit_schur_complement.cc @@ -161,7 +161,7 @@ void ImplicitSchurComplement::AddDiagonalAndInvert( m = m .selfadjointView<Eigen::Upper>() - .ldlt() + .llt() .solve(Matrix::Identity(row_block_size, row_block_size)); } } diff --git a/internal/ceres/implicit_schur_complement_test.cc b/internal/ceres/implicit_schur_complement_test.cc index bd36672..1694273 100644 --- a/internal/ceres/implicit_schur_complement_test.cc +++ b/internal/ceres/implicit_schur_complement_test.cc @@ -109,7 +109,7 @@ class ImplicitSchurComplementTest : public ::testing::Test { solution->setZero(); VectorRef schur_solution(solution->data() + num_cols_ - num_schur_rows, num_schur_rows); - schur_solution = lhs->selfadjointView<Eigen::Upper>().ldlt().solve(*rhs); + schur_solution = lhs->selfadjointView<Eigen::Upper>().llt().solve(*rhs); eliminator->BackSubstitute(A_.get(), b_.get(), D, schur_solution.data(), solution->data()); } @@ -156,7 +156,7 @@ class ImplicitSchurComplementTest : public ::testing::Test { // Reference solution to the f_block. const Vector reference_f_sol = - lhs.selfadjointView<Eigen::Upper>().ldlt().solve(rhs); + lhs.selfadjointView<Eigen::Upper>().llt().solve(rhs); // Backsubstituted solution from the implicit schur solver using the // reference solution to the f_block. diff --git a/internal/ceres/iterative_schur_complement_solver.cc b/internal/ceres/iterative_schur_complement_solver.cc index d39d7db..1aac565 100644 --- a/internal/ceres/iterative_schur_complement_solver.cc +++ b/internal/ceres/iterative_schur_complement_solver.cc @@ -78,6 +78,17 @@ LinearSolver::Summary IterativeSchurComplementSolver::SolveImpl( } schur_complement_->Init(*A, per_solve_options.D, b); + const int num_schur_complement_blocks = + A->block_structure()->cols.size() - options_.elimination_groups[0]; + if (num_schur_complement_blocks == 0) { + VLOG(2) << "No parameter blocks left in the schur complement."; + LinearSolver::Summary cg_summary; + cg_summary.num_iterations = 0; + cg_summary.termination_type = TOLERANCE; + schur_complement_->BackSubstitute(NULL, x); + return cg_summary; + } + // Initialize the solution to the Schur complement system to zero. // // TODO(sameeragarwal): There maybe a better initialization than an @@ -97,8 +108,8 @@ LinearSolver::Summary IterativeSchurComplementSolver::SolveImpl( Preconditioner::Options preconditioner_options; preconditioner_options.type = options_.preconditioner_type; - preconditioner_options.sparse_linear_algebra_library = - options_.sparse_linear_algebra_library; + preconditioner_options.sparse_linear_algebra_library_type = + options_.sparse_linear_algebra_library_type; preconditioner_options.num_threads = options_.num_threads; preconditioner_options.row_block_size = options_.row_block_size; preconditioner_options.e_block_size = options_.e_block_size; @@ -116,16 +127,16 @@ LinearSolver::Summary IterativeSchurComplementSolver::SolveImpl( case SCHUR_JACOBI: if (preconditioner_.get() == NULL) { preconditioner_.reset( - new SchurJacobiPreconditioner( - *A->block_structure(), preconditioner_options)); + new SchurJacobiPreconditioner(*A->block_structure(), + preconditioner_options)); } break; case CLUSTER_JACOBI: case CLUSTER_TRIDIAGONAL: if (preconditioner_.get() == NULL) { preconditioner_.reset( - new VisibilityBasedPreconditioner( - *A->block_structure(), preconditioner_options)); + new VisibilityBasedPreconditioner(*A->block_structure(), + preconditioner_options)); } break; default: diff --git a/internal/ceres/iterative_schur_complement_solver_test.cc b/internal/ceres/iterative_schur_complement_solver_test.cc index 86e7825..db45741 100644 --- a/internal/ceres/iterative_schur_complement_solver_test.cc +++ b/internal/ceres/iterative_schur_complement_solver_test.cc @@ -58,9 +58,9 @@ const double kEpsilon = 1e-14; class IterativeSchurComplementSolverTest : public ::testing::Test { protected : - virtual void SetUp() { + void SetUpProblem(int problem_id) { scoped_ptr<LinearLeastSquaresProblem> problem( - CreateLinearLeastSquaresProblemFromId(2)); + CreateLinearLeastSquaresProblemFromId(problem_id)); CHECK_NOTNULL(problem.get()); A_.reset(down_cast<BlockSparseMatrix*>(problem->A.release())); @@ -90,7 +90,9 @@ class IterativeSchurComplementSolverTest : public ::testing::Test { qr->Solve(&dense_A, b_.get(), per_solve_options, reference_solution.data()); options.elimination_groups.push_back(num_eliminate_blocks_); + options.elimination_groups.push_back(0); options.max_num_iterations = num_cols_; + options.preconditioner_type = SCHUR_JACOBI; IterativeSchurComplementSolver isc(options); Vector isc_sol(num_cols_); @@ -114,7 +116,14 @@ class IterativeSchurComplementSolverTest : public ::testing::Test { scoped_array<double> D_; }; -TEST_F(IterativeSchurComplementSolverTest, SolverTest) { +TEST_F(IterativeSchurComplementSolverTest, NormalProblem) { + SetUpProblem(2); + EXPECT_TRUE(TestSolver(NULL)); + EXPECT_TRUE(TestSolver(D_.get())); +} + +TEST_F(IterativeSchurComplementSolverTest, ProblemWithNoFBlocks) { + SetUpProblem(3); EXPECT_TRUE(TestSolver(NULL)); EXPECT_TRUE(TestSolver(D_.get())); } diff --git a/internal/ceres/lapack.cc b/internal/ceres/lapack.cc new file mode 100644 index 0000000..73bfa69 --- /dev/null +++ b/internal/ceres/lapack.cc @@ -0,0 +1,157 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2013 Google Inc. All rights reserved. +// http://code.google.com/p/ceres-solver/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 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/lapack.h" +#include "glog/logging.h" + +// C interface to the LAPACK Cholesky factorization and triangular solve. +extern "C" void dpotrf_(char* uplo, + int* n, + double* a, + int* lda, + int* info); + +extern "C" void dpotrs_(char* uplo, + int* n, + int* nrhs, + double* a, + int* lda, + double* b, + int* ldb, + int* info); + +extern "C" void dgels_(char* uplo, + int* m, + int* n, + int* nrhs, + double* a, + int* lda, + double* b, + int* ldb, + double* work, + int* lwork, + int* info); + + +namespace ceres { +namespace internal { + +int LAPACK::SolveInPlaceUsingCholesky(int num_rows, + const double* in_lhs, + double* rhs_and_solution) { +#ifdef CERES_NO_LAPACK + LOG(FATAL) << "Ceres was built without a BLAS library."; + return -1; +#else + char uplo = 'L'; + int n = num_rows; + int info = 0; + int nrhs = 1; + double* lhs = const_cast<double*>(in_lhs); + + dpotrf_(&uplo, &n, lhs, &n, &info); + if (info != 0) { + LOG(INFO) << "Cholesky factorization (dpotrf) failed: " << info; + return info; + } + + dpotrs_(&uplo, &n, &nrhs, lhs, &n, rhs_and_solution, &n, &info); + if (info != 0) { + LOG(INFO) << "Triangular solve (dpotrs) failed: " << info; + } + + return info; +#endif +}; + +int LAPACK::EstimateWorkSizeForQR(int num_rows, int num_cols) { +#ifdef CERES_NO_LAPACK + LOG(FATAL) << "Ceres was built without a LAPACK library."; + return -1; +#else + char trans = 'N'; + int nrhs = 1; + int lwork = -1; + double work; + int info = 0; + dgels_(&trans, + &num_rows, + &num_cols, + &nrhs, + NULL, + &num_rows, + NULL, + &num_rows, + &work, + &lwork, + &info); + + CHECK_EQ(info, 0); + return work; +#endif +} + +int LAPACK::SolveUsingQR(int num_rows, + int num_cols, + const double* in_lhs, + int work_size, + double* work, + double* rhs_and_solution) { +#ifdef CERES_NO_LAPACK + LOG(FATAL) << "Ceres was built without a LAPACK library."; + return -1; +#else + char trans = 'N'; + int m = num_rows; + int n = num_cols; + int nrhs = 1; + int lda = num_rows; + int ldb = num_rows; + int info = 0; + double* lhs = const_cast<double*>(in_lhs); + + dgels_(&trans, + &m, + &n, + &nrhs, + lhs, + &lda, + rhs_and_solution, + &ldb, + work, + &work_size, + &info); + + return info; +#endif +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/lapack.h b/internal/ceres/lapack.h new file mode 100644 index 0000000..4f3a88c --- /dev/null +++ b/internal/ceres/lapack.h @@ -0,0 +1,88 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2013 Google Inc. All rights reserved. +// http://code.google.com/p/ceres-solver/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 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_LAPACK_H_ +#define CERES_INTERNAL_LAPACK_H_ + +namespace ceres { +namespace internal { + +class LAPACK { + public: + // Solve + // + // lhs * solution = rhs + // + // using a Cholesky factorization. Here + // lhs is a symmetric positive definite matrix. It is assumed to be + // column major and only the lower triangular part of the matrix is + // referenced. + // + // This function uses the LAPACK dpotrf and dpotrs routines. + // + // The return value is zero if the solve is successful. + static int SolveInPlaceUsingCholesky(int num_rows, + const double* lhs, + double* rhs_and_solution); + + // The SolveUsingQR function requires a buffer for its temporary + // computation. This function given the size of the lhs matrix will + // return the size of the buffer needed. + static int EstimateWorkSizeForQR(int num_rows, int num_cols); + + // Solve + // + // lhs * solution = rhs + // + // using a dense QR factorization. lhs is an arbitrary (possibly + // rectangular) matrix with full column rank. + // + // work is an array of size work_size that this routine uses for its + // temporary storage. The optimal size of this array can be obtained + // by calling EstimateWorkSizeForQR. + // + // When calling, rhs_and_solution contains the rhs, and upon return + // the first num_col entries are the solution. + // + // This function uses the LAPACK dgels routine. + // + // The return value is zero if the solve is successful. + static int SolveUsingQR(int num_rows, + int num_cols, + const double* lhs, + int work_size, + double* work, + double* rhs_and_solution); +}; + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_LAPACK_H_ diff --git a/internal/ceres/line_search.cc b/internal/ceres/line_search.cc index 39618b5..8323896 100644 --- a/internal/ceres/line_search.cc +++ b/internal/ceres/line_search.cc @@ -112,7 +112,7 @@ void LineSearchFunction::Init(const Vector& position, direction_ = direction; } -bool LineSearchFunction::Evaluate(const double x, double* f, double* g) { +bool LineSearchFunction::Evaluate(double x, double* f, double* g) { scaled_direction_ = x * direction_; if (!evaluator_->Plus(position_.data(), scaled_direction_.data(), diff --git a/internal/ceres/line_search.h b/internal/ceres/line_search.h index e4836b2..5f24e9f 100644 --- a/internal/ceres/line_search.h +++ b/internal/ceres/line_search.h @@ -231,7 +231,7 @@ class LineSearchFunction : public LineSearch::Function { explicit LineSearchFunction(Evaluator* evaluator); virtual ~LineSearchFunction() {} void Init(const Vector& position, const Vector& direction); - virtual bool Evaluate(const double x, double* f, double* g); + virtual bool Evaluate(double x, double* f, double* g); double DirectionInfinityNorm() const; private: diff --git a/internal/ceres/linear_solver.h b/internal/ceres/linear_solver.h index 67bebe0..22691b3 100644 --- a/internal/ceres/linear_solver.h +++ b/internal/ceres/linear_solver.h @@ -74,7 +74,8 @@ class LinearSolver { Options() : type(SPARSE_NORMAL_CHOLESKY), preconditioner_type(JACOBI), - sparse_linear_algebra_library(SUITE_SPARSE), + dense_linear_algebra_library_type(EIGEN), + sparse_linear_algebra_library_type(SUITE_SPARSE), use_postordering(false), min_num_iterations(1), max_num_iterations(1), @@ -89,7 +90,8 @@ class LinearSolver { PreconditionerType preconditioner_type; - SparseLinearAlgebraLibraryType sparse_linear_algebra_library; + DenseLinearAlgebraLibraryType dense_linear_algebra_library_type; + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; // See solver.h for information about this flag. bool use_postordering; diff --git a/internal/ceres/miniglog/glog/logging.h b/internal/ceres/miniglog/glog/logging.h index 1fc137b..bab3191 100644 --- a/internal/ceres/miniglog/glog/logging.h +++ b/internal/ceres/miniglog/glog/logging.h @@ -1,100 +1,74 @@ -// Ceres Solver - A fast non-linear least squares minimizer -// Copyright 2011, 2012 Google Inc. All rights reserved. -// http://code.google.com/p/ceres-solver/ -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither the name of Google Inc. nor the names of its contributors may be -// used to endorse or promote products derived from this software without -// specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE -// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS -// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN -// CONTRACT, STRICT LIABILITY, OR TORT (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 2011 Google Inc. All Rights Reserved. // Author: settinger@google.com (Scott Ettinger) -// keir@google.com (Keir Mierle) -// -// Simplified Glog style logging with Android support. Supported macros in -// decreasing severity level per line: + +// Simplified Google3 style logging with Android support. +// Supported macros are : LOG(INFO), LOG(WARNING), LOG(ERROR), LOG(FATAL), +// and VLOG(n). // -// VLOG(2), VLOG(N) -// VLOG(1), -// LOG(INFO), VLOG(0), LG -// LOG(WARNING), -// LOG(ERROR), -// LOG(FATAL), +// Portions of this code are taken from the GLOG package. This code +// is only a small subset of the GLOG functionality. And like GLOG, +// higher levels are more verbose. // -// With VLOG(n), the output is directed to one of the 5 Android log levels: +// Notable differences from GLOG : // -// 2 - Verbose -// 1 - Debug -// 0 - Info -// -1 - Warning -// -2 - Error -// -3 - Fatal +// 1. lack of support for displaying unprintable characters and lack +// of stack trace information upon failure of the CHECK macros. +// 2. All output is tagged with the string "native". +// 3. While there is no runtime flag filtering logs (-v, -vmodule), the +// compile time define MAX_LOG_LEVEL can be used to silence any +// logging above the given level. // -// Any logging of level 2 and above is directed to the Verbose level. All -// Android log output is tagged with the string "native". +// -------------------------------- Usage ------------------------------------ +// Basic usage : +// LOG(<severity level>) acts as a c++ stream to the Android logcat output. +// e.g. LOG(INFO) << "Value of counter = " << counter; // -// If the symbol ANDROID is not defined, all output goes to std::cerr. -// This allows code to be built on a different system for debug. +// Valid severity levels include INFO, WARNING, ERROR, FATAL. +// The various severity levels are routed to the corresponding Android logcat +// output. +// LOG(FATAL) outputs to the log and then terminates. // -// Portions of this code are taken from the GLOG package. This code is only a -// small subset of the GLOG functionality. Notable differences from GLOG -// behavior include lack of support for displaying unprintable characters and -// lack of stack trace information upon failure of the CHECK macros. On -// non-Android systems, log output goes to std::cerr and is not written to a -// file. +// VLOG(<severity level>) can also be used. +// VLOG(n) output is directed to the Android logcat levels as follows : +// >=2 - Verbose +// 1 - Debug +// 0 - Info +// -1 - Warning +// -2 - Error +// <=-3 - Fatal +// Note that VLOG(FATAL) will terminate the program. // -// CHECK macros are defined to test for conditions within code. Any CHECK that -// fails will log the failure and terminate the application. +// CHECK macros are defined to test for conditions within code. Any CHECK +// that fails will log the failure and terminate the application. // e.g. CHECK_GE(3, 2) will pass while CHECK_GE(3, 4) will fail after logging // "Check failed 3 >= 4". +// The following CHECK macros are defined : // -// The following CHECK macros are defined: -// -// CHECK(condition) - fails if condition is false and logs condition. -// CHECK_NOTNULL(variable) - fails if the variable is NULL. +// CHECK(condition) - fails if condition is false and logs condition. +// CHECK_NOTNULL(variable) - fails if the variable is NULL. // // The following binary check macros are also defined : -// -// Macro Operator equivalent -// -------------------- ------------------- -// CHECK_EQ(val1, val2) val1 == val2 -// CHECK_NE(val1, val2) val1 != val2 -// CHECK_GT(val1, val2) val1 > val2 -// CHECK_GE(val1, val2) val1 >= val2 -// CHECK_LT(val1, val2) val1 < val2 -// CHECK_LE(val1, val2) val1 <= val2 +// Macro operator applied +// ------------------------------------------ +// CHECK_EQ(val1, val2) val1 == val2 +// CHECK_NE(val1, val2) val1 != val2 +// CHECK_GT(val1, val2) val1 > val2 +// CHECK_GE(val1, val2) val1 >= val2 +// CHECK_LT(val1, val2) val1 < val2 +// CHECK_LE(val1, val2) val1 <= val2 // // Debug only versions of all of the check macros are also defined. These // macros generate no code in a release build, but avoid unused variable // warnings / errors. -// -// To use the debug only versions, prepend a D to the normal check macros, e.g. -// DCHECK_EQ(a, b). +// To use the debug only versions, Prepend a D to the normal check macros. +// e.g. DCHECK_EQ(a, b); -#ifndef CERCES_INTERNAL_MINIGLOG_GLOG_LOGGING_H_ -#define CERCES_INTERNAL_MINIGLOG_GLOG_LOGGING_H_ +#ifndef MOBILE_BASE_LOGGING_H_ +#define MOBILE_BASE_LOGGING_H_ -#ifdef ANDROID +// Definitions for building on an Android system. #include <android/log.h> -#endif // ANDROID +#include <time.h> #include <algorithm> #include <iostream> @@ -120,29 +94,26 @@ const int WARNING = ::WARNING; const int ERROR = ::ERROR; const int FATAL = ::FATAL; -// Sink class used for integration with mock and test functions. If sinks are -// added, all log output is also sent to each sink through the send function. -// In this implementation, WaitTillSent() is called immediately after the send. +#ifdef ENABLE_LOG_SINKS + +// Sink class used for integration with mock and test functions. +// If sinks are added, all log output is also sent to each sink through +// the send function. In this implementation, WaitTillSent() is called +// immediately after the send. // This implementation is not thread safe. class LogSink { public: virtual ~LogSink() {} - virtual void send(LogSeverity severity, - const char* full_filename, - const char* base_filename, - int line, + virtual void send(LogSeverity severity, const char* full_filename, + const char* base_filename, int line, const struct tm* tm_time, - const char* message, - size_t message_len) = 0; + const char* message, size_t message_len) = 0; virtual void WaitTillSent() = 0; }; -// Global set of log sinks. The actual object is defined in logging.cc. -extern std::set<LogSink *> log_sinks_global; - -inline void InitGoogleLogging(char *argv) { - // Do nothing; this is ignored. -} +// Global set of log sinks. +// TODO(settinger): Move this into a .cc file. +static std::set<LogSink *> log_sinks_global; // Note: the Log sink functions are not thread safe. inline void AddLogSink(LogSink *sink) { @@ -153,16 +124,19 @@ inline void RemoveLogSink(LogSink *sink) { log_sinks_global.erase(sink); } +#endif // #ifdef ENABLE_LOG_SINKS + +inline void InitGoogleLogging(char *argv) {} + } // namespace google // ---------------------------- Logger Class -------------------------------- // Class created for each use of the logging macros. // The logger acts as a stream and routes the final stream contents to the -// Android logcat output at the proper filter level. If ANDROID is not -// defined, output is directed to std::cerr. This class should not +// Android logcat output at the proper filter level. This class should not // be directly instantiated in code, rather it should be invoked through the -// use of the log macros LG, LOG, or VLOG. +// use of the log macros LOG, or VLOG. class MessageLogger { public: MessageLogger(const char *file, int line, const char *tag, int severity) @@ -174,14 +148,17 @@ class MessageLogger { // Output the contents of the stream to the proper channel on destruction. ~MessageLogger() { +#ifdef MAX_LOG_LEVEL + if (severity_ > MAX_LOG_LEVEL && severity_ > FATAL) { + return; + } +#endif stream_ << "\n"; - -#ifdef ANDROID static const int android_log_levels[] = { ANDROID_LOG_FATAL, // LOG(FATAL) ANDROID_LOG_ERROR, // LOG(ERROR) ANDROID_LOG_WARN, // LOG(WARNING) - ANDROID_LOG_INFO, // LOG(INFO), LG, VLOG(0) + ANDROID_LOG_INFO, // LOG(INFO), VLOG(0) ANDROID_LOG_DEBUG, // VLOG(1) ANDROID_LOG_VERBOSE, // VLOG(2) .. VLOG(N) }; @@ -193,22 +170,22 @@ class MessageLogger { int android_log_level = android_log_levels[android_level_index]; // Output the log string the Android log at the appropriate level. - __android_log_print(android_log_level, tag_.c_str(), stream_.str().c_str()); + __android_log_write(android_log_level, tag_.c_str(), stream_.str().c_str()); // Indicate termination if needed. if (severity_ == FATAL) { - __android_log_print(ANDROID_LOG_FATAL, + __android_log_write(ANDROID_LOG_FATAL, tag_.c_str(), "terminating.\n"); } -#else - // If not building on Android, log all output to std::cerr. - std::cerr << stream_.str(); -#endif // ANDROID + +#ifdef ENABLE_LOG_SINKS LogToSinks(severity_); WaitForSinks(); +#endif // #ifdef ENABLE_LOG_SINKS + // Android logging at level FATAL does not terminate execution, so abort() // is still required to stop the program. if (severity_ == FATAL) { @@ -220,41 +197,41 @@ class MessageLogger { std::stringstream &stream() { return stream_; } private: +#ifdef ENABLE_LOG_SINKS + void LogToSinks(int severity) { time_t rawtime; - struct tm* timeinfo; + struct tm * timeinfo; - time (&rawtime); - timeinfo = localtime(&rawtime); - std::set<google::LogSink*>::iterator iter; + time ( &rawtime ); + timeinfo = localtime ( &rawtime ); + std::set<google::LogSink *>::iterator iter; // Send the log message to all sinks. for (iter = google::log_sinks_global.begin(); - iter != google::log_sinks_global.end(); ++iter) { + iter != google::log_sinks_global.end(); ++iter) (*iter)->send(severity, file_.c_str(), filename_only_.c_str(), line_, timeinfo, stream_.str().c_str(), stream_.str().size()); - } } void WaitForSinks() { - // TODO(settinger): Add locks for thread safety. + // TODO(settinger): add locks for thread safety. std::set<google::LogSink *>::iterator iter; - // Call WaitTillSent() for all sinks. for (iter = google::log_sinks_global.begin(); - iter != google::log_sinks_global.end(); ++iter) { + iter != google::log_sinks_global.end(); ++iter) (*iter)->WaitTillSent(); - } } +#endif // #ifdef ENABLE_LOG_SINKS + void StripBasename(const std::string &full_path, std::string *filename) { // TODO(settinger): add support for OS with different path separators. const char kSeparator = '/'; size_t pos = full_path.rfind(kSeparator); - if (pos != std::string::npos) { + if (pos != std::string::npos) *filename = full_path.substr(pos + 1, std::string::npos); - } else { + else *filename = full_path; - } } std::string file_; @@ -267,20 +244,6 @@ class MessageLogger { // ---------------------- Logging Macro definitions -------------------------- -#define LG MessageLogger((char *)__FILE__, __LINE__, "native", \ - INFO).stream() - -#define LOG(n) MessageLogger((char *)__FILE__, __LINE__, "native", \ - n).stream() - -#define VLOG(n) MessageLogger((char *)__FILE__, __LINE__, "native", \ - n).stream() - -// Currently, VLOG is always on. -#define VLOG_IS_ON(x) true - -// ---------------------------- CHECK helpers -------------------------------- - // This class is used to explicitly ignore values in the conditional // logging macros. This avoids compiler warnings like "value computed // is not used" and "statement has no effect". @@ -294,7 +257,40 @@ class LoggerVoidify { // Log only if condition is met. Otherwise evaluates to void. #define LOG_IF(severity, condition) \ - condition ? (void) 0 : LoggerVoidify() & LOG(severity) + !(condition) ? (void) 0 : LoggerVoidify() & \ + MessageLogger((char *)__FILE__, __LINE__, "native", severity).stream() + +// Log only if condition is NOT met. Otherwise evaluates to void. +#define LOG_IF_FALSE(severity, condition) LOG_IF(severity, !(condition)) + +// LG is a convenient shortcut for LOG(INFO). Its use is in new +// google3 code is discouraged and the following shortcut exists for +// backward compatibility with existing code. +#ifdef MAX_LOG_LEVEL +#define LOG(n) LOG_IF(n, n <= MAX_LOG_LEVEL) +#define VLOG(n) LOG_IF(n, n <= MAX_LOG_LEVEL) +#define LG LOG_IF(INFO, INFO <= MAX_LOG_LEVEL) +#else +#define LOG(n) MessageLogger((char *)__FILE__, __LINE__, "native", n).stream() +#define VLOG(n) MessageLogger((char *)__FILE__, __LINE__, "native", n).stream() +#define LG MessageLogger((char *)__FILE__, __LINE__, "native", INFO).stream() +#endif + +// Currently, VLOG is always on for levels below MAX_LOG_LEVEL. +#ifndef MAX_LOG_LEVEL +#define VLOG_IS_ON(x) (1) +#else +#define VLOG_IS_ON(x) (x <= MAX_LOG_LEVEL) +#endif + +#ifndef NDEBUG +#define DLOG LOG +#else +#define DLOG(severity) true ? (void) 0 : LoggerVoidify() & \ + MessageLogger((char *)__FILE__, __LINE__, "native", severity).stream() +#endif + +// ---------------------------- CHECK helpers -------------------------------- // Log a message and terminate. template<class T> @@ -306,16 +302,16 @@ void LogMessageFatal(const char *file, int line, const T &message) { // ---------------------------- CHECK macros --------------------------------- // Check for a given boolean condition. -#define CHECK(condition) LOG_IF(FATAL, condition) \ +#define CHECK(condition) LOG_IF_FALSE(FATAL, condition) \ << "Check failed: " #condition " " #ifndef NDEBUG // Debug only version of CHECK -#define DCHECK(condition) LOG_IF(FATAL, condition) \ +#define DCHECK(condition) LOG_IF_FALSE(FATAL, condition) \ << "Check failed: " #condition " " #else // Optimized version - generates no code. -#define DCHECK(condition) if (false) LOG_IF(FATAL, condition) \ +#define DCHECK(condition) if (false) LOG_IF_FALSE(FATAL, condition) \ << "Check failed: " #condition " " #endif // NDEBUG @@ -323,7 +319,7 @@ void LogMessageFatal(const char *file, int line, const T &message) { // Generic binary operator check macro. This should not be directly invoked, // instead use the binary comparison macros defined below. -#define CHECK_OP(val1, val2, op) LOG_IF(FATAL, (val1 op val2)) \ +#define CHECK_OP(val1, val2, op) LOG_IF_FALSE(FATAL, (val1 op val2)) \ << "Check failed: " #val1 " " #op " " #val2 " " // Check_op macro definitions @@ -388,4 +384,8 @@ T& CheckNotNull(const char *file, int line, const char *names, T& t) { CheckNotNull(__FILE__, __LINE__, "'" #val "' Must be non NULL", (val)) #endif // NDEBUG -#endif // CERCES_INTERNAL_MINIGLOG_GLOG_LOGGING_H_ +inline void PrintAndroid(const char *msg) { + __android_log_write(ANDROID_LOG_VERBOSE, "native", msg); +} + +#endif // MOBILE_BASE_LOGGING_H_ diff --git a/internal/ceres/partitioned_matrix_view.cc b/internal/ceres/partitioned_matrix_view.cc index 5dad438..59eaff8 100644 --- a/internal/ceres/partitioned_matrix_view.cc +++ b/internal/ceres/partitioned_matrix_view.cc @@ -35,10 +35,10 @@ #include <algorithm> #include <cstring> #include <vector> -#include "ceres/blas.h" #include "ceres/block_sparse_matrix.h" #include "ceres/block_structure.h" #include "ceres/internal/eigen.h" +#include "ceres/small_blas.h" #include "glog/logging.h" namespace ceres { diff --git a/internal/ceres/preconditioner.h b/internal/ceres/preconditioner.h index cb0a381..af64e3c 100644 --- a/internal/ceres/preconditioner.h +++ b/internal/ceres/preconditioner.h @@ -48,7 +48,7 @@ class Preconditioner : public LinearOperator { struct Options { Options() : type(JACOBI), - sparse_linear_algebra_library(SUITE_SPARSE), + sparse_linear_algebra_library_type(SUITE_SPARSE), num_threads(1), row_block_size(Eigen::Dynamic), e_block_size(Eigen::Dynamic), @@ -57,7 +57,7 @@ class Preconditioner : public LinearOperator { PreconditionerType type; - SparseLinearAlgebraLibraryType sparse_linear_algebra_library; + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; // If possible, how many threads the preconditioner can use. int num_threads; diff --git a/internal/ceres/program_evaluator.h b/internal/ceres/program_evaluator.h index 19c7541..8aa2a39 100644 --- a/internal/ceres/program_evaluator.h +++ b/internal/ceres/program_evaluator.h @@ -86,13 +86,13 @@ #include <map> #include <string> #include <vector> -#include "ceres/blas.h" #include "ceres/execution_summary.h" #include "ceres/internal/eigen.h" #include "ceres/internal/scoped_ptr.h" #include "ceres/parameter_block.h" #include "ceres/program.h" #include "ceres/residual_block.h" +#include "ceres/small_blas.h" namespace ceres { namespace internal { diff --git a/internal/ceres/residual_block.cc b/internal/ceres/residual_block.cc index 649f3f7..621082a 100644 --- a/internal/ceres/residual_block.cc +++ b/internal/ceres/residual_block.cc @@ -34,8 +34,6 @@ #include <algorithm> #include <cstddef> #include <vector> - -#include "ceres/blas.h" #include "ceres/corrector.h" #include "ceres/parameter_block.h" #include "ceres/residual_block_utils.h" @@ -44,6 +42,7 @@ #include "ceres/internal/fixed_array.h" #include "ceres/local_parameterization.h" #include "ceres/loss_function.h" +#include "ceres/small_blas.h" using Eigen::Dynamic; diff --git a/internal/ceres/schur_complement_solver.cc b/internal/ceres/schur_complement_solver.cc index 09f61d7..b192aa1 100644 --- a/internal/ceres/schur_complement_solver.cc +++ b/internal/ceres/schur_complement_solver.cc @@ -33,20 +33,18 @@ #include <set> #include <vector> -#ifndef CERES_NO_CXSPARSE -#include "cs.h" -#endif // CERES_NO_CXSPARSE - #include "Eigen/Dense" #include "ceres/block_random_access_dense_matrix.h" #include "ceres/block_random_access_matrix.h" #include "ceres/block_random_access_sparse_matrix.h" #include "ceres/block_sparse_matrix.h" #include "ceres/block_structure.h" +#include "ceres/cxsparse.h" #include "ceres/detect_structure.h" #include "ceres/internal/eigen.h" #include "ceres/internal/port.h" #include "ceres/internal/scoped_ptr.h" +#include "ceres/lapack.h" #include "ceres/linear_solver.h" #include "ceres/schur_complement_solver.h" #include "ceres/suitesparse.h" @@ -130,29 +128,31 @@ bool DenseSchurComplementSolver::SolveReducedLinearSystem(double* solution) { return true; } - // TODO(sameeragarwal): Add proper error handling; this completely ignores - // the quality of the solution to the solve. - VectorRef(solution, num_rows) = - ConstMatrixRef(m->values(), num_rows, num_rows) - .selfadjointView<Eigen::Upper>() - .ldlt() - .solve(ConstVectorRef(rhs(), num_rows)); + if (options().dense_linear_algebra_library_type == EIGEN) { + // TODO(sameeragarwal): Add proper error handling; this completely ignores + // the quality of the solution to the solve. + VectorRef(solution, num_rows) = + ConstMatrixRef(m->values(), num_rows, num_rows) + .selfadjointView<Eigen::Upper>() + .llt() + .solve(ConstVectorRef(rhs(), num_rows)); + return true; + } - return true; + VectorRef(solution, num_rows) = ConstVectorRef(rhs(), num_rows); + const int info = LAPACK::SolveInPlaceUsingCholesky(num_rows, + m->values(), + solution); + return (info == 0); } #if !defined(CERES_NO_SUITESPARSE) || !defined(CERES_NO_CXSPARE) SparseSchurComplementSolver::SparseSchurComplementSolver( const LinearSolver::Options& options) - : SchurComplementSolver(options) { -#ifndef CERES_NO_SUITESPARSE - factor_ = NULL; -#endif // CERES_NO_SUITESPARSE - -#ifndef CERES_NO_CXSPARSE - cxsparse_factor_ = NULL; -#endif // CERES_NO_CXSPARSE + : SchurComplementSolver(options), + factor_(NULL), + cxsparse_factor_(NULL) { } SparseSchurComplementSolver::~SparseSchurComplementSolver() { @@ -243,18 +243,18 @@ void SparseSchurComplementSolver::InitStorage( } bool SparseSchurComplementSolver::SolveReducedLinearSystem(double* solution) { - switch (options().sparse_linear_algebra_library) { + switch (options().sparse_linear_algebra_library_type) { case SUITE_SPARSE: return SolveReducedLinearSystemUsingSuiteSparse(solution); case CX_SPARSE: return SolveReducedLinearSystemUsingCXSparse(solution); default: LOG(FATAL) << "Unknown sparse linear algebra library : " - << options().sparse_linear_algebra_library; + << options().sparse_linear_algebra_library_type; } LOG(FATAL) << "Unknown sparse linear algebra library : " - << options().sparse_linear_algebra_library; + << options().sparse_linear_algebra_library_type; return false; } diff --git a/internal/ceres/schur_complement_solver.h b/internal/ceres/schur_complement_solver.h index 9525e37..b5a1c74 100644 --- a/internal/ceres/schur_complement_solver.h +++ b/internal/ceres/schur_complement_solver.h @@ -167,18 +167,14 @@ class SparseSchurComplementSolver : public SchurComplementSolver { // Size of the blocks in the Schur complement. vector<int> blocks_; -#ifndef CERES_NO_SUITESPARSE SuiteSparse ss_; // Symbolic factorization of the reduced linear system. Precomputed // once and reused in subsequent calls. cholmod_factor* factor_; -#endif // CERES_NO_SUITESPARSE -#ifndef CERES_NO_CXSPARSE CXSparse cxsparse_; // Cached factorization cs_dis* cxsparse_factor_; -#endif // CERES_NO_CXSPARSE CERES_DISALLOW_COPY_AND_ASSIGN(SparseSchurComplementSolver); }; diff --git a/internal/ceres/schur_complement_solver_test.cc b/internal/ceres/schur_complement_solver_test.cc index 206d4b5..d91c162 100644 --- a/internal/ceres/schur_complement_solver_test.cc +++ b/internal/ceres/schur_complement_solver_test.cc @@ -87,7 +87,8 @@ class SchurComplementSolverTest : public ::testing::Test { int problem_id, bool regularization, ceres::LinearSolverType linear_solver_type, - ceres::SparseLinearAlgebraLibraryType sparse_linear_algebra_library, + ceres::DenseLinearAlgebraLibraryType dense_linear_algebra_library_type, + ceres::SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type, bool use_postordering) { SetUpFromProblemId(problem_id); LinearSolver::Options options; @@ -95,7 +96,10 @@ class SchurComplementSolverTest : public ::testing::Test { options.elimination_groups.push_back( A->block_structure()->cols.size() - num_eliminate_blocks); options.type = linear_solver_type; - options.sparse_linear_algebra_library = sparse_linear_algebra_library; + options.dense_linear_algebra_library_type = + dense_linear_algebra_library_type; + options.sparse_linear_algebra_library_type = + sparse_linear_algebra_library_type; options.use_postordering = use_postordering; scoped_ptr<LinearSolver> solver(LinearSolver::Create(options)); @@ -131,53 +135,67 @@ class SchurComplementSolverTest : public ::testing::Test { scoped_array<double> sol_d; }; -TEST_F(SchurComplementSolverTest, DenseSchurWithSmallProblem) { - ComputeAndCompareSolutions(2, false, DENSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(2, true, DENSE_SCHUR, SUITE_SPARSE, true); +TEST_F(SchurComplementSolverTest, EigenBasedDenseSchurWithSmallProblem) { + ComputeAndCompareSolutions(2, false, DENSE_SCHUR, EIGEN, SUITE_SPARSE, true); + ComputeAndCompareSolutions(2, true, DENSE_SCHUR, EIGEN, SUITE_SPARSE, true); } -TEST_F(SchurComplementSolverTest, DenseSchurWithLargeProblem) { - ComputeAndCompareSolutions(3, false, DENSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(3, true, DENSE_SCHUR, SUITE_SPARSE, true); +TEST_F(SchurComplementSolverTest, EigenBasedDenseSchurWithLargeProblem) { + ComputeAndCompareSolutions(3, false, DENSE_SCHUR, EIGEN, SUITE_SPARSE, true); + ComputeAndCompareSolutions(3, true, DENSE_SCHUR, EIGEN, SUITE_SPARSE, true); } +#ifndef CERES_NO_LAPACK +TEST_F(SchurComplementSolverTest, LAPACKBasedDenseSchurWithSmallProblem) { + ComputeAndCompareSolutions(2, false, DENSE_SCHUR, LAPACK, SUITE_SPARSE, true); + ComputeAndCompareSolutions(2, true, DENSE_SCHUR, LAPACK, SUITE_SPARSE, true); +} + +TEST_F(SchurComplementSolverTest, LAPACKBasedDenseSchurWithLargeProblem) { + ComputeAndCompareSolutions(3, false, DENSE_SCHUR, LAPACK, SUITE_SPARSE, true); + ComputeAndCompareSolutions(3, true, DENSE_SCHUR, LAPACK, SUITE_SPARSE, true); +} +#endif + #ifndef CERES_NO_SUITESPARSE TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseSmallProblemNoPostOrdering) { - ComputeAndCompareSolutions(2, false, SPARSE_SCHUR, SUITE_SPARSE, false); - ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, SUITE_SPARSE, false); + ComputeAndCompareSolutions( + 2, false, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, false); + ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, false); } TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseSmallProblemPostOrdering) { - ComputeAndCompareSolutions(2, false, SPARSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, SUITE_SPARSE, true); + ComputeAndCompareSolutions(2, false, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, true); + ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, true); } TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseLargeProblemNoPostOrdering) { - ComputeAndCompareSolutions(3, false, SPARSE_SCHUR, SUITE_SPARSE, false); - ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, SUITE_SPARSE, false); + ComputeAndCompareSolutions( + 3, false, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, false); + ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, false); } TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseLargeProblemPostOrdering) { - ComputeAndCompareSolutions(3, false, SPARSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, SUITE_SPARSE, true); + ComputeAndCompareSolutions(3, false, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, true); + ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, EIGEN, SUITE_SPARSE, true); } #endif // CERES_NO_SUITESPARSE #ifndef CERES_NO_CXSPARSE TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseSmallProblem) { - ComputeAndCompareSolutions(2, false, SPARSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, SUITE_SPARSE, true); + ComputeAndCompareSolutions(2, false, SPARSE_SCHUR, EIGEN, CX_SPARSE, true); + ComputeAndCompareSolutions(2, true, SPARSE_SCHUR, EIGEN, CX_SPARSE, true); } TEST_F(SchurComplementSolverTest, SparseSchurWithSuiteSparseLargeProblem) { - ComputeAndCompareSolutions(3, false, SPARSE_SCHUR, SUITE_SPARSE, true); - ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, SUITE_SPARSE, true); + ComputeAndCompareSolutions(3, false, SPARSE_SCHUR, EIGEN, CX_SPARSE, true); + ComputeAndCompareSolutions(3, true, SPARSE_SCHUR, EIGEN, CX_SPARSE, true); } #endif // CERES_NO_CXSPARSE diff --git a/internal/ceres/schur_eliminator_impl.h b/internal/ceres/schur_eliminator_impl.h index f072c88..c09b7fb 100644 --- a/internal/ceres/schur_eliminator_impl.h +++ b/internal/ceres/schur_eliminator_impl.h @@ -51,8 +51,6 @@ #include <algorithm> #include <map> - -#include "ceres/blas.h" #include "ceres/block_random_access_matrix.h" #include "ceres/block_sparse_matrix.h" #include "ceres/block_structure.h" @@ -61,6 +59,7 @@ #include "ceres/internal/scoped_ptr.h" #include "ceres/map_util.h" #include "ceres/schur_eliminator.h" +#include "ceres/small_blas.h" #include "ceres/stl_util.h" #include "Eigen/Dense" #include "glog/logging.h" diff --git a/internal/ceres/schur_eliminator_test.cc b/internal/ceres/schur_eliminator_test.cc index a7e96ae..bed8f3a 100644 --- a/internal/ceres/schur_eliminator_test.cc +++ b/internal/ceres/schur_eliminator_test.cc @@ -112,7 +112,7 @@ class SchurEliminatorTest : public ::testing::Test { P.block(row, row, block_size, block_size) = P .block(row, row, block_size, block_size) - .ldlt() + .llt() .solve(Matrix::Identity(block_size, block_size)); row += block_size; } @@ -121,7 +121,7 @@ class SchurEliminatorTest : public ::testing::Test { .triangularView<Eigen::Upper>() = R - Q.transpose() * P * Q; rhs_expected = g.tail(schur_size) - Q.transpose() * P * g.head(num_eliminate_cols); - sol_expected = H.ldlt().solve(g); + sol_expected = H.llt().solve(g); } void EliminateSolveAndCompare(const VectorRef& diagonal, @@ -160,7 +160,7 @@ class SchurEliminatorTest : public ::testing::Test { Vector reduced_sol = lhs_ref .selfadjointView<Eigen::Upper>() - .ldlt() + .llt() .solve(rhs); // Solution to the linear least squares problem. diff --git a/internal/ceres/schur_jacobi_preconditioner.cc b/internal/ceres/schur_jacobi_preconditioner.cc index aa840c5..338df71 100644 --- a/internal/ceres/schur_jacobi_preconditioner.cc +++ b/internal/ceres/schur_jacobi_preconditioner.cc @@ -128,7 +128,7 @@ void SchurJacobiPreconditioner::RightMultiply(const double* x, VectorRef(y, block_size) = block .selfadjointView<Eigen::Upper>() - .ldlt() + .llt() .solve(ConstVectorRef(x, block_size)); x += block_size; diff --git a/internal/ceres/small_blas.h b/internal/ceres/small_blas.h new file mode 100644 index 0000000..e14e664 --- /dev/null +++ b/internal/ceres/small_blas.h @@ -0,0 +1,406 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2013 Google Inc. All rights reserved. +// http://code.google.com/p/ceres-solver/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 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) +// +// Simple blas functions for use in the Schur Eliminator. These are +// fairly basic implementations which already yield a significant +// speedup in the eliminator performance. + +#ifndef CERES_INTERNAL_SMALL_BLAS_H_ +#define CERES_INTERNAL_SMALL_BLAS_H_ + +#include "ceres/internal/eigen.h" +#include "glog/logging.h" + +namespace ceres { +namespace internal { + +// Remove the ".noalias()" annotation from the matrix matrix +// mutliplies to produce a correct build with the Android NDK, +// including versions 6, 7, 8, and 8b, when built with STLPort and the +// non-standalone toolchain (i.e. ndk-build). This appears to be a +// compiler bug; if the workaround is not in place, the line +// +// block.noalias() -= A * B; +// +// gets compiled to +// +// block.noalias() += A * B; +// +// which breaks schur elimination. Introducing a temporary by removing the +// .noalias() annotation causes the issue to disappear. Tracking this +// issue down was tricky, since the test suite doesn't run when built with +// the non-standalone toolchain. +// +// TODO(keir): Make a reproduction case for this and send it upstream. +#ifdef CERES_WORK_AROUND_ANDROID_NDK_COMPILER_BUG +#define CERES_MAYBE_NOALIAS +#else +#define CERES_MAYBE_NOALIAS .noalias() +#endif + +// The following three macros are used to share code and reduce +// template junk across the various GEMM variants. +#define CERES_GEMM_BEGIN(name) \ + template<int kRowA, int kColA, int kRowB, int kColB, int kOperation> \ + inline void name(const double* A, \ + const int num_row_a, \ + const int num_col_a, \ + const double* B, \ + const int num_row_b, \ + const int num_col_b, \ + double* C, \ + const int start_row_c, \ + const int start_col_c, \ + const int row_stride_c, \ + const int col_stride_c) + +#define CERES_GEMM_NAIVE_HEADER \ + DCHECK_GT(num_row_a, 0); \ + DCHECK_GT(num_col_a, 0); \ + DCHECK_GT(num_row_b, 0); \ + DCHECK_GT(num_col_b, 0); \ + DCHECK_GE(start_row_c, 0); \ + DCHECK_GE(start_col_c, 0); \ + DCHECK_GT(row_stride_c, 0); \ + DCHECK_GT(col_stride_c, 0); \ + DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); \ + DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); \ + DCHECK((kRowB == Eigen::Dynamic) || (kRowB == num_row_b)); \ + DCHECK((kColB == Eigen::Dynamic) || (kColB == num_col_b)); \ + const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); \ + const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); \ + const int NUM_ROW_B = (kColB != Eigen::Dynamic ? kRowB : num_row_b); \ + const int NUM_COL_B = (kColB != Eigen::Dynamic ? kColB : num_col_b); + +#define CERES_GEMM_EIGEN_HEADER \ + const typename EigenTypes<kRowA, kColA>::ConstMatrixRef \ + Aref(A, num_row_a, num_col_a); \ + const typename EigenTypes<kRowB, kColB>::ConstMatrixRef \ + Bref(B, num_row_b, num_col_b); \ + MatrixRef Cref(C, row_stride_c, col_stride_c); \ + +#define CERES_CALL_GEMM(name) \ + name<kRowA, kColA, kRowB, kColB, kOperation>( \ + A, num_row_a, num_col_a, \ + B, num_row_b, num_col_b, \ + C, start_row_c, start_col_c, row_stride_c, col_stride_c); + + +// For the matrix-matrix functions below, there are three variants for +// each functionality. Foo, FooNaive and FooEigen. Foo is the one to +// be called by the user. FooNaive is a basic loop based +// implementation and FooEigen uses Eigen's implementation. Foo +// chooses between FooNaive and FooEigen depending on how many of the +// template arguments are fixed at compile time. Currently, FooEigen +// is called if all matrix dimensions are compile time +// constants. FooNaive is called otherwise. This leads to the best +// performance currently. +// +// The MatrixMatrixMultiply variants compute: +// +// C op A * B; +// +// The MatrixTransposeMatrixMultiply variants compute: +// +// C op A' * B +// +// where op can be +=, -=, or =. +// +// The template parameters (kRowA, kColA, kRowB, kColB) allow +// specialization of the loop at compile time. If this information is +// not available, then Eigen::Dynamic should be used as the template +// argument. +// +// kOperation = 1 -> C += A * B +// kOperation = -1 -> C -= A * B +// kOperation = 0 -> C = A * B +// +// The functions can write into matrices C which are larger than the +// matrix A * B. This is done by specifying the true size of C via +// row_stride_c and col_stride_c, and then indicating where A * B +// should be written into by start_row_c and start_col_c. +// +// Graphically if row_stride_c = 10, col_stride_c = 12, start_row_c = +// 4 and start_col_c = 5, then if A = 3x2 and B = 2x4, we get +// +// ------------ +// ------------ +// ------------ +// ------------ +// -----xxxx--- +// -----xxxx--- +// -----xxxx--- +// ------------ +// ------------ +// ------------ +// +CERES_GEMM_BEGIN(MatrixMatrixMultiplyEigen) { + CERES_GEMM_EIGEN_HEADER + Eigen::Block<MatrixRef, kRowA, kColB> + block(Cref, start_row_c, start_col_c, num_row_a, num_col_b); + + if (kOperation > 0) { + block CERES_MAYBE_NOALIAS += Aref * Bref; + } else if (kOperation < 0) { + block CERES_MAYBE_NOALIAS -= Aref * Bref; + } else { + block CERES_MAYBE_NOALIAS = Aref * Bref; + } +} + +CERES_GEMM_BEGIN(MatrixMatrixMultiplyNaive) { + CERES_GEMM_NAIVE_HEADER + DCHECK_EQ(NUM_COL_A, NUM_ROW_B); + + const int NUM_ROW_C = NUM_ROW_A; + const int NUM_COL_C = NUM_COL_B; + DCHECK_LE(start_row_c + NUM_ROW_C, row_stride_c); + DCHECK_LE(start_col_c + NUM_COL_C, col_stride_c); + + for (int row = 0; row < NUM_ROW_C; ++row) { + for (int col = 0; col < NUM_COL_C; ++col) { + double tmp = 0.0; + for (int k = 0; k < NUM_COL_A; ++k) { + tmp += A[row * NUM_COL_A + k] * B[k * NUM_COL_B + col]; + } + + const int index = (row + start_row_c) * col_stride_c + start_col_c + col; + if (kOperation > 0) { + C[index] += tmp; + } else if (kOperation < 0) { + C[index] -= tmp; + } else { + C[index] = tmp; + } + } + } +} + +CERES_GEMM_BEGIN(MatrixMatrixMultiply) { +#ifdef CERES_NO_CUSTOM_BLAS + + CERES_CALL_GEMM(MatrixMatrixMultiplyEigen) + return; + +#else + + if (kRowA != Eigen::Dynamic && kColA != Eigen::Dynamic && + kRowB != Eigen::Dynamic && kColB != Eigen::Dynamic) { + CERES_CALL_GEMM(MatrixMatrixMultiplyEigen) + } else { + CERES_CALL_GEMM(MatrixMatrixMultiplyNaive) + } + +#endif +} + +CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiplyEigen) { + CERES_GEMM_EIGEN_HEADER + Eigen::Block<MatrixRef, kColA, kColB> block(Cref, + start_row_c, start_col_c, + num_col_a, num_col_b); + if (kOperation > 0) { + block CERES_MAYBE_NOALIAS += Aref.transpose() * Bref; + } else if (kOperation < 0) { + block CERES_MAYBE_NOALIAS -= Aref.transpose() * Bref; + } else { + block CERES_MAYBE_NOALIAS = Aref.transpose() * Bref; + } +} + +CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiplyNaive) { + CERES_GEMM_NAIVE_HEADER + DCHECK_EQ(NUM_ROW_A, NUM_ROW_B); + + const int NUM_ROW_C = NUM_COL_A; + const int NUM_COL_C = NUM_COL_B; + DCHECK_LE(start_row_c + NUM_ROW_C, row_stride_c); + DCHECK_LE(start_col_c + NUM_COL_C, col_stride_c); + + for (int row = 0; row < NUM_ROW_C; ++row) { + for (int col = 0; col < NUM_COL_C; ++col) { + double tmp = 0.0; + for (int k = 0; k < NUM_ROW_A; ++k) { + tmp += A[k * NUM_COL_A + row] * B[k * NUM_COL_B + col]; + } + + const int index = (row + start_row_c) * col_stride_c + start_col_c + col; + if (kOperation > 0) { + C[index]+= tmp; + } else if (kOperation < 0) { + C[index]-= tmp; + } else { + C[index]= tmp; + } + } + } +} + +CERES_GEMM_BEGIN(MatrixTransposeMatrixMultiply) { +#ifdef CERES_NO_CUSTOM_BLAS + + CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyEigen) + return; + +#else + + if (kRowA != Eigen::Dynamic && kColA != Eigen::Dynamic && + kRowB != Eigen::Dynamic && kColB != Eigen::Dynamic) { + CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyEigen) + } else { + CERES_CALL_GEMM(MatrixTransposeMatrixMultiplyNaive) + } + +#endif +} + +// Matrix-Vector multiplication +// +// c op A * b; +// +// where op can be +=, -=, or =. +// +// The template parameters (kRowA, kColA) allow specialization of the +// loop at compile time. If this information is not available, then +// Eigen::Dynamic should be used as the template argument. +// +// kOperation = 1 -> c += A' * b +// kOperation = -1 -> c -= A' * b +// kOperation = 0 -> c = A' * b +template<int kRowA, int kColA, int kOperation> +inline void MatrixVectorMultiply(const double* A, + const int num_row_a, + const int num_col_a, + const double* b, + double* c) { +#ifdef CERES_NO_CUSTOM_BLAS + const typename EigenTypes<kRowA, kColA>::ConstMatrixRef + Aref(A, num_row_a, num_col_a); + const typename EigenTypes<kColA>::ConstVectorRef bref(b, num_col_a); + typename EigenTypes<kRowA>::VectorRef cref(c, num_row_a); + + // lazyProduct works better than .noalias() for matrix-vector + // products. + if (kOperation > 0) { + cref += Aref.lazyProduct(bref); + } else if (kOperation < 0) { + cref -= Aref.lazyProduct(bref); + } else { + cref = Aref.lazyProduct(bref); + } +#else + + DCHECK_GT(num_row_a, 0); + DCHECK_GT(num_col_a, 0); + DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); + DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); + + const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); + const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); + + for (int row = 0; row < NUM_ROW_A; ++row) { + double tmp = 0.0; + for (int col = 0; col < NUM_COL_A; ++col) { + tmp += A[row * NUM_COL_A + col] * b[col]; + } + + if (kOperation > 0) { + c[row] += tmp; + } else if (kOperation < 0) { + c[row] -= tmp; + } else { + c[row] = tmp; + } + } +#endif // CERES_NO_CUSTOM_BLAS +} + +// Similar to MatrixVectorMultiply, except that A is transposed, i.e., +// +// c op A' * b; +template<int kRowA, int kColA, int kOperation> +inline void MatrixTransposeVectorMultiply(const double* A, + const int num_row_a, + const int num_col_a, + const double* b, + double* c) { +#ifdef CERES_NO_CUSTOM_BLAS + const typename EigenTypes<kRowA, kColA>::ConstMatrixRef + Aref(A, num_row_a, num_col_a); + const typename EigenTypes<kRowA>::ConstVectorRef bref(b, num_row_a); + typename EigenTypes<kColA>::VectorRef cref(c, num_col_a); + + // lazyProduct works better than .noalias() for matrix-vector + // products. + if (kOperation > 0) { + cref += Aref.transpose().lazyProduct(bref); + } else if (kOperation < 0) { + cref -= Aref.transpose().lazyProduct(bref); + } else { + cref = Aref.transpose().lazyProduct(bref); + } +#else + + DCHECK_GT(num_row_a, 0); + DCHECK_GT(num_col_a, 0); + DCHECK((kRowA == Eigen::Dynamic) || (kRowA == num_row_a)); + DCHECK((kColA == Eigen::Dynamic) || (kColA == num_col_a)); + + const int NUM_ROW_A = (kRowA != Eigen::Dynamic ? kRowA : num_row_a); + const int NUM_COL_A = (kColA != Eigen::Dynamic ? kColA : num_col_a); + + for (int row = 0; row < NUM_COL_A; ++row) { + double tmp = 0.0; + for (int col = 0; col < NUM_ROW_A; ++col) { + tmp += A[col * NUM_COL_A + row] * b[col]; + } + + if (kOperation > 0) { + c[row] += tmp; + } else if (kOperation < 0) { + c[row] -= tmp; + } else { + c[row] = tmp; + } + } +#endif // CERES_NO_CUSTOM_BLAS +} + + +#undef CERES_MAYBE_NOALIAS +#undef CERES_GEMM_BEGIN +#undef CERES_GEMM_EIGEN_HEADER +#undef CERES_GEMM_NAIVE_HEADER +#undef CERES_CALL_GEMM + +} // namespace internal +} // namespace ceres + +#endif // CERES_INTERNAL_SMALL_BLAS_H_ diff --git a/internal/ceres/small_blas_test.cc b/internal/ceres/small_blas_test.cc new file mode 100644 index 0000000..b8b5bc5 --- /dev/null +++ b/internal/ceres/small_blas_test.cc @@ -0,0 +1,303 @@ +// Ceres Solver - A fast non-linear least squares minimizer +// Copyright 2013 Google Inc. All rights reserved. +// http://code.google.com/p/ceres-solver/ +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are met: +// +// * Redistributions of source code must retain the above copyright notice, +// this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above copyright notice, +// this list of conditions and the following disclaimer in the documentation +// and/or other materials provided with the distribution. +// * Neither the name of Google Inc. nor the names of its contributors may be +// used to endorse or promote products derived from this software without +// specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +// AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +// ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE +// LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +// CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +// INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 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/small_blas.h" + +#include "gtest/gtest.h" +#include "ceres/internal/eigen.h" + +namespace ceres { +namespace internal { + +TEST(BLAS, MatrixMatrixMultiply) { + const double kTolerance = 1e-16; + const int kRowA = 3; + const int kColA = 5; + Matrix A(kRowA, kColA); + A.setOnes(); + + const int kRowB = 5; + const int kColB = 7; + Matrix B(kRowB, kColB); + B.setOnes(); + + for (int row_stride_c = kRowA; row_stride_c < 3 * kRowA; ++row_stride_c) { + for (int col_stride_c = kColB; col_stride_c < 3 * kColB; ++col_stride_c) { + Matrix C(row_stride_c, col_stride_c); + C.setOnes(); + + Matrix C_plus = C; + Matrix C_minus = C; + Matrix C_assign = C; + + Matrix C_plus_ref = C; + Matrix C_minus_ref = C; + Matrix C_assign_ref = C; + for (int start_row_c = 0; start_row_c + kRowA < row_stride_c; ++start_row_c) { + for (int start_col_c = 0; start_col_c + kColB < col_stride_c; ++start_col_c) { + C_plus_ref.block(start_row_c, start_col_c, kRowA, kColB) += + A * B; + + MatrixMatrixMultiply<kRowA, kColA, kRowB, kColB, 1>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_plus.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_plus_ref - C_plus).norm(), 0.0, kTolerance) + << "C += A * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_plus_ref << "\n" + << "C: \n" << C_plus; + + + C_minus_ref.block(start_row_c, start_col_c, kRowA, kColB) -= + A * B; + + MatrixMatrixMultiply<kRowA, kColA, kRowB, kColB, -1>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_minus.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_minus_ref - C_minus).norm(), 0.0, kTolerance) + << "C -= A * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_minus_ref << "\n" + << "C: \n" << C_minus; + + C_assign_ref.block(start_row_c, start_col_c, kRowA, kColB) = + A * B; + + MatrixMatrixMultiply<kRowA, kColA, kRowB, kColB, 0>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_assign.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_assign_ref - C_assign).norm(), 0.0, kTolerance) + << "C = A * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_assign_ref << "\n" + << "C: \n" << C_assign; + } + } + } + } +} + +TEST(BLAS, MatrixTransposeMatrixMultiply) { + const double kTolerance = 1e-16; + const int kRowA = 5; + const int kColA = 3; + Matrix A(kRowA, kColA); + A.setOnes(); + + const int kRowB = 5; + const int kColB = 7; + Matrix B(kRowB, kColB); + B.setOnes(); + + for (int row_stride_c = kColA; row_stride_c < 3 * kColA; ++row_stride_c) { + for (int col_stride_c = kColB; col_stride_c < 3 * kColB; ++col_stride_c) { + Matrix C(row_stride_c, col_stride_c); + C.setOnes(); + + Matrix C_plus = C; + Matrix C_minus = C; + Matrix C_assign = C; + + Matrix C_plus_ref = C; + Matrix C_minus_ref = C; + Matrix C_assign_ref = C; + for (int start_row_c = 0; start_row_c + kColA < row_stride_c; ++start_row_c) { + for (int start_col_c = 0; start_col_c + kColB < col_stride_c; ++start_col_c) { + C_plus_ref.block(start_row_c, start_col_c, kColA, kColB) += + A.transpose() * B; + + MatrixTransposeMatrixMultiply<kRowA, kColA, kRowB, kColB, 1>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_plus.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_plus_ref - C_plus).norm(), 0.0, kTolerance) + << "C += A' * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_plus_ref << "\n" + << "C: \n" << C_plus; + + C_minus_ref.block(start_row_c, start_col_c, kColA, kColB) -= + A.transpose() * B; + + MatrixTransposeMatrixMultiply<kRowA, kColA, kRowB, kColB, -1>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_minus.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_minus_ref - C_minus).norm(), 0.0, kTolerance) + << "C -= A' * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_minus_ref << "\n" + << "C: \n" << C_minus; + + C_assign_ref.block(start_row_c, start_col_c, kColA, kColB) = + A.transpose() * B; + + MatrixTransposeMatrixMultiply<kRowA, kColA, kRowB, kColB, 0>( + A.data(), kRowA, kColA, + B.data(), kRowB, kColB, + C_assign.data(), start_row_c, start_col_c, row_stride_c, col_stride_c); + + EXPECT_NEAR((C_assign_ref - C_assign).norm(), 0.0, kTolerance) + << "C = A' * B \n" + << "row_stride_c : " << row_stride_c << "\n" + << "col_stride_c : " << col_stride_c << "\n" + << "start_row_c : " << start_row_c << "\n" + << "start_col_c : " << start_col_c << "\n" + << "Cref : \n" << C_assign_ref << "\n" + << "C: \n" << C_assign; + } + } + } + } +} + +TEST(BLAS, MatrixVectorMultiply) { + const double kTolerance = 1e-16; + const int kRowA = 5; + const int kColA = 3; + Matrix A(kRowA, kColA); + A.setOnes(); + + Vector b(kColA); + b.setOnes(); + + Vector c(kRowA); + c.setOnes(); + + Vector c_plus = c; + Vector c_minus = c; + Vector c_assign = c; + + Vector c_plus_ref = c; + Vector c_minus_ref = c; + Vector c_assign_ref = c; + + c_plus_ref += A * b; + MatrixVectorMultiply<kRowA, kColA, 1>(A.data(), kRowA, kColA, + b.data(), + c_plus.data()); + EXPECT_NEAR((c_plus_ref - c_plus).norm(), 0.0, kTolerance) + << "c += A * b \n" + << "c_ref : \n" << c_plus_ref << "\n" + << "c: \n" << c_plus; + + c_minus_ref -= A * b; + MatrixVectorMultiply<kRowA, kColA, -1>(A.data(), kRowA, kColA, + b.data(), + c_minus.data()); + EXPECT_NEAR((c_minus_ref - c_minus).norm(), 0.0, kTolerance) + << "c += A * b \n" + << "c_ref : \n" << c_minus_ref << "\n" + << "c: \n" << c_minus; + + c_assign_ref = A * b; + MatrixVectorMultiply<kRowA, kColA, 0>(A.data(), kRowA, kColA, + b.data(), + c_assign.data()); + EXPECT_NEAR((c_assign_ref - c_assign).norm(), 0.0, kTolerance) + << "c += A * b \n" + << "c_ref : \n" << c_assign_ref << "\n" + << "c: \n" << c_assign; +} + +TEST(BLAS, MatrixTransposeVectorMultiply) { + const double kTolerance = 1e-16; + const int kRowA = 5; + const int kColA = 3; + Matrix A(kRowA, kColA); + A.setRandom(); + + Vector b(kRowA); + b.setRandom(); + + Vector c(kColA); + c.setOnes(); + + Vector c_plus = c; + Vector c_minus = c; + Vector c_assign = c; + + Vector c_plus_ref = c; + Vector c_minus_ref = c; + Vector c_assign_ref = c; + + c_plus_ref += A.transpose() * b; + MatrixTransposeVectorMultiply<kRowA, kColA, 1>(A.data(), kRowA, kColA, + b.data(), + c_plus.data()); + EXPECT_NEAR((c_plus_ref - c_plus).norm(), 0.0, kTolerance) + << "c += A' * b \n" + << "c_ref : \n" << c_plus_ref << "\n" + << "c: \n" << c_plus; + + c_minus_ref -= A.transpose() * b; + MatrixTransposeVectorMultiply<kRowA, kColA, -1>(A.data(), kRowA, kColA, + b.data(), + c_minus.data()); + EXPECT_NEAR((c_minus_ref - c_minus).norm(), 0.0, kTolerance) + << "c += A' * b \n" + << "c_ref : \n" << c_minus_ref << "\n" + << "c: \n" << c_minus; + + c_assign_ref = A.transpose() * b; + MatrixTransposeVectorMultiply<kRowA, kColA, 0>(A.data(), kRowA, kColA, + b.data(), + c_assign.data()); + EXPECT_NEAR((c_assign_ref - c_assign).norm(), 0.0, kTolerance) + << "c += A' * b \n" + << "c_ref : \n" << c_assign_ref << "\n" + << "c: \n" << c_assign; +} + +} // namespace internal +} // namespace ceres diff --git a/internal/ceres/solver.cc b/internal/ceres/solver.cc index 5d8447d..3b67746 100644 --- a/internal/ceres/solver.cc +++ b/internal/ceres/solver.cc @@ -120,7 +120,8 @@ Solver::Summary::Summary() inner_iterations_used(false), preconditioner_type(IDENTITY), trust_region_strategy_type(LEVENBERG_MARQUARDT), - sparse_linear_algebra_library(SUITE_SPARSE), + dense_linear_algebra_library_type(EIGEN), + sparse_linear_algebra_library_type(SUITE_SPARSE), line_search_direction_type(LBFGS), line_search_type(ARMIJO) { } @@ -192,6 +193,15 @@ string Solver::Summary::FullReport() const { // TRUST_SEARCH HEADER StringAppendF(&report, "\nMinimizer %19s\n", "TRUST_REGION"); + + if (linear_solver_type_used == DENSE_NORMAL_CHOLESKY || + linear_solver_type_used == DENSE_SCHUR || + linear_solver_type_used == DENSE_QR) { + StringAppendF(&report, "\nDense linear algebra library %15s\n", + DenseLinearAlgebraLibraryTypeToString( + dense_linear_algebra_library_type)); + } + if (linear_solver_type_used == SPARSE_NORMAL_CHOLESKY || linear_solver_type_used == SPARSE_SCHUR || (linear_solver_type_used == ITERATIVE_SCHUR && @@ -199,7 +209,7 @@ string Solver::Summary::FullReport() const { preconditioner_type == CLUSTER_TRIDIAGONAL))) { StringAppendF(&report, "\nSparse linear algebra library %15s\n", SparseLinearAlgebraLibraryTypeToString( - sparse_linear_algebra_library)); + sparse_linear_algebra_library_type)); } StringAppendF(&report, "Trust region strategy %19s", diff --git a/internal/ceres/solver_impl.cc b/internal/ceres/solver_impl.cc index d6ef731..83faa05 100644 --- a/internal/ceres/solver_impl.cc +++ b/internal/ceres/solver_impl.cc @@ -317,6 +317,16 @@ void SolverImpl::LineSearchMinimize( void SolverImpl::Solve(const Solver::Options& options, ProblemImpl* problem_impl, Solver::Summary* summary) { + VLOG(2) << "Initial problem: " + << problem_impl->NumParameterBlocks() + << " parameter blocks, " + << problem_impl->NumParameters() + << " parameters, " + << problem_impl->NumResidualBlocks() + << " residual blocks, " + << problem_impl->NumResiduals() + << " residuals."; + if (options.minimizer_type == TRUST_REGION) { TrustRegionSolve(options, problem_impl, summary); } else { @@ -506,8 +516,10 @@ void SolverImpl::TrustRegionSolve(const Solver::Options& original_options, original_options.num_linear_solver_threads; summary->num_linear_solver_threads_used = options.num_linear_solver_threads; - summary->sparse_linear_algebra_library = - options.sparse_linear_algebra_library; + summary->dense_linear_algebra_library_type = + options.dense_linear_algebra_library_type; + summary->sparse_linear_algebra_library_type = + options.sparse_linear_algebra_library_type; summary->trust_region_strategy_type = options.trust_region_strategy_type; summary->dogleg_type = options.dogleg_type; @@ -1067,6 +1079,16 @@ Program* SolverImpl::CreateReducedProgram(Solver::Options* options, return NULL; } + VLOG(2) << "Reduced problem: " + << transformed_program->NumParameterBlocks() + << " parameter blocks, " + << transformed_program->NumParameters() + << " parameters, " + << transformed_program->NumResidualBlocks() + << " residual blocks, " + << transformed_program->NumResiduals() + << " residuals."; + if (transformed_program->NumParameterBlocks() == 0) { LOG(WARNING) << "No varying parameter blocks to optimize; " << "bailing early."; @@ -1092,7 +1114,7 @@ Program* SolverImpl::CreateReducedProgram(Solver::Options* options, if (IsSchurType(options->linear_solver_type)) { if (!ReorderProgramForSchurTypeLinearSolver( options->linear_solver_type, - options->sparse_linear_algebra_library, + options->sparse_linear_algebra_library_type, problem_impl->parameter_map(), linear_solver_ordering, transformed_program.get(), @@ -1104,7 +1126,7 @@ Program* SolverImpl::CreateReducedProgram(Solver::Options* options, if (options->linear_solver_type == SPARSE_NORMAL_CHOLESKY) { if (!ReorderProgramForSparseNormalCholesky( - options->sparse_linear_algebra_library, + options->sparse_linear_algebra_library_type, linear_solver_ordering, transformed_program.get(), error)) { @@ -1134,9 +1156,32 @@ LinearSolver* SolverImpl::CreateLinearSolver(Solver::Options* options, } } +#ifdef CERES_NO_LAPACK + if (options->linear_solver_type == DENSE_NORMAL_CHOLESKY && + options->dense_linear_algebra_library_type == LAPACK) { + *error = "Can't use DENSE_NORMAL_CHOLESKY with LAPACK because " + "LAPACK was not enabled when Ceres was built."; + return NULL; + } + + if (options->linear_solver_type == DENSE_QR && + options->dense_linear_algebra_library_type == LAPACK) { + *error = "Can't use DENSE_QR with LAPACK because " + "LAPACK was not enabled when Ceres was built."; + return NULL; + } + + if (options->linear_solver_type == DENSE_SCHUR && + options->dense_linear_algebra_library_type == LAPACK) { + *error = "Can't use DENSE_SCHUR with LAPACK because " + "LAPACK was not enabled when Ceres was built."; + return NULL; + } +#endif + #ifdef CERES_NO_SUITESPARSE if (options->linear_solver_type == SPARSE_NORMAL_CHOLESKY && - options->sparse_linear_algebra_library == SUITE_SPARSE) { + options->sparse_linear_algebra_library_type == SUITE_SPARSE) { *error = "Can't use SPARSE_NORMAL_CHOLESKY with SUITESPARSE because " "SuiteSparse was not enabled when Ceres was built."; return NULL; @@ -1157,7 +1202,7 @@ LinearSolver* SolverImpl::CreateLinearSolver(Solver::Options* options, #ifdef CERES_NO_CXSPARSE if (options->linear_solver_type == SPARSE_NORMAL_CHOLESKY && - options->sparse_linear_algebra_library == CX_SPARSE) { + options->sparse_linear_algebra_library_type == CX_SPARSE) { *error = "Can't use SPARSE_NORMAL_CHOLESKY with CXSPARSE because " "CXSparse was not enabled when Ceres was built."; return NULL; @@ -1194,8 +1239,10 @@ LinearSolver* SolverImpl::CreateLinearSolver(Solver::Options* options, options->max_linear_solver_iterations; linear_solver_options.type = options->linear_solver_type; linear_solver_options.preconditioner_type = options->preconditioner_type; - linear_solver_options.sparse_linear_algebra_library = - options->sparse_linear_algebra_library; + linear_solver_options.sparse_linear_algebra_library_type = + options->sparse_linear_algebra_library_type; + linear_solver_options.dense_linear_algebra_library_type = + options->dense_linear_algebra_library_type; linear_solver_options.use_postordering = options->use_postordering; // Ignore user's postordering preferences and force it to be true if @@ -1204,7 +1251,7 @@ LinearSolver* SolverImpl::CreateLinearSolver(Solver::Options* options, // done. #if !defined(CERES_NO_SUITESPARSE) && defined(CERES_NO_CAMD) if (IsSchurType(linear_solver_options.type) && - linear_solver_options.sparse_linear_algebra_library == SUITE_SPARSE) { + options->sparse_linear_algebra_library_type == SUITE_SPARSE) { linear_solver_options.use_postordering = true; } #endif @@ -1590,6 +1637,11 @@ bool SolverImpl::ReorderProgramForSchurTypeLinearSolver( parameter_blocks[i]->mutable_user_state())); } + // Renumber the entries of constraints to be contiguous integers + // as camd requires that the group ids be in the range [0, + // parameter_blocks.size() - 1]. + SolverImpl::CompactifyArray(&constraints); + // Set the offsets and index for CreateJacobianSparsityTranspose. program->SetParameterOffsetsAndIndex(); // Compute a block sparse presentation of J'. @@ -1713,5 +1765,20 @@ bool SolverImpl::ReorderProgramForSparseNormalCholesky( return true; } +void SolverImpl::CompactifyArray(vector<int>* array_ptr) { + vector<int>& array = *array_ptr; + const set<int> unique_group_ids(array.begin(), array.end()); + map<int, int> group_id_map; + for (set<int>::const_iterator it = unique_group_ids.begin(); + it != unique_group_ids.end(); + ++it) { + InsertOrDie(&group_id_map, *it, group_id_map.size()); + } + + for (int i = 0; i < array.size(); ++i) { + array[i] = group_id_map[array[i]]; + } +} + } // namespace internal } // namespace ceres diff --git a/internal/ceres/solver_impl.h b/internal/ceres/solver_impl.h index ebfb813..2b7ca3e 100644 --- a/internal/ceres/solver_impl.h +++ b/internal/ceres/solver_impl.h @@ -208,6 +208,13 @@ class SolverImpl { ParameterBlockOrdering* parameter_block_ordering, Program* program, string* error); + + // array contains a list of (possibly repeating) non-negative + // integers. Let us assume that we have constructed another array + // `p` by sorting and uniqueing the entries of array. + // CompactifyArray replaces each entry in "array" with its position + // in `p`. + static void CompactifyArray(vector<int>* array); }; } // namespace internal diff --git a/internal/ceres/solver_impl_test.cc b/internal/ceres/solver_impl_test.cc index d81858c..583ef4e 100644 --- a/internal/ceres/solver_impl_test.cc +++ b/internal/ceres/solver_impl_test.cc @@ -592,7 +592,7 @@ TEST(SolverImpl, CreateLinearSolverNormalOperation) { #ifndef CERES_NO_SUITESPARSE options.linear_solver_type = SPARSE_NORMAL_CHOLESKY; - options.sparse_linear_algebra_library = SUITE_SPARSE; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; solver.reset(SolverImpl::CreateLinearSolver(&options, &error)); EXPECT_EQ(options.linear_solver_type, SPARSE_NORMAL_CHOLESKY); EXPECT_TRUE(solver.get() != NULL); @@ -600,7 +600,7 @@ TEST(SolverImpl, CreateLinearSolverNormalOperation) { #ifndef CERES_NO_CXSPARSE options.linear_solver_type = SPARSE_NORMAL_CHOLESKY; - options.sparse_linear_algebra_library = CX_SPARSE; + options.sparse_linear_algebra_library_type = CX_SPARSE; solver.reset(SolverImpl::CreateLinearSolver(&options, &error)); EXPECT_EQ(options.linear_solver_type, SPARSE_NORMAL_CHOLESKY); EXPECT_TRUE(solver.get() != NULL); @@ -991,5 +991,52 @@ TEST(SolverImpl, ReallocationInCreateJacobianBlockSparsityTranspose) { EXPECT_EQ((expected_dense_jacobian - actual_dense_jacobian).norm(), 0.0); } +TEST(CompactifyArray, ContiguousEntries) { + vector<int> array; + array.push_back(0); + array.push_back(1); + vector<int> expected = array; + SolverImpl::CompactifyArray(&array); + EXPECT_EQ(array, expected); + array.clear(); + + array.push_back(1); + array.push_back(0); + expected = array; + SolverImpl::CompactifyArray(&array); + EXPECT_EQ(array, expected); +} + +TEST(CompactifyArray, NonContiguousEntries) { + vector<int> array; + array.push_back(0); + array.push_back(2); + vector<int> expected; + expected.push_back(0); + expected.push_back(1); + SolverImpl::CompactifyArray(&array); + EXPECT_EQ(array, expected); +} + +TEST(CompactifyArray, NonContiguousRepeatingEntries) { + vector<int> 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<int> 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); + + SolverImpl::CompactifyArray(&array); + EXPECT_EQ(array, expected); +} + } // namespace internal } // namespace ceres diff --git a/internal/ceres/sparse_normal_cholesky_solver.cc b/internal/ceres/sparse_normal_cholesky_solver.cc index 9601142..f1a5237 100644 --- a/internal/ceres/sparse_normal_cholesky_solver.cc +++ b/internal/ceres/sparse_normal_cholesky_solver.cc @@ -36,11 +36,8 @@ #include <cstring> #include <ctime> -#ifndef CERES_NO_CXSPARSE -#include "cs.h" -#endif - #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" @@ -54,14 +51,9 @@ namespace internal { SparseNormalCholeskySolver::SparseNormalCholeskySolver( const LinearSolver::Options& options) - : options_(options) { -#ifndef CERES_NO_SUITESPARSE - factor_ = NULL; -#endif - -#ifndef CERES_NO_CXSPARSE - cxsparse_factor_ = NULL; -#endif // CERES_NO_CXSPARSE + : factor_(NULL), + cxsparse_factor_(NULL), + options_(options) { } SparseNormalCholeskySolver::~SparseNormalCholeskySolver() { @@ -85,18 +77,18 @@ LinearSolver::Summary SparseNormalCholeskySolver::SolveImpl( const double* b, const LinearSolver::PerSolveOptions& per_solve_options, double * x) { - switch (options_.sparse_linear_algebra_library) { + switch (options_.sparse_linear_algebra_library_type) { case SUITE_SPARSE: return SolveImplUsingSuiteSparse(A, b, per_solve_options, x); case CX_SPARSE: return SolveImplUsingCXSparse(A, b, per_solve_options, x); default: LOG(FATAL) << "Unknown sparse linear algebra library : " - << options_.sparse_linear_algebra_library; + << options_.sparse_linear_algebra_library_type; } LOG(FATAL) << "Unknown sparse linear algebra library : " - << options_.sparse_linear_algebra_library; + << options_.sparse_linear_algebra_library_type; return LinearSolver::Summary(); } diff --git a/internal/ceres/sparse_normal_cholesky_solver.h b/internal/ceres/sparse_normal_cholesky_solver.h index ebb32e6..61111b4 100644 --- a/internal/ceres/sparse_normal_cholesky_solver.h +++ b/internal/ceres/sparse_normal_cholesky_solver.h @@ -73,17 +73,13 @@ class SparseNormalCholeskySolver : public CompressedRowSparseMatrixSolver { const LinearSolver::PerSolveOptions& options, double* x); -#ifndef CERES_NO_SUITESPARSE SuiteSparse ss_; // Cached factorization cholmod_factor* factor_; -#endif // CERES_NO_SUITESPARSE -#ifndef CERES_NO_CXSPARSE CXSparse cxsparse_; // Cached factorization cs_dis* cxsparse_factor_; -#endif // CERES_NO_CXSPARSE const LinearSolver::Options options_; CERES_DISALLOW_COPY_AND_ASSIGN(SparseNormalCholeskySolver); diff --git a/internal/ceres/suitesparse.h b/internal/ceres/suitesparse.h index 8a5b0a8..16f298e 100644 --- a/internal/ceres/suitesparse.h +++ b/internal/ceres/suitesparse.h @@ -43,6 +43,7 @@ #include "ceres/internal/port.h" #include "cholmod.h" #include "glog/logging.h" +#include "SuiteSparseQR.hpp" // Before SuiteSparse version 4.2.0, cholmod_camd was only enabled // if SuiteSparse was compiled with Metis support. This makes @@ -58,6 +59,14 @@ #define CERES_NO_CAMD #endif +// UF_long is deprecated but SuiteSparse_long is only available in +// newer versions of SuiteSparse. So for older versions of +// SuiteSparse, we define SuiteSparse_long to be the same as UF_long, +// which is what recent versions of SuiteSparse do anyways. +#ifndef SuiteSparse_long +#define SuiteSparse_long UF_long +#endif + namespace ceres { namespace internal { @@ -261,6 +270,11 @@ class SuiteSparse { } // namespace internal } // namespace ceres +#else // CERES_NO_SUITESPARSE + +class SuiteSparse {}; +typedef void cholmod_factor; + #endif // CERES_NO_SUITESPARSE #endif // CERES_INTERNAL_SUITESPARSE_H_ diff --git a/internal/ceres/system_test.cc b/internal/ceres/system_test.cc index 095b51e..7b0e02d 100644 --- a/internal/ceres/system_test.cc +++ b/internal/ceres/system_test.cc @@ -64,21 +64,21 @@ const bool kUserOrdering = false; // Struct used for configuring the solver. struct SolverConfig { SolverConfig(LinearSolverType linear_solver_type, - SparseLinearAlgebraLibraryType sparse_linear_algebra_library, + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type, bool use_automatic_ordering) : linear_solver_type(linear_solver_type), - sparse_linear_algebra_library(sparse_linear_algebra_library), + sparse_linear_algebra_library_type(sparse_linear_algebra_library_type), use_automatic_ordering(use_automatic_ordering), preconditioner_type(IDENTITY), num_threads(1) { } SolverConfig(LinearSolverType linear_solver_type, - SparseLinearAlgebraLibraryType sparse_linear_algebra_library, + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type, bool use_automatic_ordering, PreconditionerType preconditioner_type) : linear_solver_type(linear_solver_type), - sparse_linear_algebra_library(sparse_linear_algebra_library), + sparse_linear_algebra_library_type(sparse_linear_algebra_library_type), use_automatic_ordering(use_automatic_ordering), preconditioner_type(preconditioner_type), num_threads(1) { @@ -88,14 +88,14 @@ struct SolverConfig { return StringPrintf( "(%s, %s, %s, %s, %d)", LinearSolverTypeToString(linear_solver_type), - SparseLinearAlgebraLibraryTypeToString(sparse_linear_algebra_library), + SparseLinearAlgebraLibraryTypeToString(sparse_linear_algebra_library_type), use_automatic_ordering ? "AUTOMATIC" : "USER", PreconditionerTypeToString(preconditioner_type), num_threads); } LinearSolverType linear_solver_type; - SparseLinearAlgebraLibraryType sparse_linear_algebra_library; + SparseLinearAlgebraLibraryType sparse_linear_algebra_library_type; bool use_automatic_ordering; PreconditionerType preconditioner_type; int num_threads; @@ -130,8 +130,8 @@ void RunSolversAndCheckTheyMatch(const vector<SolverConfig>& configurations, Solver::Options& options = *(system_test_problem->mutable_solver_options()); options.linear_solver_type = config.linear_solver_type; - options.sparse_linear_algebra_library = - config.sparse_linear_algebra_library; + options.sparse_linear_algebra_library_type = + config.sparse_linear_algebra_library_type; options.preconditioner_type = config.preconditioner_type; options.num_threads = config.num_threads; options.num_linear_solver_threads = config.num_threads; @@ -281,9 +281,9 @@ class PowellsFunction { TEST(SystemTest, PowellsFunction) { vector<SolverConfig> configs; -#define CONFIGURE(linear_solver, sparse_linear_algebra_library, ordering) \ - configs.push_back(SolverConfig(linear_solver, \ - sparse_linear_algebra_library, \ +#define CONFIGURE(linear_solver, sparse_linear_algebra_library_type, ordering) \ + configs.push_back(SolverConfig(linear_solver, \ + sparse_linear_algebra_library_type, \ ordering)) CONFIGURE(DENSE_QR, SUITE_SPARSE, kAutomaticOrdering); @@ -485,9 +485,9 @@ class BundleAdjustmentProblem { TEST(SystemTest, BundleAdjustmentProblem) { vector<SolverConfig> configs; -#define CONFIGURE(linear_solver, sparse_linear_algebra_library, ordering, preconditioner) \ +#define CONFIGURE(linear_solver, sparse_linear_algebra_library_type, ordering, preconditioner) \ configs.push_back(SolverConfig(linear_solver, \ - sparse_linear_algebra_library, \ + sparse_linear_algebra_library_type, \ ordering, \ preconditioner)) diff --git a/internal/ceres/trust_region_minimizer.cc b/internal/ceres/trust_region_minimizer.cc index d6ae0ab..03d6c8e 100644 --- a/internal/ceres/trust_region_minimizer.cc +++ b/internal/ceres/trust_region_minimizer.cc @@ -177,6 +177,7 @@ void TrustRegionMinimizer::Minimize(const Minimizer::Options& options, int num_consecutive_invalid_steps = 0; bool inner_iterations_are_enabled = options.inner_iteration_minimizer != NULL; while (true) { + bool inner_iterations_were_useful = false; if (!RunCallbacks(options.callbacks, iteration_summary, summary)) { return; } @@ -240,8 +241,8 @@ void TrustRegionMinimizer::Minimize(const Minimizer::Options& options, // = -f'J * step - step' * J' * J * step / 2 model_residuals.setZero(); jacobian->RightMultiply(trust_region_step.data(), model_residuals.data()); - model_cost_change = -(residuals.dot(model_residuals) + - model_residuals.squaredNorm() / 2.0); + model_cost_change = + - model_residuals.dot(residuals + model_residuals / 2.0); if (model_cost_change < 0.0) { VLOG(1) << "Invalid step: current_cost: " << cost @@ -330,11 +331,13 @@ void TrustRegionMinimizer::Minimize(const Minimizer::Options& options, << " x_plus_delta_cost: " << x_plus_delta_cost << " new_cost: " << new_cost; const double inner_iteration_relative_progress = - (x_plus_delta_cost - new_cost) / x_plus_delta_cost; + 1.0 - new_cost / x_plus_delta_cost; inner_iterations_are_enabled = (inner_iteration_relative_progress > options.inner_iteration_tolerance); + inner_iterations_were_useful = new_cost < cost; + // Disable inner iterations once the relative improvement // drops below tolerance. if (!inner_iterations_are_enabled) { @@ -398,13 +401,51 @@ void TrustRegionMinimizer::Minimize(const Minimizer::Options& options, ? max(relative_decrease, historical_relative_decrease) : relative_decrease; + // Normally, the quality of a trust region step is measured by + // the ratio + // + // cost_change + // r = ----------------- + // model_cost_change + // + // All the change in the nonlinear objective is due to the trust + // region step so this ratio is a good measure of the quality of + // the trust region radius. However, when inner iterations are + // being used, cost_change includes the contribution of the + // inner iterations and its not fair to credit it all to the + // trust region algorithm. So we change the ratio to be + // + // cost_change + // r = ------------------------------------------------ + // (model_cost_change + inner_iteration_cost_change) + // + // In most cases this is fine, but it can be the case that the + // change in solution quality due to inner iterations is so large + // and the trust region step is so bad, that this ratio can become + // quite small. + // + // This can cause the trust region loop to reject this step. To + // get around this, we expicitly check if the inner iterations + // led to a net decrease in the objective function value. If + // they did, we accept the step even if the trust region ratio + // is small. + // + // Notice that we do not just check that cost_change is positive + // which is a weaker condition and would render the + // min_relative_decrease threshold useless. Instead, we keep + // track of inner_iterations_were_useful, which is true only + // when inner iterations lead to a net decrease in the cost. iteration_summary.step_is_successful = - iteration_summary.relative_decrease > options_.min_relative_decrease; + (inner_iterations_were_useful || + iteration_summary.relative_decrease > + options_.min_relative_decrease); if (iteration_summary.step_is_successful) { accumulated_candidate_model_cost_change += model_cost_change; accumulated_reference_model_cost_change += model_cost_change; - if (relative_decrease <= options_.min_relative_decrease) { + + if (!inner_iterations_were_useful && + relative_decrease <= options_.min_relative_decrease) { iteration_summary.step_is_nonmonotonic = true; VLOG(2) << "Non-monotonic step! " << " relative_decrease: " << relative_decrease diff --git a/internal/ceres/types.cc b/internal/ceres/types.cc index 164185e..a97f1a5 100644 --- a/internal/ceres/types.cc +++ b/internal/ceres/types.cc @@ -101,7 +101,6 @@ const char* SparseLinearAlgebraLibraryTypeToString( } } - bool StringToSparseLinearAlgebraLibraryType( string value, SparseLinearAlgebraLibraryType* type) { @@ -111,6 +110,25 @@ bool StringToSparseLinearAlgebraLibraryType( return false; } +const char* DenseLinearAlgebraLibraryTypeToString( + DenseLinearAlgebraLibraryType type) { + switch (type) { + CASESTR(EIGEN); + CASESTR(LAPACK); + default: + return "UNKNOWN"; + } +} + +bool StringToDenseLinearAlgebraLibraryType( + string value, + DenseLinearAlgebraLibraryType* type) { + UpperCase(&value); + STRENUM(EIGEN); + STRENUM(LAPACK); + return false; +} + const char* TrustRegionStrategyTypeToString(TrustRegionStrategyType type) { switch (type) { CASESTR(LEVENBERG_MARQUARDT); @@ -318,4 +336,21 @@ bool IsSparseLinearAlgebraLibraryTypeAvailable( return false; } +bool IsDenseLinearAlgebraLibraryTypeAvailable( + DenseLinearAlgebraLibraryType type) { + if (type == EIGEN) { + return true; + } + if (type == LAPACK) { +#ifdef CERES_NO_LAPACK + return false; +#else + return true; +#endif + } + + LOG(WARNING) << "Unknown dense linear algebra library " << type; + return false; +} + } // namespace ceres diff --git a/internal/ceres/unsymmetric_linear_solver_test.cc b/internal/ceres/unsymmetric_linear_solver_test.cc index 232f34c..af9dffe 100644 --- a/internal/ceres/unsymmetric_linear_solver_test.cc +++ b/internal/ceres/unsymmetric_linear_solver_test.cc @@ -118,23 +118,41 @@ class UnsymmetricLinearSolverTest : public ::testing::Test { scoped_array<double> sol_regularized_; }; -TEST_F(UnsymmetricLinearSolverTest, DenseQR) { +TEST_F(UnsymmetricLinearSolverTest, EigenDenseQR) { LinearSolver::Options options; options.type = DENSE_QR; + options.dense_linear_algebra_library_type = EIGEN; TestSolver(options); } -TEST_F(UnsymmetricLinearSolverTest, DenseNormalCholesky) { +TEST_F(UnsymmetricLinearSolverTest, EigenDenseNormalCholesky) { LinearSolver::Options options; + options.dense_linear_algebra_library_type = EIGEN; options.type = DENSE_NORMAL_CHOLESKY; TestSolver(options); } +#ifndef CERES_NO_LAPACK +TEST_F(UnsymmetricLinearSolverTest, LAPACKDenseQR) { + LinearSolver::Options options; + options.type = DENSE_QR; + options.dense_linear_algebra_library_type = LAPACK; + TestSolver(options); +} + +TEST_F(UnsymmetricLinearSolverTest, LAPACKDenseNormalCholesky) { + LinearSolver::Options options; + options.dense_linear_algebra_library_type = LAPACK; + options.type = DENSE_NORMAL_CHOLESKY; + TestSolver(options); +} +#endif + #ifndef CERES_NO_SUITESPARSE TEST_F(UnsymmetricLinearSolverTest, SparseNormalCholeskyUsingSuiteSparsePreOrdering) { LinearSolver::Options options; - options.sparse_linear_algebra_library = SUITE_SPARSE; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; options.type = SPARSE_NORMAL_CHOLESKY; options.use_postordering = false; TestSolver(options); @@ -143,7 +161,7 @@ TEST_F(UnsymmetricLinearSolverTest, TEST_F(UnsymmetricLinearSolverTest, SparseNormalCholeskyUsingSuiteSparsePostOrdering) { LinearSolver::Options options; - options.sparse_linear_algebra_library = SUITE_SPARSE; + options.sparse_linear_algebra_library_type = SUITE_SPARSE; options.type = SPARSE_NORMAL_CHOLESKY; options.use_postordering = true; TestSolver(options); @@ -154,7 +172,7 @@ TEST_F(UnsymmetricLinearSolverTest, TEST_F(UnsymmetricLinearSolverTest, SparseNormalCholeskyUsingCXSparsePreOrdering) { LinearSolver::Options options; - options.sparse_linear_algebra_library = CX_SPARSE; + options.sparse_linear_algebra_library_type = CX_SPARSE; options.type = SPARSE_NORMAL_CHOLESKY; options.use_postordering = false; TestSolver(options); @@ -163,7 +181,7 @@ TEST_F(UnsymmetricLinearSolverTest, TEST_F(UnsymmetricLinearSolverTest, SparseNormalCholeskyUsingCXSparsePostOrdering) { LinearSolver::Options options; - options.sparse_linear_algebra_library = CX_SPARSE; + options.sparse_linear_algebra_library_type = CX_SPARSE; options.type = SPARSE_NORMAL_CHOLESKY; options.use_postordering = true; TestSolver(options); diff --git a/internal/ceres/visibility.cc b/internal/ceres/visibility.cc index fcd793c..acfa45b 100644 --- a/internal/ceres/visibility.cc +++ b/internal/ceres/visibility.cc @@ -153,4 +153,4 @@ Graph<int>* CreateSchurComplementGraph(const vector<set<int> >& visibility) { } // namespace internal } // namespace ceres -#endif +#endif // CERES_NO_SUITESPARSE diff --git a/internal/ceres/visibility_based_preconditioner_test.cc b/internal/ceres/visibility_based_preconditioner_test.cc index 53d10e1..2edbb18 100644 --- a/internal/ceres/visibility_based_preconditioner_test.cc +++ b/internal/ceres/visibility_based_preconditioner_test.cc @@ -279,7 +279,7 @@ namespace internal { // preconditioner_->RightMultiply(x.data(), y.data()); // z = full_schur_complement // .selfadjointView<Eigen::Upper>() -// .ldlt().solve(x); +// .llt().solve(x); // double max_relative_difference = // ((y - z).array() / z.array()).matrix().lpNorm<Eigen::Infinity>(); // EXPECT_NEAR(max_relative_difference, 0.0, kTolerance); diff --git a/jni/Android.mk b/jni/Android.mk index b881d88..7d5afd8 100644 --- a/jni/Android.mk +++ b/jni/Android.mk @@ -99,6 +99,7 @@ LOCAL_C_INCLUDES += $(EIGEN_PATH) LOCAL_CPP_EXTENSION := .cc LOCAL_CFLAGS := $(CERES_EXTRA_DEFINES) \ + -DCERES_NO_LAPACK \ -DCERES_NO_SUITESPARSE \ -DCERES_NO_GFLAGS \ -DCERES_NO_THREADS \ @@ -111,6 +112,7 @@ LOCAL_CFLAGS := $(CERES_EXTRA_DEFINES) \ LOCAL_CFLAGS += -Wno-psabi LOCAL_SRC_FILES := $(CERES_SRC_PATH)/array_utils.cc \ + $(CERES_SRC_PATH)/blas.cc \ $(CERES_SRC_PATH)/block_evaluate_preparer.cc \ $(CERES_SRC_PATH)/block_jacobian_writer.cc \ $(CERES_SRC_PATH)/block_jacobi_preconditioner.cc \ @@ -137,6 +139,7 @@ LOCAL_SRC_FILES := $(CERES_SRC_PATH)/array_utils.cc \ $(CERES_SRC_PATH)/gradient_checking_cost_function.cc \ $(CERES_SRC_PATH)/implicit_schur_complement.cc \ $(CERES_SRC_PATH)/iterative_schur_complement_solver.cc \ + $(CERES_SRC_PATH)/lapack.cc \ $(CERES_SRC_PATH)/levenberg_marquardt_strategy.cc \ $(CERES_SRC_PATH)/line_search.cc \ $(CERES_SRC_PATH)/line_search_direction.cc \ diff --git a/scripts/ceres-solver.spec b/scripts/ceres-solver.spec index 69b08e6..b3b6f0f 100644 --- a/scripts/ceres-solver.spec +++ b/scripts/ceres-solver.spec @@ -3,13 +3,13 @@ Version: 1.7.0 # Release candidate versions are messy. Give them a release of # e.g. "0.1.0%{?dist}" for RC1 (and remember to adjust the Source0 # URL). Non-RC releases go back to incrementing integers starting at 1. -Release: "0.1.0%{?dist}" +Release: 0.3.0%{?dist} Summary: A non-linear least squares minimizer Group: Development/Libraries License: BSD URL: http://code.google.com/p/ceres-solver/ -Source0: http://%{name}.googlecode.com/files/%{name}-%{version}rc1.tar.gz +Source0: http://%{name}.googlecode.com/files/%{name}-%{version}rc3.tar.gz BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) %if (0%{?rhel} == 06) @@ -18,7 +18,13 @@ BuildRequires: cmake28 BuildRequires: cmake %endif BuildRequires: eigen3-devel -BuildRequires: suitesparse-devel +# suitesparse <= 3.4.0-7 ships without *.hpp C++ headers +# https://bugzilla.redhat.com/show_bug.cgi?id=1001869 +BuildRequires: suitesparse-devel > 3.4.0-7 +# If the suitesparse package was built with TBB then we need TBB too +%ifarch %{ix86} x86_64 ia64 +BuildRequires: tbb-devel +%endif # Use atlas for BLAS and LAPACK BuildRequires: atlas-devel BuildRequires: gflags-devel @@ -65,12 +71,10 @@ pushd build # packages because it breaks the build since release 1.5.0rc1 %define optflags "" %if (0%{?rhel} == 06) -%{cmake28} .. \ +%{cmake28} .. %else -%{cmake} .. \ +%{cmake} .. %endif - -DBLAS_LIB:FILEPATH=%{_libdir}/atlas/libatlas.so \ - -DLAPACK_LIB:FILEPATH=%{_libdir}/atlas/liblapack.so make %{?_smp_mflags} @@ -80,6 +84,9 @@ pushd build make install DESTDIR=$RPM_BUILD_ROOT find $RPM_BUILD_ROOT -name '*.la' -delete +# Make the subdirectory in /usr/share match the name of this package +mv $RPM_BUILD_ROOT%{_datadir}/{Ceres,%{name}} + %clean rm -rf $RPM_BUILD_ROOT @@ -92,19 +99,24 @@ rm -rf $RPM_BUILD_ROOT %files %defattr(-,root,root,-) -%doc +%doc README LICENSE %{_libdir}/*.so.* %files devel %defattr(-,root,root,-) -%doc %{_includedir}/* %{_libdir}/*.so -%{_libdir}/*.a +%{_datadir}/%{name}/*.cmake %changelog -* Mon July 18 2013 Sameer Agarwal <sameeragarwal@google.com> - 1.7.0-0 +* Thu Aug 29 2013 Taylor Braun-Jones <taylor@braun-jones.org> - 1.7.0-0.3.0 +- Bump version + +* Mon Aug 26 2013 Sameer Agarwal <sameeragarwal@google.com> - 1.7.0-0.2.0 +- Bump version + +* Mon Jul 18 2013 Sameer Agarwal <sameeragarwal@google.com> - 1.7.0-0.1.0 - Bump version * Mon Apr 29 2013 Sameer Agarwal <sameeragarwal@google.com> - 1.6.0-1 |