Update documentation and version history for 2.3.0 - Populate 2.3.0 release notes in docs/source/version_history.rst covering all new features, API changes, and bug fixes since 2.2.0 with contributor credits. - Overhaul docs/source/installation.rst for 2.3.0: document Abseil, GoogleTest, Google Benchmark, and cuDSS dependencies, submodule workflow, WITH_* CMake options, Config-mode dependency discovery, Bzlmod Bazel build, and 2.3 migration notes; modernize CMake CLI invocations and consolidate build-tree export guidance. - Document CUDA_SPARSE (cuDSS) in docs/source/nnls_solving.rst. - Update tutorial code snippets and solver summaries in docs/source/nnls_tutorial.rst and docs/source/gradient_tutorial.rst for Abseil logging and 2.3.0. - Add abseil_cpp dependency to package.xml. - Fix broken and redirected external URLs across docs/source/*.rst. Change-Id: I1a356c4ffe4a91d4384816c4e7a83d1cc4566346
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index cba274c..39e9d00 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst
@@ -6,7 +6,7 @@ We welcome contributions to Ceres, whether they are new features, bug fixes or tests. The Ceres `mailing -<http://groups.google.com/group/ceres-solver>`_ list is the best place +<https://groups.google.com/g/ceres-solver>`_ list is the best place for all development related discussions. Please consider joining it. If you have ideas on how you would like to contribute to Ceres, it is a good idea to let us know on the mailing list before you start @@ -17,7 +17,7 @@ We follow Google's `C++ Style Guide <https://google.github.io/styleguide/cppguide.html>`_ and -use `git <http://git-scm.com/>`_ for version control. We use the +use `git <https://git-scm.com/>`_ for version control. We use `Gerrit <https://ceres-solver-review.googlesource.com/>`_ to collaborate and review changes to Ceres. Gerrit enables pre-commit reviews so that Ceres can maintain a linear history with clean, reviewed commits, and @@ -33,14 +33,13 @@ * Mac ``brew install git``. * Linux ``sudo apt-get install git``. - * Windows. Download `msysgit - <https://code.google.com/p/msysgit/>`_, which includes a minimal - `Cygwin <http://www.cygwin.com/>`_ install. + * Windows. Download `Git for Windows + <https://git-scm.com/download/win>`__. 2. Sign up for `Gerrit <https://ceres-solver-review.googlesource.com/>`_. You will also need to `sign the Contributor License Agreement (CLA) - <https://opensource.google.com/docs/cla/#sign>`_ with Google, which gives + <https://opensource.google/documentation/reference/cla>`_ with Google, which gives Google a royalty-free unlimited license to use your contributions. You retain copyright.
diff --git a/docs/source/features.rst b/docs/source/features.rst index 609f41c..6a962fa 100644 --- a/docs/source/features.rst +++ b/docs/source/features.rst
@@ -86,11 +86,11 @@ application .. _best performing: https://groups.google.com/forum/#!topic/ceres-solver/UcicgMPgbXw -.. _bundle adjustment: http://en.wikipedia.org/wiki/Bundle_adjustment -.. _SuiteSparse: http://www.cise.ufl.edu/research/sparse/SuiteSparse/ -.. _Eigen: http://eigen.tuxfamily.org/ -.. _LAPACK: http://www.netlib.org/lapack/ -.. _automatic: http://en.wikipedia.org/wiki/Automatic_differentiation -.. _numeric: http://en.wikipedia.org/wiki/Numerical_differentiation -.. _CUDA : https://developer.nvidia.com/cuda-toolkit -.. _Apple's Accelerate: https://developer.apple.com/documentation/accelerate/sparse_solvers +.. _bundle adjustment: https://en.wikipedia.org/wiki/Bundle_adjustment +.. _SuiteSparse: https://people.engr.tamu.edu/davis/suitesparse.html +.. _Eigen: https://libeigen.gitlab.io/ +.. _LAPACK: https://www.netlib.org/lapack/ +.. _automatic: https://en.wikipedia.org/wiki/Automatic_differentiation +.. _numeric: https://en.wikipedia.org/wiki/Numerical_differentiation +.. _CUDA : https://developer.nvidia.com/cuda/toolkit +.. _Apple's Accelerate: https://developer.apple.com/documentation/accelerate/sparse-solvers-library
diff --git a/docs/source/gradient_tutorial.rst b/docs/source/gradient_tutorial.rst index 6f7508b..c6829e3 100644 --- a/docs/source/gradient_tutorial.rst +++ b/docs/source/gradient_tutorial.rst
@@ -112,7 +112,7 @@ 33: f: 4.835994e-17 d: 1.00e-12 g: 1.05e-07 h: 1.13e-06 s: 1.00e+00 e: 1 it: 1.19e-06 tt: 3.34e-04 34: f: 1.885250e-22 d: 4.84e-17 g: 2.69e-10 h: 1.45e-08 s: 1.00e+00 e: 1 it: 9.54e-07 tt: 3.37e-04 - Solver Summary (v 2.2.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) + Solver Summary (v 2.3.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) Parameters 2 Line search direction LBFGS (20)
diff --git a/docs/source/installation.rst b/docs/source/installation.rst index ad9384d..3c88f7f 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst
@@ -18,9 +18,9 @@ optional. For details on customizing the build process, see :ref:`section-customizing` . -- `CMake <http://www.cmake.org>`_ (**required**) 3.22 or later. +- `CMake <https://cmake.org>`_ (**Required**) 3.22 or later. -- `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ +- `Eigen <https://libeigen.gitlab.io/>`_ (**Required**) 3.3.4 or later. .. NOTE :: @@ -34,9 +34,17 @@ - `GoogleTest <https://github.com/google/googletest>`_ (**Optional**; Required if you wish to build and run tests) 1.14.0 or later. -- `SuiteSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_ +- `Google Benchmark <https://github.com/google/benchmark>`_ (**Optional**; + used if ``BUILD_BENCHMARKS`` is ``ON``). + +- `SuiteSparse <https://people.engr.tamu.edu/davis/suitesparse.html>`_ (**Optional; strongly recommended for large problems**) 4.5.6 or - later. Needed for solving large sparse linear systems. + later (7.4.0 or later for single-precision ``CHOLMOD`` support). Needed + for solving large sparse linear systems. Because ``SuiteSparse``'s + supernodal ``CHOLMOD`` and ``SPQR`` components are licensed under the + GPL, ``WITH_SUITESPARSE`` defaults to ``OFF``; pass + ``-DWITH_SUITESPARSE=ON`` to ``CMake`` to enable it (see + ``WITH_SUITESPARSE`` in :ref:`options-controlling-ceres-configuration`). .. NOTE :: @@ -46,56 +54,60 @@ found TBB version. You can customize the searched TBB location with the ``TBB_ROOT`` variable. +- `METIS <https://github.com/KarypisLab/METIS>`_ (**Optional**) Used by + ``SuiteSparse``, optionally by ``Eigen``'s sparse solvers (when + ``WITH_EIGENMETIS=ON``), and directly by Ceres for graph partitioning. + - `Apple's Accelerate sparse solvers - <https://developer.apple.com/documentation/accelerate/sparse_solvers>`_. (**Optional**) + <https://developer.apple.com/documentation/accelerate/sparse-solvers-library>`_. (**Optional**) As of Xcode 9.0, Apple's Accelerate framework includes support for solving sparse linear systems across macOS, iOS et al. -- `BLAS <http://www.netlib.org/blas/>`_ and `LAPACK - <http://www.netlib.org/lapack/>`_ (**Optional but required for** - ``SuiteSparse``) ``LAPACK`` and ``BLAS`` routines are needed by - ``SuiteSparse``, and optionally used by Ceres directly for some - operations. +- `BLAS <https://www.netlib.org/blas/>`_ and `LAPACK + <https://www.netlib.org/lapack/>`_ (**Optional**) ``LAPACK`` and + ``BLAS`` routines are used by ``SuiteSparse``, and optionally used by + Ceres directly for some operations (controlled by ``WITH_LAPACK``). For best performance on ``x86`` based Linux systems we recommend - using `Intel MKL - <https://www.intel.com/content/www/us/en/develop/documentation/get-started-with-mkl-for-dpcpp/top.html>`_. + using `Intel oneAPI MKL + <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_. - Two other good options are `ATLAS - <http://math-atlas.sourceforge.net/>`_, which includes ``BLAS`` and - ``LAPACK`` routines and `OpenBLAS - <https://github.com/xianyi/OpenBLAS>`_ . However, one needs to be + Another good option is `OpenBLAS + <https://github.com/OpenMathLib/OpenBLAS>`_. However, one needs to be careful to `turn off the threading - <https://github.com/xianyi/OpenBLAS/wiki/faq#wiki-multi-threaded>`_ + <https://www.openmathlib.org/OpenBLAS/docs/faq/#how-can-i-use-openblas-in-multi-threaded-applications>`_ inside ``OpenBLAS`` as it conflicts with use of threads in Ceres. - MacOS ships with an optimized ``LAPACK`` and ``BLAS`` + macOS ships with an optimized ``LAPACK`` and ``BLAS`` implementation as part of the ``Accelerate`` framework. The Ceres build system will automatically detect and use it. - For Windows things are much more complicated. `LAPACK For - Windows <http://icl.cs.utk.edu/lapack-for-windows/lapack/>`_ - has detailed instructions. + On Windows, ``BLAS`` and ``LAPACK`` (such as ``OpenBLAS`` or ``Intel MKL``) + can be installed via `vcpkg <https://github.com/microsoft/vcpkg>`_ or + `MSYS2 <https://www.msys2.org/>`_, or obtained as part of the prebuilt + ``SuiteSparse`` binary packages (see :ref:`section-windows`). -- `CUDA <https://developer.nvidia.com/cuda-toolkit>`_ and `cuDSS +- `CUDA <https://developer.nvidia.com/cuda/toolkit>`_ and `cuDSS <https://developer.nvidia.com/cudss>`_ (**Optional**) - If you have an NVIDIA GPU then Ceres Solver can use it accelerate + If you have an NVIDIA GPU then Ceres Solver can use it to accelerate the solution of the Gauss-Newton linear systems using the CMake flag ``WITH_CUDA``. - This support depends on two libraries from NVIDIA `CUDA` and `cuDSS`. + This support depends on two libraries from NVIDIA: ``CUDA`` and ``cuDSS``. If ``CUDA`` is available, Ceres Solver is able to use - GPU acceleration to speed up ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY`` - and ``DENSE_SCHUR`` and ``CGNR``. This also enables ``CUDA`` based + GPU acceleration to speed up ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY``, + ``DENSE_SCHUR``, and ``CGNR``. This also enables ``CUDA`` based mixed precision solves for ``DENSE_NORMAL_CHOLESKY`` and ``DENSE_SCHUR``. - Additionally if ``cuDSS`` is also available then GPU acceleration can - be used for ``SPARSE_NORMAL_CHOLESKY`` and ``SPARSE_SCHUR``. + Additionally, if ``cuDSS`` is also available (controlled by + ``WITH_CUDSS``), then GPU acceleration can be used for + ``SPARSE_NORMAL_CHOLESKY`` and ``SPARSE_SCHUR`` via the + ``CUDA_SPARSE`` sparse linear algebra library. .. _section-source: @@ -104,23 +116,24 @@ You can start with the `latest stable release -<http://ceres-solver.org/ceres-solver-2.2.0.tar.gz>`_ . Or if you want +<http://ceres-solver.org/ceres-solver-2.3.0.tar.gz>`_ . Or if you want the latest version, you can clone the git repository .. code-block:: bash - git clone https://ceres-solver.googlesource.com/ceres-solver + git clone https://github.com/ceres-solver/ceres-solver If your system does not have recent enough versions of `Abseil -<https://abseil.io/>`_ and/or `GoogleTest -<https://github.com/google/googletest>`_, then you can use the -versions included with Ceres Solver as submodules by using the command +<https://abseil.io/>`_ (>= 20240116) and/or `GoogleTest +<https://github.com/google/googletest>`_ (>= 1.14.0), then you can use +the versions included with Ceres Solver as git submodules by using the +command .. code-block:: bash git clone --recurse-submodules https://github.com/ceres-solver/ceres-solver -The build instructions below use ``ceres-solver-2.2.0`` as the source +The build instructions below use ``ceres-solver-2.3.0`` as the source directory because they assume a release archive. If you build from a Git checkout, replace it with the name of your checkout, usually ``ceres-solver``. @@ -130,7 +143,7 @@ Linux ===== -We will use `Ubuntu <http://www.ubuntu.com>`_ as our example linux +We will use `Ubuntu <https://ubuntu.com/>`_ as our example Linux distribution. .. NOTE:: @@ -140,34 +153,42 @@ repositories and compiler toolchain. Support for earlier versions is not guaranteed or maintained. -Start by installing all the dependencies. + Because the default ``apt`` repositories on Ubuntu 22.04 and 24.04 + ship versions of ``libabsl-dev`` older than ``20240116``, we + recommend cloning Ceres with ``--recurse-submodules`` on those + distributions so that CMake automatically builds the bundled + ``Abseil`` and ``GoogleTest`` submodules in ``third_party/``. On + newer distributions that ship ``Abseil >= 20240116`` and + ``GoogleTest >= 1.14.0``, you can install ``libabsl-dev`` and + ``libgtest-dev`` directly via ``apt``. + +Start by installing the dependencies: .. code-block:: bash # CMake sudo apt-get install cmake - # google-glog + gflags - sudo apt-get install libgoogle-glog-dev libgflags-dev - # Use ATLAS for BLAS & LAPACK - sudo apt-get install libatlas-base-dev + # BLAS & LAPACK + sudo apt-get install libblas-dev liblapack-dev # Eigen3 sudo apt-get install libeigen3-dev - # SuiteSparse (optional) - sudo apt-get install libsuitesparse-dev + # SuiteSparse and METIS (optional) + sudo apt-get install libsuitesparse-dev libmetis-dev + # Abseil and GoogleTest (if your distribution ships >= 20240116 and >= 1.14.0; + # otherwise clone Ceres with --recurse-submodules) + sudo apt-get install libabsl-dev libgtest-dev We are now ready to build, test, and install Ceres. .. code-block:: bash - tar zxf ceres-solver-2.2.0.tar.gz - mkdir ceres-bin - cd ceres-bin - cmake ../ceres-solver-2.2.0 - make -j3 - make test - # The build tree is also exported for use without installation. Registry - # registration can be disabled with CMAKE_EXPORT_PACKAGE_REGISTRY=OFF. - make install + tar zxf ceres-solver-2.3.0.tar.gz + cmake -S ceres-solver-2.3.0 -B ceres-bin -DWITH_SUITESPARSE=ON + cmake --build ceres-bin -j + ctest --test-dir ceres-bin --output-on-failure + # Optionally install Ceres system-wide (or use ceres-bin directly via Ceres_DIR; + # see "Using Ceres with CMake" below). + sudo cmake --install ceres-bin 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 @@ -175,7 +196,7 @@ .. code-block:: bash - bin/simple_bundle_adjuster ../ceres-solver-2.2.0/data/problem-16-22106-pre.txt + ceres-bin/bin/simple_bundle_adjuster ceres-solver-2.3.0/data/problem-16-22106-pre.txt This runs Ceres for a maximum of 10 iterations using the ``DENSE_SCHUR`` linear solver. The output should look something like @@ -190,9 +211,9 @@ 3 1.899774e+04 3.09e+04 1.60e+06 1.24e+02 9.77e-01 9.26e+04 1 4.74e-02 2.11e-01 4 1.808729e+04 9.10e+02 3.97e+05 6.39e+01 9.51e-01 2.78e+05 1 4.75e-02 2.59e-01 5 1.803399e+04 5.33e+01 1.48e+04 1.23e+01 9.99e-01 8.33e+05 1 4.74e-02 3.06e-01 - 6 1.803390e+04 9.02e-02 6.35e+01 8.00e-01 1.00e+00 2.50e+06 1 4.76e-02 3.54e-01 + 6 1.803390e+04 9.02e-02 6.35e+01 8.00e+01 1.00e+00 2.50e+06 1 4.76e-02 3.54e-01 - Solver Summary (v 2.2.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) + Solver Summary (v 2.3.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) Original Reduced Parameter blocks 22122 22122 @@ -233,7 +254,7 @@ Termination: CONVERGENCE (Function tolerance reached. |cost_change|/cost: 1.769759e-09 <= 1.000000e-06) -.. section-macos: +.. _section-macos: macOS ===== @@ -268,34 +289,32 @@ You can also install each of the dependencies by hand using `Homebrew <https://brew.sh/>`_. There is no need to install ``BLAS`` or ``LAPACK`` separately as macOS ships with optimized -``BLAS`` and ``LAPACK`` routines as part of the `vecLib -<https://developer.apple.com/library/mac/#documentation/Performance/Conceptual/vecLib/Reference/reference.html>`_ +``BLAS`` and ``LAPACK`` routines as part of the `Accelerate +<https://developer.apple.com/documentation/accelerate>`_ framework. .. code-block:: bash # CMake brew install cmake - # google-glog and gflags - brew install glog gflags + # Abseil and GoogleTest + brew install abseil googletest # Eigen3 brew install eigen - # SuiteSparse - brew install suite-sparse + # SuiteSparse and METIS (optional) + brew install suite-sparse metis We are now ready to build, test, and install Ceres. .. code-block:: bash - tar zxf ceres-solver-2.2.0.tar.gz - mkdir ceres-bin - cd ceres-bin - cmake ../ceres-solver-2.2.0 - make -j3 - make test - # The build tree is also exported for use without installation. Registry - # registration can be disabled with CMAKE_EXPORT_PACKAGE_REGISTRY=OFF. - make install + tar zxf ceres-solver-2.3.0.tar.gz + cmake -S ceres-solver-2.3.0 -B ceres-bin -DWITH_SUITESPARSE=ON + cmake --build ceres-bin -j + ctest --test-dir ceres-bin --output-on-failure + # Optionally install Ceres (or use ceres-bin directly via Ceres_DIR; + # see "Using Ceres with CMake" below). + cmake --install ceres-bin .. _section-windows: @@ -347,108 +366,83 @@ Building from Source -------------------- -Ceres Solver can also be built from source. For this purpose, we support Visual -Studio 2019 and newer. - -.. NOTE:: - - If you find the following CMake difficult to set up, then you may - be interested in a `Microsoft Visual Studio wrapper - <https://github.com/tbennun/ceres-windows>`_ for Ceres Solver by Tal - Ben-Nun. +Ceres Solver can also be built from source on Windows using Visual Studio 2019 +or newer (or MSYS2 / MinGW-w64). #. Create a top-level directory for dependencies, build, and sources somewhere, e.g., ``ceres/`` -#. Get dependencies; unpack them as subdirectories in ``ceres/`` - (``ceres/eigen``, ``ceres/glog``, etc.) +#. Obtain the Ceres source code and its dependencies: - #. ``Eigen`` 3.3.4 . Configure and optionally install Eigen. It should be - exported into the CMake package registry by default as part of the - configure stage so installation should not be necessary. - - #. ``google-glog`` Open up the Visual Studio solution and build it. - #. ``gflags`` Open up the Visual Studio solution and build it. - - #. (Experimental) ``SuiteSparse`` Previously SuiteSparse was not - available on Windows, recently it has become possible to build - it on Windows using the `suitesparse-metis-for-windows - <https://github.com/jlblancoc/suitesparse-metis-for-windows>`_ - project. If you wish to use ``SuiteSparse``, follow their - instructions for obtaining and building it. - - Alternatively, Ceres Solver supports ``SuiteSparse`` binary - packages available for Visual Studio 2019 and 2022 provided by - the `CMake support for SuiteSparse - <https://github.com/sergiud/SuiteSparse>`_ project that also - include `reference LAPACK <http://www.netlib.org/blas>`_ (and - BLAS). The binary packages are used by Ceres Solver for - continuous testing on Github. - -#. Unpack the Ceres tarball into ``ceres``. For the tarball, you - should get a directory inside ``ceres`` similar to - ``ceres-solver-2.2.0``. Alternately, checkout Ceres via ``git`` to - get ``ceres-solver.git`` inside ``ceres``. - -#. Install ``CMake``, - -#. Create a directory ``ceres/ceres-bin`` (for an out-of-tree build) - - #. If you use the above binary ``SuiteSparse`` package, make sure CMake can - find it, e.g., by assigning the path of the directory that contains the - unzipped contents to the ``CMAKE_PREFIX_PATH`` environment variable. In a - Windows command prompt this can be achieved as follows: + #. **Abseil** (>= 20240116) and **GoogleTest** (>= 1.14.0): The simplest way + to provide ``Abseil`` and ``GoogleTest`` when building from source on + Windows is to clone Ceres with ``--recurse-submodules``: .. code:: bat - export CMAKE_PREFIX_PATH=C:/Downloads/SuiteSparse-5.11.0-cmake.1-vc16-Win64-Release-shared-gpl + git clone --recurse-submodules https://github.com/ceres-solver/ceres-solver -#. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or - ``ceres-solver.git`` directory for the CMake file. Then select the - ``ceres-bin`` for the build directory. + Alternatively, you can build and install ``Abseil`` and ``GoogleTest`` + separately using CMake and pass their install prefix via + ``CMAKE_PREFIX_PATH`` (or set ``absl_DIR`` / ``absl_ROOT`` and + ``GTest_DIR`` / ``GTest_ROOT``). -#. Try running ``Configure`` which can fail at first because some dependencies - cannot be automatically located. In this case, you must set the following - CMake variables to the appropriate directories where you unpacked/built them: + #. **Eigen** (>= 3.3.4): Unpack and configure/install Eigen using CMake, and + pass ``-DEigen3_ROOT=<path/to/eigen>`` (or + ``-DEigen3_DIR=<path/to/Eigen3Config.cmake>``) when configuring Ceres. - #. ``Eigen3_DIR`` (Set to directory containing ``Eigen3Config.cmake``) - #. ``GLOG_INCLUDE_DIR_HINTS`` - #. ``GLOG_LIBRARY_DIR_HINTS`` - #. (Optional) ``gflags_DIR`` (Set to directory containing ``gflags-config.cmake``) - #. (SuiteSparse binary package) ``BLAS_blas_LIBRARY`` and - ``LAPACK_lapack_LIBRARY`` CMake variables must be `explicitly set` to - ``<path>/lib/blas.lib`` and ``<path>/lib/lapack.lib``, respectively, both - located in the unzipped package directory ``<path>``. + #. (Optional) **SuiteSparse**: You can build SuiteSparse on Windows using + `suitesparse-metis-for-windows + <https://github.com/jlblancoc/suitesparse-metis-for-windows>`_ or + official ``SuiteSparse`` CMake releases, or use the prebuilt binary + packages for Visual Studio 2019 and 2022 provided by the `CMake support + for SuiteSparse <https://github.com/sergiud/SuiteSparse>`_ project that + also include `reference LAPACK <https://www.netlib.org/blas/>`_ (and + BLAS). When using the prebuilt ``SuiteSparse`` archive, add its directory + to ``CMAKE_PREFIX_PATH``, enable ``-DWITH_SUITESPARSE=ON``, and set + ``BLAS_blas_LIBRARY`` and ``LAPACK_lapack_LIBRARY`` to + ``<suitesparse_path>/lib/libblas.lib`` and + ``<suitesparse_path>/lib/liblapack.lib``. - If any of the variables are not visible in the ``CMake`` GUI, create a new - entry for them. We recommend using the - ``<NAME>_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than setting the - ``<NAME>_INCLUDE_DIR`` & ``<NAME>_LIBRARY`` variables directly to keep all of - the validity checking, and to avoid having to specify the library files - manually. +#. Install ``CMake``. -#. You may have to tweak some more settings to generate a MSVC - project. After each adjustment, try pressing Configure & Generate - until it generates successfully. +#. Configure and build Ceres out-of-tree in ``ceres-bin`` (either from the + command line or using ``cmake-gui`` and the Visual Studio IDE): -#. Open the solution and build it in MSVC + .. code:: bat + cmake -S ceres-solver -B ceres-bin -DEigen3_ROOT=C:\path\to\eigen + cmake --build ceres-bin --config Release -To run the tests, select the ``RUN_TESTS`` target and hit **Build -RUN_TESTS** from the build menu. + If you are using ``cmake-gui``, select ``ceres-solver`` as the source + directory and ``ceres-bin`` as the build directory, click **Configure**, set + any missing dependency locations (see + :ref:`options-controlling-ceres-dependency-locations`), click **Generate**, + and then open the generated Visual Studio solution in ``ceres-bin`` to build + it. + +#. To run the tests, run ``ctest`` from the command line: + + .. code:: bat + + ctest --test-dir ceres-bin -C Release --output-on-failure + + Or in Visual Studio, select the ``RUN_TESTS`` target and click **Build + RUN_TESTS** from the build menu. Like the Linux build, you should now be able to run -``bin/simple_bundle_adjuster``. +``ceres-bin\bin\Release\simple_bundle_adjuster.exe``. .. note:: - #. The default build is ``Debug``; consider switching it to ``Release`` for - optimal performance. - #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` by - default. + #. The default multi-config build in Visual Studio is ``Debug``; always pass + ``--config Release`` on the command line or switch the active + configuration to ``Release`` in Visual Studio for optimal performance. + #. CMake puts the resulting binaries in ``ceres-bin/bin/Debug`` or + ``ceres-bin/bin/Release`` by default. #. Without a sparse linear algebra library, only a subset of - solvers is usable, namely: ``DENSE_QR``, ``DENSE_SCHUR``, - ``CGNR``, and ``ITERATIVE_SCHUR``. + solvers is usable, namely: ``DENSE_QR``, ``DENSE_NORMAL_CHOLESKY``, + ``DENSE_SCHUR``, ``CGNR``, and ``ITERATIVE_SCHUR``. .. _section-android: @@ -458,46 +452,46 @@ .. NOTE:: - You will need Android NDK r15 or higher to build Ceres solver. + You will need Android NDK r20 or higher (current LTS such as r27 is + recommended) to build Ceres Solver with full C++17 support. -To build Ceres for Android, we need to force ``CMake`` to find -the toolchains from the Android NDK instead of using the standard -ones. For example, assuming you have specified ``$NDK_DIR``: +To build Ceres for Android, clone Ceres with ``--recurse-submodules`` (so that +``Abseil`` is built alongside Ceres for the target Android ABI, or provide a +cross-compiled ``Abseil`` via ``-Dabsl_DIR=...``) and instruct ``CMake`` to use +the toolchain file from the Android NDK. For example, assuming you have +specified ``$NDK_DIR``: .. code-block:: bash - cmake \ - -DCMAKE_TOOLCHAIN_FILE=\ - $NDK_DIR/build/cmake/android.toolchain.cmake \ - -DEigen3_DIR=/path/to/Eigen3Config.cmake \ - -DANDROID_ABI=arm64-v8a \ - -DANDROID_STL=c++_shared \ - -DANDROID_NATIVE_API_LEVEL=android-29 \ - -DBUILD_SHARED_LIBS=ON \ - -DMINIGLOG=ON \ - <PATH_TO_CERES_SOURCE> + cmake -S <PATH_TO_CERES_SOURCE> -B ceres-bin \ + -DCMAKE_TOOLCHAIN_FILE=$NDK_DIR/build/cmake/android.toolchain.cmake \ + -DEigen3_DIR=/path/to/Eigen3Config.cmake \ + -DANDROID_ABI=arm64-v8a \ + -DANDROID_STL=c++_shared \ + -DANDROID_NATIVE_API_LEVEL=android-29 \ + -DBUILD_SHARED_LIBS=ON \ + -DBUILD_TESTING=OFF \ + -DBUILD_EXAMPLES=OFF \ + -DBUILD_BENCHMARKS=OFF + cmake --build ceres-bin -j -You can build for any Android STL or ABI, but the c++_shared STL -and the armeabi-v7a or arm64-v8a ABI are recommended for 32bit -and 64bit architectures, respectively. Several API levels may -be supported, but it is recommended that you use the highest -level that is suitable for your Android project. +You can build for any supported Android STL or ABI (such as ``arm64-v8a``, +``armeabi-v7a``, ``x86_64``, or ``x86``). Several API levels are supported; +use an API level appropriate for your Android project. .. NOTE:: You must always use the same API level and STL library for your Android project and the Ceres binaries. -After building, you get a ``libceres.so`` library, which you can -link in your Android build system by using a -``PREBUILT_SHARED_LIBRARY`` target in your build script. +After building, you get a ``libceres.so`` library (and Abseil libraries if +built as shared libraries), which you can link into your Android build. -If you are building any Ceres samples and would like to verify -your library, you will need to place them in an executable public -directory together with ``libceres.so`` on your Android device -(e.g. in /data/local/tmp) and ensure that the STL library from -your NDK is present in that same directory. You may then execute -the sample by running for example: +If you also build the Ceres sample binaries (by setting +``-DBUILD_EXAMPLES=ON``) and would like to verify your library on an Android +device, place the sample binary together with ``libceres.so`` (and the NDK STL +shared library ``libc++_shared.so`` and any other shared dependencies) in an +executable directory on the device such as ``/data/local/tmp``, and run: .. code-block:: bash @@ -505,10 +499,6 @@ cd /data/local/tmp LD_LIBRARY_PATH=/data/local/tmp ./helloworld -Note that any solvers or other shared dependencies you include in -your project must also be present in your android build config and -your test directory on Android. - .. _section-ios: iOS @@ -516,42 +506,40 @@ .. NOTE:: - You need iOS version 7.0 or higher to build Ceres Solver. + You need at least iOS 7.0 or higher to build Ceres Solver (iOS 12.0 or + higher is recommended for modern Xcode toolchains). -To build Ceres for iOS, we need to force ``CMake`` to find the -toolchains from the iOS SDK instead of using the standard ones. For -example: +To build Ceres for iOS, clone Ceres with ``--recurse-submodules`` (or provide +``Abseil`` for iOS via ``-Dabsl_DIR=...``) and instruct ``CMake`` to use the +``cmake/iOS.cmake`` toolchain file: .. code-block:: bash - cmake \ - -DCMAKE_TOOLCHAIN_FILE=../ceres-solver/cmake/iOS.cmake \ - -DEigen3_DIR=/path/to/Eigen3Config.cmake \ - -DIOS_PLATFORM=<PLATFORM> \ - <PATH_TO_CERES_SOURCE> + cmake -S <PATH_TO_CERES_SOURCE> -B ceres-bin \ + -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_CERES_SOURCE>/cmake/iOS.cmake \ + -DEigen3_DIR=/path/to/Eigen3Config.cmake \ + -DIOS_PLATFORM=<PLATFORM> \ + -DBUILD_TESTING=OFF \ + -DBUILD_EXAMPLES=OFF \ + -DBUILD_BENCHMARKS=OFF + cmake --build ceres-bin --config Release -``PLATFORM`` can be: ``OS``, ``SIMULATOR`` or ``SIMULATOR64``. You can -build for ``OS`` (``armv7``, ``armv7s``, ``arm64``), ``SIMULATOR`` -(``i386``) or ``SIMULATOR64`` (``x86_64``) separately and use ``lipo`` -to merge them into one static library. See ``cmake/iOS.cmake`` for -more options. +``PLATFORM`` can be ``OS`` (``iphoneos``, ``arm64``), ``SIMULATOR64`` +(``iphonesimulator``, ``x86_64``), or ``SIMULATOR`` (``iphonesimulator``, +``i386``). See ``cmake/iOS.cmake`` for additional options such as +``IOS_DEPLOYMENT_TARGET``. -.. NOTE:: +After building, you will get ``libceres.a`` (and the required ``Abseil`` static +libraries when built from the submodule), which you will need to link into your +Xcode project. - iOS version 11.0+ requires a 64-bit architecture, so you cannot - build for armv7/armv7s with iOS 11.0+ (only arm64 is supported). +The default iOS configuration builds Ceres Solver using ``Eigen`` and +``Abseil``, which is sufficient for solving small to moderate sized problems +(and can also use Apple's ``Accelerate`` sparse solvers when available). -After building, you will get a ``libceres.a`` library, which you will -need to add to your Xcode project. - -The default CMake configuration builds a bare bones version of Ceres -Solver that only depends on Eigen (``MINIGLOG`` is compiled into Ceres -if it is used), this should be sufficient for solving small to -moderate sized problems. - -If you decide to use ``LAPACK`` and ``BLAS``, then you also need to -add ``Accelerate.framework`` to your Xcode project's linking -dependency. +If you decide to use ``Accelerate`` (including ``AccelerateSparse``), you also +need to add ``Accelerate.framework`` to your Xcode project's linked +frameworks. .. _section-customizing: @@ -579,23 +567,11 @@ .. NOTE:: - If you are setting variables via ``-D<VARIABLE>=<VALUE>`` when - calling ``CMake``, it is important to understand that this forcibly - **overwrites** the variable ``<VARIABLE>`` in the ``CMake`` cache at - the start of *every configure*. - - This can lead to confusion if you are invoking the ``CMake`` `curses - <http://www.gnu.org/software/ncurses/ncurses.html>`_ terminal GUI - (via ``ccmake``, e.g. ```ccmake -D<VARIABLE>=<VALUE> - <PATH_TO_SRC>``). In this case, even if you change the value of - ``<VARIABLE>`` in the ``CMake`` GUI, your changes will be - **overwritten** with the value passed via ``-D<VARIABLE>=<VALUE>`` - (if one exists) at the start of each configure. - - As such, it is generally easier not to pass values to ``CMake`` via - ``-D`` and instead interactively experiment with their values in the - ``CMake`` GUI. If they are not present in the *Standard View*, - toggle to the *Advanced View* with ``<t>``. + Passing ``-D<VARIABLE>=<VALUE>`` on the command line forcibly overwrites + ``<VARIABLE>`` in the ``CMake`` cache at the start of every configure. If you + are using the interactive ``ccmake`` terminal GUI, avoid passing ``-D`` on + the ``ccmake`` command line so that interactive changes in the GUI (use + ``<t>`` to toggle *Advanced View*) are not overwritten on reconfigure. Modifying default compilation flags @@ -640,12 +616,11 @@ when the benchmark dependency is available. #. ``BUILD_DOCUMENTATION [Default: OFF]``: Use this to enable building - the documentation. This requires `Sphinx <http://sphinx-doc.org/>`_ and + the documentation. This requires `Sphinx <https://www.sphinx-doc.org/>`_ and the `sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`_ package - available from the Python package index. Configuration fails if either is - unavailable. In addition, ``make ceres_docs`` can be used to build only the - documentation. + available from the Python package index. In addition, ``make ceres_docs`` + can be used to build only the documentation. #. ``BUILD_EXAMPLES [Default: ON]``: Build the Ceres example programs. @@ -659,7 +634,7 @@ installing Ceres. Set this standard CMake variable to ``ON`` to also have ``export(PACKAGE)`` register the build directory in the `user's local CMake package registry - <http://www.cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html#user-package-registry>`_, + <https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#user-package-registry>`_, so that it is found automatically by ``find_package(Ceres)`` without setting ``Ceres_DIR``. It is left disabled by default, matching CMake's own default for ``export(PACKAGE)``. @@ -686,6 +661,10 @@ value can be ``OFF``, ``default``, or ``static``. The latter links against static CUDA runtime libraries when supported. +#. ``WITH_CUDSS [Default: ON]``: Enable NVIDIA cuDSS support for sparse CUDA + linear solvers (``CUDA_SPARSE``). This option is available when ``WITH_CUDA`` + is enabled and the ``cudss`` package is found. + #. ``WITH_CUSTOM_BLAS [Default: ON]``: Use Ceres' custom BLAS routines instead of Eigen's implementations where available. @@ -732,93 +711,118 @@ remove files installed by Ceres. +.. _options-controlling-ceres-dependency-locations: + Options controlling Ceres dependency locations ---------------------------------------------- -Ceres uses the ``CMake`` `find_package -<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ -function to find all of its dependencies. Dependencies that reliably -provide config files on all supported platforms are expected to be -found in "Config" mode of ``find_package`` (``Eigen``, ``gflags``). -This means you can use the standard ``CMake`` facilities to customize -where these dependencies are found, such as ``CMAKE_PREFIX_PATH``, -the ``<DEPENDENCY_NAME>_DIR`` variables, or since ``CMake`` 3.12 the -``<DEPENDENCY_NAME>_ROOT`` variables. +Ceres uses the ``CMake`` `find_package() +<https://cmake.org/cmake/help/latest/command/find_package.html>`_ +command to find all of its dependencies. -Other dependencies are found using -``Find<DEPENDENCY_NAME>.cmake`` scripts which are either included in -Ceres (for most dependencies) or are shipped as standard with -``CMake`` (for ``LAPACK`` & ``BLAS``). These scripts will search all -of the "standard" install locations for various OSs for each -dependency. However, particularly for Windows, they may fail to find -the library, in this case you will have to manually specify its -installed location. The ``Find<DEPENDENCY_NAME>.cmake`` scripts -shipped with Ceres support two ways for you to do this: +#. **Config-mode packages** (``Eigen3``, ``absl``, ``GTest``, ``benchmark``, + ``cudss``, ``TBB``, and ``SuiteSparse`` >= 7.0): -#. Set the *hints* variables specifying the *directories* to search in - preference, but in addition, to the search directories in the - ``Find<DEPENDENCY_NAME>.cmake`` script: + These dependencies provide CMake package configuration files + (``<PackageName>Config.cmake`` or ``<lowercase>-config.cmake``). You can + customize where CMake searches for them using standard CMake variables: - - ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR_HINTS`` - - ``<DEPENDENCY_NAME (CAPS)>_LIBRARY_DIR_HINTS`` + - ``CMAKE_PREFIX_PATH``: A semicolon-separated list of installation prefixes + to search (e.g., ``-DCMAKE_PREFIX_PATH="/opt/local;/custom/prefix"``). + - ``<PackageName>_ROOT``: The installation prefix for a specific package + (e.g., ``-DEigen3_ROOT=/path/to/eigen``, ``-Dabsl_ROOT=/path/to/abseil``, + ``-DTBB_ROOT=/path/to/tbb``). + - ``<PackageName>_DIR``: The exact directory containing the package's + ``<PackageName>Config.cmake`` file (e.g., ``-DEigen3_DIR=...``, + ``-Dabsl_DIR=...``, ``-DGTest_DIR=...``, ``-Dcudss_DIR=...``). - These variables should be set via ``-D<VAR>=<VALUE>`` - ``CMake`` arguments as they are not visible in the GUI. + Note that if ``third_party/abseil-cpp`` and ``third_party/googletest`` are + present (e.g., when Ceres is cloned with ``--recurse-submodules``), Ceres + uses the bundled submodules directly instead of searching for installed + ``absl`` and ``GTest`` packages. -#. Set the variables specifying the *explicit* include directory - and library file to use: +#. **CUDA Toolkit** (``CUDAToolkit``): - - ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR`` - - ``<DEPENDENCY_NAME (CAPS)>_LIBRARY`` + When ``WITH_CUDA`` is enabled, Ceres uses CMake's standard + `FindCUDAToolkit + <https://cmake.org/cmake/help/latest/module/FindCUDAToolkit.html>`_ module. + You can customize the CUDA installation location using ``CUDAToolkit_ROOT`` + or ``CUDACXX``. - This bypasses *all* searching in the - ``Find<DEPENDENCY_NAME>.cmake`` script, but validation is still - performed. +#. **Find-module dependencies** (``METIS``, ``SuiteSparse`` < 7.0 without + CMake config files, ``AccelerateSparse``, and ``Sphinx``): - These variables are available to set in the ``CMake`` GUI. They are - visible in the *Standard View* if the library has not been found - (but the current Ceres configuration requires it), but are always - visible in the *Advanced View*. They can also be set directly via - ``-D<VAR>=<VALUE>`` arguments to ``CMake``. + When a dependency does not provide a CMake package configuration file, Ceres + uses its bundled ``Find<Package>.cmake`` modules. You can guide these modules + using ``CMAKE_PREFIX_PATH``, ``CMAKE_INCLUDE_PATH``, ``CMAKE_LIBRARY_PATH``, + ``<Package>_ROOT``, or by setting explicit cache variables: + + - **METIS**: ``METIS_INCLUDE_DIR`` and ``METIS_LIBRARY``. + - **SuiteSparse** (fallback when ``SuiteSparseConfig.cmake`` is not present): + ``SuiteSparse_<COMPONENT>_INCLUDE_DIR`` and + ``SuiteSparse_<COMPONENT>_LIBRARY`` (for components ``AMD``, ``CAMD``, + ``CCOLAMD``, ``CHOLMOD``, ``COLAMD``, ``SPQR``, ``Config``). + - **Sphinx**: ``Sphinx_EXECUTABLE``. + +.. NOTE:: + + The legacy Ceres-specific ``<DEPENDENCY_NAME>_INCLUDE_DIR_HINTS`` and + ``<DEPENDENCY_NAME>_LIBRARY_DIR_HINTS`` variables from earlier versions of + Ceres have been removed. Use ``CMAKE_PREFIX_PATH`` or ``<PackageName>_ROOT`` + instead. Building using custom BLAS & LAPACK installs ---------------------------------------------- If the standard find package scripts for ``BLAS`` & ``LAPACK`` which ship with ``CMake`` fail to find the desired libraries on your system, -try setting ``CMAKE_LIBRARY_PATH`` to the path(s) to the directories -containing the ``BLAS`` & ``LAPACK`` libraries when invoking ``CMake`` -to build Ceres via ``-D<VAR>=<VALUE>``. This should result in the +try setting ``CMAKE_LIBRARY_PATH`` (or ``CMAKE_PREFIX_PATH``) to the path(s) to +the directories containing the ``BLAS`` & ``LAPACK`` libraries when invoking +``CMake`` to build Ceres via ``-D<VAR>=<VALUE>``. This should result in the libraries being found for any common variant of each. Alternatively, you may also directly specify the ``BLAS_LIBRARIES`` and ``LAPACK_LIBRARIES`` variables via ``-D<VAR>=<VALUE>`` when invoking CMake to configure Ceres. +.. _section-bazel: + +Building with Bazel +=================== + +Ceres Solver also provides a `Bazel <https://bazel.build/>`_ build configuration +using Bzlmod (``MODULE.bazel``), which builds Ceres with ``Eigen`` and +``Abseil`` (and ``GoogleTest`` / ``Google Benchmark`` for tests and benchmarks): + +.. code-block:: bash + + # Build the Ceres library + bazel build //:ceres + + # Build and run the unit tests + bazel test //... + + # Build the example binaries + bazel build //examples/... + .. _section-using-ceres: Using Ceres with CMake ====================== In order to use Ceres in client code with CMake using `find_package() -<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ +<https://cmake.org/cmake/help/latest/command/find_package.html>`_ then either: -#. Ceres must have been installed with ``make install``. If the - install location is non-standard (i.e. is not in CMake's default - search paths) then it will not be detected by default, see: - :ref:`section-local-installations`. +#. Ceres must have been installed with ``cmake --install`` (or + ``make install``). If the install location is non-standard (i.e. is not in + CMake's default search paths) then it will not be detected by default; see + :ref:`section-local-installations`. - Note that if you are using a non-standard install location you - should consider exporting Ceres instead. If registry registration is - also enabled (see ``CMAKE_EXPORT_PACKAGE_REGISTRY``), this will not - require any extra information to be provided in client code for Ceres - to be detected. - -#. Or Ceres' build directory can be used directly through its generated - build-tree package files. Unless registry registration was enabled - when Ceres was configured, set ``Ceres_DIR`` to the Ceres build - directory. +#. Or Ceres' build directory can be used directly without installing (see + :ref:`section-install-vs-export`) by setting ``Ceres_DIR`` to the Ceres + build directory (or by enabling ``CMAKE_EXPORT_PACKAGE_REGISTRY=ON`` when + configuring Ceres). As an example of how to use Ceres, to compile `examples/helloworld.cc @@ -828,7 +832,7 @@ .. code-block:: cmake - cmake_minimum_required(VERSION 3.5) + cmake_minimum_required(VERSION 3.22) project(helloworld) @@ -868,25 +872,32 @@ The Ceres components which can be specified are: -#. ``LAPACK``: Ceres built with direct LAPACK support. +#. ``LAPACK``: Ceres built with direct LAPACK support (``WITH_LAPACK=ON``). -#. ``SuiteSparse``: Ceres built with SuiteSparse support. +#. ``SuiteSparse``: Ceres built with SuiteSparse support (``WITH_SUITESPARSE=ON``). #. ``AccelerateSparse``: Ceres built with Apple's Accelerate sparse solver - support. + support (``WITH_ACCELERATESPARSE=ON``). #. ``EigenSparse``: Ceres built with Eigen's sparse Cholesky factorization - support. + support (``WITH_EIGENSPARSE=ON``). + +#. ``cuDSS``: Ceres built with NVIDIA cuDSS sparse solver support + (``WITH_CUDA`` and ``WITH_CUDSS=ON``). #. ``SparseLinearAlgebraLibrary``: Ceres built with *at least one* sparse linear algebra library. This is equivalent to - ``SuiteSparse`` **OR** ``AccelerateSparse`` **OR** ``EigenSparse``. + ``SuiteSparse`` **OR** ``AccelerateSparse`` **OR** ``EigenSparse`` **OR** + ``cuDSS``. -#. ``SchurSpecializations``: Ceres built with Schur specializations. +#. ``SchurSpecializations``: Ceres built with Schur specializations + (``WITH_SCHUR_SPECIALIZATIONS=ON``). + +#. ``Multithreading``: Ceres built with multithreading support. To specify one/multiple Ceres components use the ``COMPONENTS`` argument to `find_package() -<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ like so: +<https://cmake.org/cmake/help/latest/command/find_package.html>`_ like so: .. code-block:: cmake @@ -904,12 +915,12 @@ Additionally, when CMake has found Ceres it can optionally check the package version, if it has been specified in the `find_package() -<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ +<https://cmake.org/cmake/help/latest/command/find_package.html>`_ call. For example: .. code-block:: cmake - find_package(Ceres 1.2.3 REQUIRED) + find_package(Ceres 2.3.0 REQUIRED) .. _section-local-installations: @@ -917,21 +928,18 @@ ------------------- If Ceres was installed in a non-standard path by specifying -``-DCMAKE_INSTALL_PREFIX="/some/where/local"``, then the user should -add the **PATHS** option to the ``find_package()`` command, e.g., +``-DCMAKE_INSTALL_PREFIX="/some/where/local"``, you can either pass +``-DCMAKE_PREFIX_PATH="/some/where/local"`` (or +``-DCeres_DIR="/some/where/local/lib/cmake/Ceres"``) when running CMake to +configure your project, or add the **PATHS** option to the ``find_package()`` +command in your ``CMakeLists.txt``: .. code-block:: cmake find_package(Ceres REQUIRED PATHS "/some/where/local/") -Note that this can be used to have multiple versions of Ceres -installed. However, particularly if you have only a single version of -Ceres which you want to use but do not wish to install to a system -location, you should consider using Ceres' build-tree package export instead -of a local install. Build-tree exports are automatically detected, -irrespective of their location, only when registry registration was enabled -via ``CMAKE_EXPORT_PACKAGE_REGISTRY`` when Ceres was configured. Otherwise -set ``Ceres_DIR`` to the Ceres build directory. +If you do not wish to install Ceres to a system location, you can also use +Ceres directly from its build directory (see :ref:`section-install-vs-export`). Understanding the CMake Package System ---------------------------------------- @@ -941,31 +949,25 @@ crop up when using Ceres. For more detailed CMake usage, the following references are very useful: -- The `official CMake tutorial <http://www.cmake.org/cmake-tutorial/>`_ +- The `official CMake tutorial <https://cmake.org/cmake/help/latest/guide/tutorial/index.html>`_ Provides a tour of the core features of CMake. -- `ProjectConfig tutorial - <http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file>`_ - and the `cmake-packages documentation - <http://www.cmake.org/cmake/help/git-master/manual/cmake-packages.7.html>`_ +- `cmake-packages documentation + <https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html>`_ - Cover how to write a ``ProjectConfig.cmake`` file, discussed below, - for your own project when installing or exporting it using CMake. - It also covers how these processes in conjunction with - ``find_package()`` are actually handled by CMake. The - `ProjectConfig tutorial - <http://www.cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file>`_ - is the older style, currently used by Ceres for compatibility with - older versions of CMake. + Covers how to write a ``ProjectConfig.cmake`` file, discussed below, + for your own project when installing or exporting it using CMake, + and how these processes in conjunction with ``find_package()`` are + handled by CMake. .. NOTE :: **Targets in CMake.** All libraries and executables built using CMake are represented as *targets* created using `add_library() - <http://www.cmake.org/cmake/help/v3.5/command/add_library.html>`_ + <https://cmake.org/cmake/help/latest/command/add_library.html>`_ and `add_executable() - <http://www.cmake.org/cmake/help/v3.5/command/add_executable.html>`_. + <https://cmake.org/cmake/help/latest/command/add_executable.html>`_. Targets encapsulate the rules and dependencies (which can be other targets) required to build or link against an object. This allows CMake to implicitly manage dependency chains. Thus it is @@ -975,15 +977,14 @@ public dependencies of ``A``. When a project like Ceres is installed using CMake, or its build -directory is exported into the local CMake package registry (see -:ref:`section-install-vs-export`), in addition to the public headers -and compiled libraries, a set of CMake-specific project configuration -files are also installed to: ``<INSTALL_ROOT>/lib/cmake/Ceres`` (if Ceres -is installed), or created in the build directory (if Ceres' build -directory is exported). When `find_package -<http://www.cmake.org/cmake/help/v3.5/command/find_package.html>`_ is +directory is exported (see :ref:`section-install-vs-export`), in addition to +the public headers and compiled libraries, a set of CMake-specific project +configuration files are also installed to: ``<INSTALL_ROOT>/lib/cmake/Ceres`` +(if Ceres is installed), or created in the build directory. When `find_package +<https://cmake.org/cmake/help/latest/command/find_package.html>`_ is invoked, CMake checks various standard install locations (including -``/usr/local`` on Linux & UNIX systems), and the local CMake package +``/usr/local`` on Linux & UNIX systems), any paths specified via +``CMAKE_PREFIX_PATH`` or ``Ceres_DIR``, and the local CMake package registry for CMake configuration files for the project to be found (i.e. Ceres in the case of ``find_package(Ceres)``). Specifically it looks for: @@ -1023,24 +1024,15 @@ its export targets: ``Ceres::ceres``. However, historically the Ceres target did not have a namespace, and was just called ``ceres``. -Whilst an alias target called ``ceres`` is still provided in v2.0 for backwards -compatibility, it creates a potential drawback, if you failed to call +Whilst a deprecated target called ``ceres`` is still provided for backwards +compatibility (and emits a CMake deprecation warning when linked against), it +creates a potential drawback: if you failed to call ``find_package(Ceres)``, and Ceres is installed in a default search path for your compiler, then instead of matching the imported Ceres target, it will -instead match the installed libceres.so/dylib/a library. If this happens you -will get either compiler errors for missing include directories or linker errors -due to missing references to Ceres public dependencies. - -Note that this description applies both to projects that are -**installed** using CMake, and to those whose **build directory is -exported** using `export() -<http://www.cmake.org/cmake/help/v3.5/command/export.html>`_ (instead -of `install() -<http://www.cmake.org/cmake/help/v3.5/command/install.html>`_). Ceres -supports both installation and export of its build directory. The build-tree -package files are always generated. The standard -``CMAKE_EXPORT_PACKAGE_REGISTRY`` variable controls whether the build directory -is added to the user package registry. +instead match the installed ``libceres.so``/``dylib``/``a`` library. If this +happens you will get either compiler errors for missing include directories or +linker errors due to missing references to Ceres public dependencies. Always +link against ``Ceres::ceres``. .. _section-install-vs-export: @@ -1049,17 +1041,23 @@ When a project is **installed**, the compiled libraries and headers are copied from the source & build directory to the install location, -and it is these copied files that are used by any client code. When a -project's build directory is **exported**, instead of copying the -compiled libraries and headers, CMake creates an entry for the project -in the `user's local CMake package registry -<http://www.cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html#user-package-registry>`_, -``<USER_HOME>/.cmake/packages`` on Linux & macOS, which contains the -path to the project's build directory which will be checked by CMake -during a call to ``find_package()``. The effect of which is that any -client code uses the compiled libraries and headers in the build -directory directly, **thus not requiring the project to be installed -to be used**. +and it is these copied files that are used by any client code. + +Ceres also generates ``CeresConfig.cmake`` and ``CeresTargets.cmake`` directly +in its **build directory** using `export() +<https://cmake.org/cmake/help/latest/command/export.html>`_, so client code can +use the compiled libraries and headers in the build directory directly +**without requiring Ceres to be installed**: + +- By default, you can point a client project at the Ceres build directory by + passing ``-DCeres_DIR=/path/to/ceres-bin`` when configuring the client + project. +- Alternatively, if you pass ``-DCMAKE_EXPORT_PACKAGE_REGISTRY=ON`` when + configuring Ceres, CMake also records the path to the Ceres build directory + in the `user's local CMake package registry + <https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html#user-package-registry>`_ + (``<USER_HOME>/.cmake/packages`` on Linux & macOS), which is checked + automatically during ``find_package(Ceres)``. Installing / Exporting a project that uses Ceres -------------------------------------------------- @@ -1074,30 +1072,24 @@ Thus, when a project ``Foo`` which uses Ceres is exported, its list of dependencies as seen by another project ``Bar`` which imports ``Foo`` -via: ``find_package(Foo REQUIRED)`` will contain: ``ceres``. However, -the definition of ``ceres`` as an imported target is **not -(re)exported** when Foo is exported. Hence, without any additional -steps, when processing ``Bar``, ``ceres`` will not be defined as an -imported target. Thus, when processing ``Bar``, CMake will assume -that ``ceres`` refers only to: ``libceres.a/so/dylib/lib`` (the -compiled Ceres library) directly if it is on the current list of -search paths. In which case, no CMake errors will occur, but ``Bar`` -will not link properly, as it does not have the required public link -dependencies of Ceres, which are stored in the imported target -definition. +via: ``find_package(Foo REQUIRED)`` will contain: ``Ceres::ceres``. However, +the definition of ``Ceres::ceres`` as an imported target is **not +(re)exported** when ``Foo`` is exported. Hence, without any additional +steps, when processing ``Bar``, ``Ceres::ceres`` will not be defined as an +imported target. The solution to this is for ``Foo`` (i.e., the project that uses -Ceres) to invoke ``find_package(Ceres)`` in ``FooConfig.cmake``, thus -``ceres`` will be defined as an imported target when CMake processes +Ceres) to invoke ``find_dependency(Ceres)`` in ``FooConfig.cmake``, thus +``Ceres::ceres`` will be defined as an imported target when CMake processes ``Bar``. An example of the required modifications to -``FooConfig.cmake`` are show below: +``FooConfig.cmake`` is shown below: .. code-block:: cmake - # Importing Ceres in FooConfig.cmake using CMake 3.x style. + # Importing Ceres in FooConfig.cmake. # - # In CMake v3.x, the find_dependency() macro exists to forward the REQUIRED - # / QUIET parameters to find_package() when searching for dependencies. + # The find_dependency() macro forwards the REQUIRED / QUIET parameters to + # find_package() when searching for dependencies. # # Note that find_dependency() does not take a path hint, so if Ceres was # installed in a non-standard location, that location must be added to @@ -1112,6 +1104,54 @@ The following includes some hints for migrating from previous versions. +Version 2.3 +----------- + +- **Abseil replaces glog, gflags, and miniglog**: ``google-glog``, ``gflags``, + and ``MINIGLOG`` are no longer used by Ceres. Instead, Ceres requires + `Abseil <https://abseil.io/>`_ (version ``20240116`` or later) and uses + `GoogleTest <https://github.com/google/googletest>`_ (version ``1.14.0`` or + later) when ``BUILD_TESTING=ON``. If your system does not provide recent + enough versions of ``Abseil`` or ``GoogleTest``, clone Ceres with + ``git clone --recurse-submodules`` so that CMake automatically builds the + bundled submodules in ``third_party/``. +- **CMake minimum version**: Building Ceres now requires CMake 3.22 or later. +- **CMake feature options use the ``WITH_`` prefix**: + The Ceres-specific CMake options have been standardized to use the ``WITH_`` + prefix: + + - ``SUITESPARSE`` :math:`\rightarrow` ``WITH_SUITESPARSE`` + - ``EIGENSPARSE`` :math:`\rightarrow` ``WITH_EIGENSPARSE`` + - ``ACCELERATESPARSE`` :math:`\rightarrow` ``WITH_ACCELERATESPARSE`` + - ``USE_CUDA`` :math:`\rightarrow` ``WITH_CUDA`` (accepts ``OFF``, + ``default``, or ``static``) + - ``LAPACK`` :math:`\rightarrow` ``WITH_LAPACK`` + - ``CUSTOM_BLAS`` :math:`\rightarrow` ``WITH_CUSTOM_BLAS`` + - ``EIGENMETIS`` :math:`\rightarrow` ``WITH_EIGENMETIS`` + - ``SCHUR_SPECIALIZATIONS`` :math:`\rightarrow` ``WITH_SCHUR_SPECIALIZATIONS`` + - ``IOS_BITCODE`` :math:`\rightarrow` ``WITH_BITCODE`` + - ``ANDROID_STRIP_DEBUG_SYMBOLS`` :math:`\rightarrow` + ``WITH_STRIPPED_DEBUG_SYMBOLS`` + - ``PROVIDE_UNINSTALL_TARGET`` :math:`\rightarrow` ``WITH_UNINSTALL_TARGET`` + +- **SuiteSparse is now opt-in (``WITH_SUITESPARSE=OFF`` by default)**: + Because ``SuiteSparse``'s supernodal ``CHOLMOD`` and ``SPQR`` components are + licensed under the GPL, ``WITH_SUITESPARSE`` now defaults to ``OFF``. Pass + ``-DWITH_SUITESPARSE=ON`` to CMake to build Ceres with ``SuiteSparse`` + support. +- **Standard CMake variables replace custom Ceres variables**: + + - ``EXPORT_BUILD_DIR`` has been removed; use the standard + ``CMAKE_EXPORT_PACKAGE_REGISTRY`` variable instead. + - ``LIB_SUFFIX`` has been removed; use the standard ``CMAKE_INSTALL_LIBDIR`` + variable instead. + - ``MSVC_USE_STATIC_CRT`` has been removed; use the standard + ``CMAKE_MSVC_RUNTIME_LIBRARY`` variable instead. + - Custom ``<DEPENDENCY>_INCLUDE_DIR_HINTS`` and + ``<DEPENDENCY>_LIBRARY_DIR_HINTS`` variables have been removed; use + ``CMAKE_PREFIX_PATH``, ``<PackageName>_ROOT``, or ``<PackageName>_DIR`` + instead. + Version 2.0 ----------- @@ -1122,13 +1162,6 @@ exported Ceres CMake target already contains the definitions of its public include directories which will be automatically included by CMake when compiling a target that links against Ceres. -- When building Ceres, some dependencies (Eigen, gflags) are not found - using custom ``Find<DEPENDENCY_NAME>.cmake`` modules any - more. Hence, instead of the custom variables (``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR_HINTS``, - ``<DEPENDENCY_NAME (CAPS)>_INCLUDE_DIR``, ...) you should use standard - CMake facilities to customize where these dependencies are found, such as - ``CMAKE_PREFIX_PATH``, the ``<DEPENDENCY_NAME>_DIR`` variables, or - since CMake 3.12 the ``<DEPENDENCY_NAME>_ROOT`` variables. - While TBB is not used any more directly by Ceres, it might still try to link against it, if SuiteSparseQR was found. The variable (environment or CMake) to customize this is ``TBB_ROOT`` (used to be ``TBBROOT``).
diff --git a/docs/source/modeling_faqs.rst b/docs/source/modeling_faqs.rst index b51380a..b6cafcf 100644 --- a/docs/source/modeling_faqs.rst +++ b/docs/source/modeling_faqs.rst
@@ -48,7 +48,7 @@ .. NOTE:: If you are using `Eigen's Quaternion - <http://eigen.tuxfamily.org/dox/classEigen_1_1Quaternion.html>`_ + <https://libeigen.gitlab.io/eigen/docs-nightly/classEigen_1_1Quaternion.html>`_ object, whose layout is :math:`x,y,z,w`, then you should use :class:`EigenQuaternionManifold`.
diff --git a/docs/source/nnls_covariance.rst b/docs/source/nnls_covariance.rst index f95d246..8b82887 100644 --- a/docs/source/nnls_covariance.rst +++ b/docs/source/nnls_covariance.rst
@@ -142,7 +142,7 @@ .. member:: SparseLinearAlgebraLibraryType Covariance::Options::sparse_linear_algebra_library_type Default: ``SUITE_SPARSE`` Ceres Solver is built with support for - `SuiteSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_ + `SuiteSparse <https://people.engr.tamu.edu/davis/suitesparse.html>`_ and ``EIGEN_SPARSE`` otherwise. Note that ``EIGEN_SPARSE`` is always available.
diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst index 004ccbd..975056e 100644 --- a/docs/source/nnls_modeling.rst +++ b/docs/source/nnls_modeling.rst
@@ -1636,7 +1636,7 @@ .. class:: EigenQuaternionManifold Implements the quaternion manifold for `Eigen's -<http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ +<https://libeigen.gitlab.io/>`_ representation of the Hamilton quaternion. Geometrically it is exactly the same as the :class:`QuaternionManifold` defined above. However, Eigen uses a different internal memory layout for the elements of the
diff --git a/docs/source/nnls_solving.rst b/docs/source/nnls_solving.rst index 3d58a70..8e2b2d4 100644 --- a/docs/source/nnls_solving.rst +++ b/docs/source/nnls_solving.rst
@@ -486,7 +486,7 @@ By default (``Solver::Options::dense_linear_algebra_library_type = EIGEN``) Ceres Solver will use `Eigen Householder QR factorization -<https://eigen.tuxfamily.org/dox-devel/classEigen_1_1HouseholderQR.html>`_ +<https://libeigen.gitlab.io/eigen/docs-nightly/classEigen_1_1HouseholderQR.html>`_ . If Ceres Solver has been built with an optimized LAPACK @@ -497,7 +497,7 @@ implementation this may perform better than using Eigen's Householder QR factorization. -.. _DGEQRF: https://netlib.org/lapack/explore-html/df/dc5/group__variants_g_ecomputational_ga3766ea903391b5cf9008132f7440ec7b.html +.. _DGEQRF: https://www.netlib.org/lapack/explore-html/d3/d69/dgeqrf_8f.html If an NVIDIA GPU is available and Ceres Solver has been built with @@ -554,7 +554,7 @@ By default (``Solver::Options::dense_linear_algebra_library_type = EIGEN``) Ceres Solver will use `Eigen's LLT factorization`_ routine. -.. _Eigen's LLT Factorization: https://eigen.tuxfamily.org/dox/classEigen_1_1LLT.html +.. _Eigen's LLT Factorization: https://libeigen.gitlab.io/eigen/docs-nightly/classEigen_1_1LLT.html If Ceres Solver has been built with an optimized LAPACK implementation, then the user can also choose to use LAPACK's @@ -564,7 +564,7 @@ implementation this may perform better than using Eigen's Cholesky factorization. -.. _DPOTRF: https://www.netlib.org/lapack/explore-html/d1/d7a/group__double_p_ocomputational_ga2f55f604a6003d03b5cd4a0adcfb74d6.html +.. _DPOTRF: https://www.netlib.org/lapack/explore-html/d0/d8a/dpotrf_8f.html If an NVIDIA GPU is available and Ceres Solver has been built with CUDA support enabled, then the user can also choose to perform the @@ -601,20 +601,22 @@ 1. `SuiteSparse <https://people.engr.tamu.edu/davis/suitesparse.html>`_ (``SUITE_SPARSE``). 2. `Apple's Accelerate framework - <https://developer.apple.com/documentation/accelerate/sparse_solvers?language=objc>`_ + <https://developer.apple.com/documentation/accelerate/sparse-solvers-library?language=objc>`_ (``ACCELERATE_SPARSE``). 3. `Eigen's sparse linear solvers - <https://eigen.tuxfamily.org/dox/group__SparseCholesky__Module.html>`_ + <https://libeigen.gitlab.io/eigen/docs-nightly/group__SparseCholesky__Module.html>`_ (``EIGEN_SPARSE``). + 4. `NVIDIA's cuDSS library + <https://developer.nvidia.com/cudss>`_ + (``CUDA_SPARSE``). -SuiteSparse and Accelerate offer high performance sparse Cholesky -factorization routines as they level-3 BLAS routines -internally. Eigen's sparse Cholesky routines are *simplicial* and do +SuiteSparse, Accelerate, and cuDSS offer high performance sparse Cholesky +factorization routines (using level-3 BLAS routines on the CPU or GPU +acceleration via CUDA). Eigen's sparse Cholesky routines are *simplicial* and do not use dense linear algebra routines and as a result cannot compete -with SuiteSparse and Accelerate, especially on large problems. As a +with SuiteSparse, Accelerate, or cuDSS, especially on large problems. As a result to get the best performance out of SuiteSparse it should be -linked to high quality BLAS and LAPACK implementations e.g. `ATLAS -<https://math-atlas.sourceforge.net/>`_, `OpenBLAS +linked to high quality BLAS and LAPACK implementations e.g. `OpenBLAS <https://www.openblas.net/>`_ or `Intel MKL <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_. @@ -1658,25 +1660,28 @@ Default: The highest available according to: ``SUITE_SPARSE`` > ``ACCELERATE_SPARSE`` > ``EIGEN_SPARSE`` > ``NO_SPARSE`` - Ceres supports the use of three sparse linear algebra libraries, + Ceres supports the use of four sparse linear algebra libraries: ``SuiteSparse``, which is enabled by setting this parameter to - ``SUITE_SPARSE``, ``Acclerate``, which can be selected by setting - this parameter to ``ACCELERATE_SPARSE`` and ``Eigen`` which is - enabled by setting this parameter to ``EIGEN_SPARSE``. Lastly, - ``NO_SPARSE`` means that no sparse linear solver should be used; - note that this is irrespective of whether Ceres was compiled with - support for one. + ``SUITE_SPARSE``; Apple's ``Accelerate`` framework, which can be + selected by setting this parameter to ``ACCELERATE_SPARSE``; + ``Eigen``, which is enabled by setting this parameter to + ``EIGEN_SPARSE``; and NVIDIA's ``cuDSS``, which is enabled by + setting this parameter to ``CUDA_SPARSE``. Lastly, ``NO_SPARSE`` + means that no sparse linear solver should be used; note that this is + irrespective of whether Ceres was compiled with support for one. ``SuiteSparse`` is a sophisticated sparse linear algebra library - and should be used in general. On MacOS you may want to use the - ``Accelerate`` framework. + and should be used in general on the CPU. On macOS you may want to use the + ``Accelerate`` framework, and on systems with an NVIDIA GPU and ``cuDSS`` + installed you can use ``CUDA_SPARSE`` for GPU-accelerated sparse + factorizations. If your needs/platforms prevent you from using ``SuiteSparse``, consider using the sparse linear algebra routines in ``Eigen``. The sparse Cholesky algorithms currently included with ``Eigen`` are - not as sophisticated as the ones in ``SuiteSparse`` and - ``Accelerate`` and as a result its performance is considerably - worse. + not as sophisticated as the ones in ``SuiteSparse``, + ``Accelerate``, and ``cuDSS``, and as a result its performance is + considerably worse. .. member:: LinearSolverOrderingType Solver::Options::linear_solver_ordering_type
diff --git a/docs/source/nnls_tutorial.rst b/docs/source/nnls_tutorial.rst index 2304e70..a2be7de 100644 --- a/docs/source/nnls_tutorial.rst +++ b/docs/source/nnls_tutorial.rst
@@ -100,7 +100,7 @@ .. code-block:: c++ int main(int argc, char** argv) { - google::InitGoogleLogging(argv[0]); + absl::InitializeLog(); // The variable to solve for with its initial value. double initial_x = 5.0; @@ -394,7 +394,7 @@ 13 1.791438e-14 2.69e-13 2.91e-10 3.01e-04 9.37e-01 1.59e+10 1 1.91e-06 4.45e-04 14 1.120029e-15 1.68e-14 3.64e-11 1.51e-04 9.37e-01 4.78e+10 1 2.15e-06 4.48e-04 - Solver Summary (v 2.2.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) + Solver Summary (v 2.3.0-eigen-(3.4.0)-lapack-suitesparse-(7.1.0)-metis-(5.1.0)-acceleratesparse-eigensparse) Original Reduced Parameter blocks 4 4 @@ -611,7 +611,7 @@ for solving bundle adjustment problems. Let us solve a problem from the `BAL -<http://grail.cs.washington.edu/projects/bal/>`_ dataset [#f8]_. +<https://grail.cs.washington.edu/projects/bal/>`_ dataset [#f8]_. The first step as usual is to define a templated functor that computes the reprojection error/residual. The structure of the functor is @@ -623,8 +623,8 @@ are: three for rotation as a Rodrigues' axis-angle vector, three for translation, one for focal length and two for radial distortion. The details of this camera model can be found the `Bundler homepage -<http://phototour.cs.washington.edu/bundler/>`_ and the `BAL homepage -<http://grail.cs.washington.edu/projects/bal/>`_. +<https://www.cs.cornell.edu/~snavely/bundler/>`_ and the `BAL homepage +<https://grail.cs.washington.edu/projects/bal/>`_. .. code-block:: c++ @@ -766,13 +766,13 @@ #. `denoising.cc <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/denoising.cc>`_ implements image denoising using the `Fields of Experts - <http://www.gris.informatik.tu-darmstadt.de/~sroth/research/foe/index.html>`_ + <https://doi.org/10.1007/s11263-008-0197-6>`_ model. #. `nist.cc <https://ceres-solver.googlesource.com/ceres-solver/+/master/examples/nist.cc>`_ implements and attempts to solves the `NIST - <http://www.itl.nist.gov/div898/strd/nls/nls_main.shtml>`_ + <https://www.itl.nist.gov/div898/strd/nls/nls_main.shtml>`_ non-linear regression problems. #. `more_garbow_hillstrom.cc
diff --git a/docs/source/version_history.rst b/docs/source/version_history.rst index 29cd06c..8f37367 100644 --- a/docs/source/version_history.rst +++ b/docs/source/version_history.rst
@@ -14,32 +14,163 @@ Unreleased ========== -Bug Fixes & Minor Changes -------------------------- +New Features +------------ -#. Clarify building Ceres Solver from Git sources in the installation - documentation. +#. Added ``CUDA_SPARSE`` sparse linear algebra library backend powered by + NVIDIA ``cuDSS``, enabling GPU-accelerated ``SPARSE_NORMAL_CHOLESKY`` and + ``SPARSE_SCHUR`` solves. (Mark Shachkov, Ben Hamilton & Sameer Agarwal) +#. Mixed precision solves + iterative refinement when using ``SUITE_SPARSE`` + as the sparse linear algebra library (requires SuiteSparse 7.4.0 or later + for single-precision ``CHOLMOD``). (Sameer Agarwal) +#. Added ``AccurateNorm`` for overflow and underflow safe variadic norms + accurate to nearly full working precision. Its Jet derivatives are defined + wherever the norm is nonzero, unlike those of nested two-argument norms. + (Sergiu Deitsch) +#. Simplify instantiation of cost functions and their functors by forwarding + functor constructor arguments directly, and add ``std::unique_ptr`` and + :enum:`Ownership` constructors across cost and first-order functions. + (Sergiu Deitsch & Sameer Agarwal) +#. Add support for maximum matrix sizes (``kMaxResiduals`` and + ``kMaxParameters``) to :class:`TinySolver`, + :class:`TinySolverAutoDiffFunction`, and + :class:`TinySolverCostFunctionAdapter` to support zero dynamic memory + allocation when dimensions are ``Eigen::Dynamic``. (Pez Firoozfam) +#. Add ``Residuals()`` and ``Jacobian()`` getters to :class:`TinySolver`. + (connorlee77) +#. Do not restrict :class:`Grid1D` and :class:`Grid2D` output to ``double``. + (Sergiu Deitsch) +#. Allow :func:`AngleAxisRotatePoint` to be applied in-place. (Sergiu Deitsch + & @CatInTheRain) +#. Allow specifying the memory layout of quaternion coefficients via a + template parameter in rotation functions and reuse rotation functionality in + :class:`QuaternionManifold` and :class:`EigenQuaternionManifold`. (Sergiu + Deitsch) +#. Provide ``Eigen::NumTraits`` ``quiet_NaN`` and ``infinity`` for + :class:`Jet`. (Sergiu Deitsch) +#. Move C++17 Bessel functions availability checks from configuration time to + inclusion time, with fallback to POSIX implementations on ``libc++``. + (Sergiu Deitsch) + Backward Incompatible API Changes --------------------------------- -#. The ``SUITESPARSE`` CMake option now defaults to ``OFF``. Passing - ``-DSUITESPARSE=ON`` restores the previous behavior, but makes the - resulting Ceres build GPL licensed unless you hold a commercial - SuiteSparse license. +#. ``glog``, ``gflags``, and ``MINIGLOG`` have been removed and replaced by + `Abseil <https://abseil.io/>`_ (version ``20240116`` or later). + `GoogleTest <https://github.com/google/googletest>`_ (version ``1.14.0`` or + later) is now required when ``BUILD_TESTING=ON``. (Sameer Agarwal, Reinhold + Gschweicher & Sergiu Deitsch) +#. :class:`GradientProblem` and related classes now exclusively use + ``std::unique_ptr`` instead of raw pointers for ownership transfer. (Sameer + Agarwal) +#. Fix casing of ``StringToLoggingType`` and ``StringToDumpFormatType`` + (formerly ``StringToLoggingtype`` and ``StringToDumpFormatype``) for + consistency with the rest of the API, and fix a duplicate declaration in + ``ceres/types.h``. (Sameer Agarwal) +#. Ceres Solver now requires CMake 3.22 or later and Eigen 3.3.4 or later. + (Sergiu Deitsch) +#. The ``WITH_SUITESPARSE`` CMake option (formerly ``SUITESPARSE``) now + defaults to ``OFF``. Passing ``-DWITH_SUITESPARSE=ON`` restores the + previous behavior, but makes the resulting Ceres build GPL licensed unless + you hold a commercial SuiteSparse license. (Sergiu Deitsch) #. CMake configuration now reports dependencies using standard package output and ``FeatureSummary``, and feature options are renamed with a ``WITH_`` - prefix (e.g. ``SUITESPARSE`` is now ``WITH_SUITESPARSE``). The - ``LIB_SUFFIX``, ``MSVC_USE_STATIC_CRT``, and ``EXPORT_BUILD_DIR`` options - are removed in favor of standard CMake variables. CMake 3.22 or later is - now required. See :ref:`options-controlling-ceres-configuration`. + prefix (e.g. ``SUITESPARSE`` is now ``WITH_SUITESPARSE``, ``USE_CUDA`` is + now ``WITH_CUDA``). The ``LIB_SUFFIX``, ``MSVC_USE_STATIC_CRT``, + ``EXPORT_BUILD_DIR``, and ``<DEPENDENCY>_INCLUDE/LIBRARY_DIR_HINTS`` + options are removed in favor of standard CMake variables. See + :ref:`options-controlling-ceres-configuration`. (Sergiu Deitsch) +#. Linking against the legacy unscoped ``ceres`` CMake import target now emits + a deprecation warning; link against ``Ceres::ceres`` instead. (Sergiu + Deitsch) +#. Support for 32-bit MinGW has been removed. (Sergiu Deitsch) -New Features ------------- -#. Added ``AccurateNorm`` for overflow and underflow safe variadic norms - accurate to nearly full working precision. Its Jet derivatives are defined - wherever the norm is nonzero, unlike those of nested two-argument norms. +Bug Fixes & Minor Changes +------------------------- + +#. Use ``absl`` hash and B-tree containers in graph algorithms and + preprocessor, substantially reducing preprocessor time when finding an + automatic Schur ordering. (Sameer Agarwal) +#. Remove a level of indirection when using ``CellInfo``, improving the + performance of the Schur eliminator and block diagonal preconditioners. + (Sameer Agarwal) +#. Reorder the fields in ``ParameterBlock`` to group hot fields together and + reduce cache misses. (Sameer Agarwal) +#. Preserve caller orderings during preprocessing so subsequent ``Solve`` + calls are not mutated. (RanaPriyansh) +#. Apply deterministic parameter block reordering. (Johannes Schönberger) +#. Fix threading bug in ``CovarianceImpl`` where an extra thread was spawned + even when ``num_threads = 1``. (Matt Vitelli) +#. Fix a bug in inner iterations where round-off error could cause an inner + iteration with slightly higher cost to be accepted. (Sameer Agarwal) +#. Skip structure detection on preprocessor failure. (Dmitriy Korchemkin) +#. Fix discrepancy in ``QuaternionRotatePoint`` for different quaternion + orders. (Sergiu Deitsch) +#. Do not differentiate the norm at gimbal lock to avoid ``NaN`` derivatives. + (Sergiu Deitsch) +#. Use Euler parameters in ``QuaternionPlusImpl`` while preserving the + half-angle tangent space scaling convention. (Sergiu Deitsch) +#. Avoid division by zero in rotation routines under + ``-fsanitize=float-divide-by-zero`` and partially revert 3-argument + ``std::hypot`` zero checks due to ``libc++`` underflow. (Sergiu Deitsch) +#. Fix an initialization order error in ``cuda_sparse_cholesky.cc``. (Sameer + Agarwal) +#. Fix ODR violations when compiling Ceres with Schur specializations and Link + Time Optimization (LTO). (Sergiu Deitsch) +#. Ensure ``DynamicCostFunctionToFunctor`` is exported in shared library + builds and ensure consistent visibility attributes. (Sergiu Deitsch) +#. Do not rely on a preprocessor define for disabling warnings in public + headers. (Sergiu Deitsch) +#. Modernize public and internal headers (``AutoDiffCostFunction``, + ``NumericDiffCostFunction``, ``ProductManifold``, ``EuclideanManifold``, + ``TinySolver``, ``InvertPSDMatrix``, ``ParameterBlock``, + ``cubic_interpolation.h``, ``parameter_dims.h``, ``jet_traits.h``) to C++17 + and Abseil conventions (``absl::FixedArray``, ``absl::strings``, + ``absl::time``, ``std::string_view``), add an ``EventLogger`` to + ``TrustRegionPreprocessor``, and extensive ClangTidy cleanups. (Sameer + Agarwal) +#. Support Eigen 5.0.0. (Sergiu Deitsch) +#. Support CUDA 13 (Mackay), set ``CMAKE_CUDA_ARCHITECTURES`` depending on + ``CUDAToolkit_VERSION`` and link static CUDA libraries when configured + (Markus Heß), expose Hopper (``sm_90``) support only for CUDA 12.0 and + later, and replace ``--extended-lambda`` with ``--expt-extended-lambda`` + for NVCC (Sameer Agarwal). +#. Update bundled dependencies to support GCC 15. (Sergiu Deitsch & @adam-ce) +#. Fix Abseil CMake package configuration usage, version checking, and + ``absl::log_flags`` linking. (Reinhold Gschweicher, Sameer Agarwal & Sergiu + Deitsch) +#. Make ``test_util`` GTest-optional to fix benchmark builds when + ``BUILD_TESTING=OFF``. (Sameer Agarwal) +#. Fix vector operations benchmark compilation (Sergey Sharybin) and eliminate + Google Benchmark deprecation warnings (Sergiu Deitsch). +#. Do not export the SuiteSparse ``Partition`` target and make SuiteSparse + partitioning detection more robust. (Sergiu Deitsch) +#. Do not discard caller's ``CMAKE_MODULE_PATH`` in ``CeresConfig.cmake``, use + native CMake ``TBB`` package configuration, do not assume Homebrew usage on + macOS, and enable Apple linker library deduplication. (Sergiu Deitsch) +#. Fix shared library builds, MSVC builds, CTest build configuration + parameters, and bundle adjuster perturbation assertions in debug mode. + (Sergiu Deitsch) +#. Fix Clang 16 compiler warnings (Johannes Schönberger), CUDA set-but-unused + variable warnings (Sergiu Deitsch), and missing ``std`` qualifiers and + header includes (Yuriy Chernyshov, Sergiu Deitsch & Sameer Agarwal). +#. Reuse macro to format version string (Mark Shachkov) and remove remaining + references to ``CXSparse`` and + ``CreateFakeBundleAdjustmentPartitionedJacobian`` (Sameer Agarwal). +#. Fix and modernize the Bazel build to use Bzlmod (``MODULE.bazel``), support + Bazel 8/9, and add missing sources, tests, benchmarks, and examples. + (Sameer Agarwal, Sergiu Deitsch & Laurenz) +#. Add ReadTheDocs support, specify docs requirements, fix search on + ``ceres-solver.org``, document ``DumpLinearLeastSquaresProblem``, update + ``GradientChecker`` and installation docs, and fix various documentation + typos. (Sergiu Deitsch, Sameer Agarwal, Maxim Smolskiy, brettmichaelgreen, + reprojection.calibration, Ian Muldoon, Johannes Bruenger, @sarlinpe, Roger + Labbe & @valgur) +#. Numerous GitHub Actions CI improvements (Ubuntu 24.04, macOS 14/15, Visual + Studio 2022, CUDA 12.5.1, Android NDK LTS, ``mold`` linker, SuiteSparse + testing, submodule checkout). (Sergiu Deitsch & Mark Shachkov) 2.2.0 =====
diff --git a/package.xml b/package.xml index 7e9aeb3..e94bdb5 100644 --- a/package.xml +++ b/package.xml
@@ -43,6 +43,7 @@ <build_depend>atlas</build_depend> <build_depend>gfortran</build_depend> <build_depend>suitesparse</build_depend> + <depend>abseil_cpp</depend> <depend>eigen</depend> <export>