Bindings for Eigen's decompositions, matrix solvers, and geometry module, and add stubs

.gersemirc

@@ -1,4 +1,4 @@
-definitions: [./CMakeLists.txt, ./cmake]
+definitions: [./CMakeLists.txt, ./cmake, ./tests]
 line_length: 80
 indent: 2
 warn_about_unknown_commands: false

.git-blame-ignore-revs

@@ -0,0 +1,2 @@
+# pre-commit run -a (format-all, 2025-03-19)
+98c85ab243b68db680a0a5f1ccbf238aeb6523ba

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ ci:
   submodules: true
 repos:
   - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v19.1.7
+    rev: v20.1.0
     hooks:
     - id: clang-format
       types_or: []
@@ -28,7 +28,7 @@ repos:
                 doc/doxygen-awesome.*
             )$
   - repo: https://github.com/BlankSpruce/gersemi
-    rev: 0.19.0
+    rev: 0.19.2
     hooks:
       - id: gersemi
   - repo: https://github.com/Lucas-C/pre-commit-hooks

CMakeLists.txt

@@ -1,25 +1,29 @@
+#
+# Copyright 2025 INRIA
+#
+
 cmake_minimum_required(VERSION 3.18)
 
 set(PROJECT_NAME nanoeigenpy)
-set(PROJECT_URL https://github.com/ManifoldFR/nanoeigenpy)
+set(PROJECT_URL https://github.com/Simple-Robotics/nanoeigenpy)
 set(PROJECT_DESCRIPTION "Tools for using Eigen with nanobind")
 set(PROJECT_CUSTOM_HEADER_EXTENSION "hpp")
 set(PROJECT_USE_CMAKE_EXPORT True)
 
+if(POLICY CMP0167)
+  cmake_policy(SET CMP0167 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0167 NEW)
+endif()
+if(POLICY CMP0177)
+  cmake_policy(SET CMP0177 NEW)
+  set(CMAKE_POLICY_DEFAULT_CMP0177 NEW)
+endif()
 include(cmake/base.cmake)
+include(cmake/ide.cmake)
 
 COMPUTE_PROJECT_ARGS(PROJECT_ARGS LANGUAGES CXX)
 project(${PROJECT_NAME} ${PROJECT_ARGS})
 
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/lib)
-
-find_package(Eigen3 REQUIRED)
-
-add_library(nanoeigenpy_headers INTERFACE)
-target_link_libraries(nanoeigenpy_headers INTERFACE Eigen3::Eigen)
-
-find_package(Python REQUIRED COMPONENTS Interpreter Development)
-
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
   set_property(
@@ -28,6 +32,11 @@ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
   )
 endif()
 
+# Find dependencies
+ADD_PROJECT_DEPENDENCY(Eigen3 REQUIRED PKG_CONFIG_REQUIRES "eigen3 >= 3.3.1")
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development)
+
 # Detect the installed nanobind package and import it into CMake
 execute_process(
   COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
@@ -36,29 +45,47 @@ execute_process(
 )
 find_package(nanobind CONFIG REQUIRED)
 
-file(GLOB nanoeigenpy_SOURCES src/*.cpp)
-nanobind_add_module(nanoeigenpy NB_STATIC NB_SUPPRESS_WARNINGS ${nanoeigenpy_SOURCES})
+# Setup main targets
+file(GLOB_RECURSE ${PROJECT_NAME}_HEADERS include/nanoeigenpy/*.hpp)
+
+add_library(nanoeigenpy_headers INTERFACE)
+target_include_directories(
+  nanoeigenpy_headers
+  INTERFACE
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+)
+target_link_libraries(nanoeigenpy_headers INTERFACE Eigen3::Eigen)
+
+file(GLOB ${PROJECT_NAME}_SOURCES src/*.cpp)
+nanobind_add_module(nanoeigenpy NB_STATIC NB_SUPPRESS_WARNINGS ${nanoeigenpy_SOURCES} ${nanoeigenpy_HEADERS})
 target_link_libraries(nanoeigenpy PUBLIC nanoeigenpy_headers)
 
 if(BUILD_TESTING)
   add_subdirectory(tests)
 endif()
 
+# Install targets
 install(
-  TARGETS nanoeigenpy_headers
+  TARGETS ${PROJECT_NAME}_headers
   EXPORT ${TARGETS_EXPORT_NAME}
+  PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
   INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )
 
 install(
-  DIRECTORY include/nanoeigenpy
-  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
-  FILES_MATCHING
-  PATTERN "*.hpp"
-)
-
-install(
-  TARGETS nanoeigenpy
+  TARGETS ${PROJECT_NAME}
   EXPORT ${TARGETS_EXPORT_NAME}
-  LIBRARY DESTINATION ${Python_SITELIB}
+  PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )
+
+ADD_HEADER_GROUP(${PROJECT_NAME}_HEADERS)
+ADD_SOURCE_GROUP(${PROJECT_NAME}_SOURCES)

include/nanoeigenpy/computation-info.hpp

@@ -0,0 +1,22 @@
+/// Copyright 2025 INRIA
+#pragma once
+
+#include <nanobind/nanobind.h>
+#include <Eigen/Core>
+
+namespace nanoeigenpy {
+namespace nb = nanobind;
+inline void exposeComputationInfo(nb::module_ m) {
+  nb::enum_<Eigen::ComputationInfo>(m, "ComputationInfo")
+      .value("Success", Eigen::Success, "Computation was successful.")
+      .value("NumericalIssue", Eigen::NumericalIssue,
+             "The provided data did not satisfy the prerequisites.")
+      .value("NoConvergence", Eigen::NoConvergence,
+             "Iterative procedure did not converge.")
+      .value("InvalidInput", Eigen::InvalidInput,
+             "The inputs are invalid, or the algorithm has been improperly "
+             "called. "
+             "When assertions are enabled, such errors trigger an assert.")
+      .export_values();
+}
+}  // namespace nanoeigenpy

include/nanoeigenpy/decompositions.hpp

@@ -1,4 +1,14 @@
+/// Copyright 2025 INRIA
 #pragma once
 
-#include "nanoeigenpy/decompositions/ldlt.hpp"
 #include "nanoeigenpy/decompositions/llt.hpp"
+#include "nanoeigenpy/decompositions/ldlt.hpp"
+#include "nanoeigenpy/decompositions/minres.hpp"
+#include "nanoeigenpy/decompositions/HouseholderQR.hpp"
+#include "nanoeigenpy/decompositions/FullPivHouseholderQR.hpp"
+#include "nanoeigenpy/decompositions/ColPivHouseholderQR.hpp"
+#include "nanoeigenpy/decompositions/CompleteOrthogonalDecomposition.hpp"
+#include "nanoeigenpy/decompositions/EigenSolver.hpp"
+
+#include "nanoeigenpy/decompositions/sparse/llt.hpp"
+#include "nanoeigenpy/decompositions/sparse/ldlt.hpp"

include/nanoeigenpy/decompositions/ColPivHouseholderQR.hpp

@@ -0,0 +1,199 @@
+/// Copyright 2025 INRIA
+#pragma once
+#include "base.hpp"
+#include <Eigen/QR>
+
+namespace nanoeigenpy {
+namespace nb = nanobind;
+
+template <typename MatrixType, typename MatrixOrVector>
+MatrixOrVector solve(const Eigen::ColPivHouseholderQR<MatrixType> &c,
+                     const MatrixOrVector &vec) {
+  return c.solve(vec);
+}
+
+template <typename MatrixType>
+MatrixType inverse(const Eigen::ColPivHouseholderQR<MatrixType> &c) {
+  return c.inverse();
+}
+
+template <typename MatrixType>
+void exposeColPivHouseholderQRSolver(nb::module_ m, const char *name) {
+  using Solver = Eigen::ColPivHouseholderQR<MatrixType>;
+  using Scalar = typename MatrixType::Scalar;
+  using RealScalar = typename MatrixType::RealScalar;
+  using VectorType = Eigen::Matrix<Scalar, -1, 1>;
+  auto cl =
+      nb::class_<Solver>(
+          m, name,
+          "This class performs a rank-revealing QR decomposition of a matrix A "
+          "into matrices P, Q and R such that:\n"
+          "AP=QR\n"
+          "by using Householder transformations. Here, P is a permutation "
+          "matrix, Q a unitary matrix and R an upper triangular matrix.\n"
+          "\n"
+          "This decomposition performs column pivoting in order to be "
+          "rank-revealing and improve numerical stability. It is slower than "
+          "HouseholderQR, and faster than FullPivHouseholderQR.")
+
+          .def(nb::init<>(),
+               "Default constructor.\n"
+               "The default constructor is useful in cases in which the "
+               "user intends to perform decompositions via "
+               "HouseholderQR.compute(matrix).")
+          .def(nb::init<Eigen::DenseIndex, Eigen::DenseIndex>(),
+               nb::arg("rows"), nb::arg("cols"),
+               "Default constructor with memory preallocation.\n"
+               "Like the default constructor but with preallocation of the "
+               "internal data according to the specified problem size. ")
+          .def(nb::init<const MatrixType &>(), nb::arg("matrix"),
+               "Constructs a QR factorization from a given matrix.\n"
+               "This constructor computes the QR factorization of the matrix "
+               "matrix by calling the method compute().")
+
+          .def("info", &Solver::info,
+               "Reports whether the QR factorization was successful.\n"
+               "Note: This function always returns Success. It is provided for "
+               "compatibility with other factorization routines.")
+
+          .def("absDeterminant", &Solver::absDeterminant,
+               "Returns the absolute value of the determinant of the matrix of "
+               "which *this is the QR decomposition.\n"
+               "It has only linear complexity (that is, O(n) where n is the "
+               "dimension of the square matrix) as the QR decomposition has "
+               "already been computed.\n"
+               "Note: This is only for square matrices.")
+          .def("logAbsDeterminant", &Solver::logAbsDeterminant,
+               "Returns the natural log of the absolute value of the "
+               "determinant "
+               "of the matrix of which *this is the QR decomposition.\n"
+               "It has only linear complexity (that is, O(n) where n is the "
+               "dimension of the square matrix) as the QR decomposition has "
+               "already been computed.\n"
+               "Note: This is only for square matrices. This method is useful "
+               "to "
+               "work around the risk of overflow/underflow that's inherent to "
+               "determinant computation.")
+          .def("dimensionOfKernel", &Solver::dimensionOfKernel,
+               "Returns the dimension of the kernel of the matrix of which "
+               "*this "
+               "is the QR decomposition.")
+          .def("isInjective", &Solver::isInjective,
+               "Returns true if the matrix associated with this QR "
+               "decomposition "
+               "represents an injective linear map, i.e. has trivial kernel; "
+               "false otherwise.\n"
+               "\n"
+               "Note: This method has to determine which pivots should be "
+               "considered nonzero. For that, it uses the threshold value that "
+               "you can control by calling setThreshold(threshold).")
+          .def(
+              "isInvertible", &Solver::isInvertible,
+              "Returns true if the matrix associated with the QR decomposition "
+              "is invertible.\n"
+              "\n"
+              "Note: This method has to determine which pivots should be "
+              "considered nonzero. For that, it uses the threshold value that "
+              "you can control by calling setThreshold(threshold).")
+          .def("isSurjective", &Solver::isSurjective,
+               "Returns true if the matrix associated with this QR "
+               "decomposition "
+               "represents a surjective linear map; false otherwise.\n"
+               "\n"
+               "Note: This method has to determine which pivots should be "
+               "considered nonzero. For that, it uses the threshold value that "
+               "you can control by calling setThreshold(threshold).")
+          .def("maxPivot", &Solver::maxPivot,
+               "Returns the absolute value of the biggest pivot, i.e. the "
+               "biggest diagonal coefficient of U.")
+          .def(
+              "nonzeroPivots", &Solver::nonzeroPivots,
+              "Returns the number of nonzero pivots in the QR decomposition. "
+              "Here nonzero is meant in the exact sense, not in a fuzzy sense. "
+              "So that notion isn't really intrinsically interesting, but it "
+              "is "
+              "still useful when implementing algorithms.")
+          .def("rank", &Solver::rank,
+               "Returns the rank of the matrix associated with the QR "
+               "decomposition.\n"
+               "\n"
+               "Note: This method has to determine which pivots should be "
+               "considered nonzero. For that, it uses the threshold value that "
+               "you can control by calling setThreshold(threshold).")
+
+          .def(
+              "setThreshold",
+              [](Solver &c, RealScalar const &threshold) {
+                return c.setThreshold(threshold);
+              },
+              nb::arg("threshold"),
+              "Allows to prescribe a threshold to be used by certain methods, "
+              "such as rank(), who need to determine when pivots are to be "
+              "considered nonzero. This is not used for the QR decomposition "
+              "itself.\n"
+              "\n"
+              "When it needs to get the threshold value, Eigen calls "
+              "threshold(). By default, this uses a formula to automatically "
+              "determine a reasonable threshold. Once you have called the "
+              "present method setThreshold(const RealScalar&), your value is "
+              "used instead.\n"
+              "\n"
+              "Note: A pivot will be considered nonzero if its absolute value "
+              "is strictly greater than |pivot| ⩽ threshold×|maxpivot| where "
+              "maxpivot is the biggest pivot.",
+              nb::rv_policy::reference)
+          .def(
+              "threshold", &Solver::threshold,
+              "Returns the threshold that will be used by certain methods such "
+              "as rank().")
+
+          .def("matrixQR", &Solver::matrixQR,
+               "Returns the matrix where the Householder QR decomposition is "
+               "stored in a LAPACK-compatible way.",
+               nb::rv_policy::copy)
+          .def("matrixR", &Solver::matrixR,
+               "Returns the matrix where the result Householder QR is stored.",
+               nb::rv_policy::copy)
+
+          .def(
+              "compute",
+              [](Solver &c, VectorType const &matrix) {
+                return c.compute(matrix);
+              },
+              nb::arg("matrix"),
+              "Computes the QR factorization of given matrix.",
+              nb::rv_policy::reference)
+
+          .def(
+              "inverse",
+              [](Solver const &c) -> MatrixType { return inverse(c); },
+              "Returns the inverse of the matrix associated with the QR "
+              "decomposition.")
+
+          .def(
+              "solve",
+              [](Solver const &c, VectorType const &b) -> VectorType {
+                return solve(c, b);
+              },
+              nb::arg("b"),
+              "Returns the solution x of A x = B using the current "
+              "decomposition of A where b is a right hand side vector.")
+          .def(
+              "solve",
+              [](Solver const &c, MatrixType const &B) -> MatrixType {
+                return solve(c, B);
+              },
+              nb::arg("B"),
+              "Returns the solution X of A X = B using the current "
+              "decomposition of A where B is a right hand side matrix.")
+
+          .def(
+              "id",
+              [](Solver const &c) -> int64_t {
+                return reinterpret_cast<int64_t>(&c);
+              },
+              "Returns the unique identity of an object.\n"
+              "For objects held in C++, it corresponds to its memory address.");
+}
+
+}  // namespace nanoeigenpy