C++ library for IRLBA

Overview

This repository contains a header-only C++ library implementing the Augmented Implicitly Restarted Lanczos Bidiagonalization Algorithm (IRLBA) from Baglama and Lothar (2005). IRLBA is a fast and memory-efficient method for truncated singular value decomposition, and is particularly useful for approximate principal components analysis of large matrices. The code here is derived from the C code in the irlba R package, refactored to use the Eigen library for matrix algebra.

Quick start

Using this library is as simple as including the header file in your source code:

#include "irlba/irlba.hpp"

irlba::Irlba runner;

// optional; specify the number of singular vectors, workspace, etc.
runner.set_number(5).set_work(20);

auto result = runner.run(mat, false, false, U, V, S);
result.U; // left singular vectors
result.V; // right singular vectors
result.S; // singular values

To perform a PCA:

auto res = runner.run(mat, true, false);
Eigen::MatrixXd components = res.U;
components *= res.S.asDiagonal();

See the reference documentation for more details.

Building projects

CMake with `FetchContent`

If you're using CMake, you just need to add something like this to your CMakeLists.txt:

include(FetchContent)

FetchContent_Declare(
  irlba 
  GIT_REPOSITORY https://github.com/LTLA/CppIrlba
  GIT_TAG master # or any version of interest
)

FetchContent_MakeAvailable(irlba)

Then you can link to irlba to make the headers available during compilation:

# For executables:
target_link_libraries(myexe ltla::irlba)

# For libaries
target_link_libraries(mylib INTERFACE ltla::irlba)

CMake with `find_package()`

find_package(ltla_irlba CONFIG REQUIRED)
target_link_libraries(mylib INTERFACE ltla::irlba)

To install the library use:

mkdir build && cd build
cmake .. -DIRLBA_TESTS=OFF
cmake --build . --target install

By default, this will use FetchContent to fetch all external dependencies. If you want to install them manually, use -DPOWERIT_FETCH_EXTERN=OFF. See the commit hashes in extern/CMakeLists.txt to find compatible versions of each dependency.

Manual

If you're not using CMake, the simple approach is to just copy the files - either directly or with Git submodules - and include their path during compilation with, e.g., GCC's -I. Note that this requires manual management of a few dependencies:

Eigen, for matrix manipulations.
aarand, for system-agnostic random distribution functions.

See extern/CMakeLists.txt for more details.

References

Baglama, James, and Lothar Reichel (2005). Augmented implicitly restarted Lanczos bidiagonalization methods. SIAM J. Sci. Comput., 27(1), 19-42.

moritz-h/CppIrlba