umappp 0.1.2

data/vendor/irlba/lanczos.hpp

@@ -0,0 +1,212 @@
+#ifndef IRLBA_LANCZOS_HPP
+#define IRLBA_LANCZOS_HPP
+
+#include "Eigen/Dense"
+#include "utils.hpp"
+#include "wrappers.hpp"
+#include <cmath>
+#include <limits>
+
+/**
+ * @file lanczos.hpp
+ *
+ * @brief Perform the Lanczos bidiagonalization iterations.
+ */
+
+namespace irlba {
+
+/**
+ * @brief Perform Lanczos bidiagonalization on an input matrix.
+ */
+class LanczosBidiagonalization {
+public:
+    struct Defaults {
+        /**
+         * See `set_epsilon()` for details.
+         */
+        static constexpr double epsilon = -1;
+    };
+public:
+    /**
+     * Set the tolerance to use to define invariant subspaces.
+     * This is used as the lower bound for the L2 norm for the subspace vectors;
+     * below this bound, vectors are treated as all-zero and are instead filled with random draws from a normal distribution.
+     *
+     * @param e A positive number defining the tolerance.
+     * If negative, we instead use the machine epsilon to the power of 0.8 (the same value as the **irlba** R package).
+     *
+     * @return A reference to the `LanczosBidiagonalization` instance.
+     */
+    LanczosBidiagonalization& set_epsilon(double e = Defaults::epsilon) {
+        epsilon = e;
+        return *this;
+    }
+
+public:
+    /**
+     * @brief Intermediate data structures to avoid repeated allocations.
+     */
+    struct Intermediates {
+        /**
+         * @tparam M Matrix class, most typically from the **Eigen** library.
+         *
+         * @param mat Instance of a matrix class `M`.
+         */
+        template<class M>
+        Intermediates(const M& mat) : F(mat.cols()), W_next(mat.rows()), orthog_tmp(mat.cols()) {}
+
+        /**
+         * Obtain the residual vector, see algorithm 2.1 of Baglama and Reichel (2005).
+         *
+         * @return Vector of residuals of length equal to the number of columns of `mat` in `run()`.
+         */
+        const Eigen::VectorXd& residuals() const {
+            return F;
+        }
+
+        /**
+         * @cond
+         */
+        Eigen::VectorXd F; 
+        Eigen::VectorXd W_next;
+        Eigen::VectorXd orthog_tmp;
+        /**
+         * @endcond
+         */
+    };
+
+    template<class M>
+    Intermediates initialize(const M& mat) const {
+        return Intermediates(mat);
+    }
+
+public:
+    /**
+     * Perform the Lanczos bidiagonalization on an input matrix, optionally with scaling and centering.
+     * This implements Algorithm 2.1 described by Baglama and Reichel (2005).
+     * Support is provided for centering and scaling without modifying `mat`.
+     * Protection against invariant subspaces is also implemented.
+     *
+     * @tparam M Matrix class, most typically from the **Eigen** library.
+     * See the `Irlba` documentation for a detailed description of the expected methods.
+     * @tparam Engine A functor that, when called with no arguments, returns a random integer from a discrete uniform distribution.
+     *
+     * @param mat Input matrix.
+     * @param W Output matrix with number of rows equal to `mat.rows()`.
+     * The size of the working subspace is defined from the number of columns.
+     * The first `start` columns should contain orthonormal column vectors with non-zero L2 norms.
+     * @param V Matrix with number of rows equal to `mat.cols()` and number of columns equal to `W.cols()`.
+     * The first `start + 1` columns should contain orthonormal column vectors with non-zero L2 norms.
+     * @param B Square matrix with number of rows and columns equal to the size of the working subspace.
+     * Number of values is defined by `set_number()`.
+     * @param eng An instance of a random number `Engine`.
+     * @param inter Collection of intermediate data structures generated by calling `initialize()` on `mat`.
+     * @param start The dimension from which to start the bidiagonalization.
+     *
+     * @return
+     * `W` is filled with orthonormal vectors, as is `V`.
+     * `B` is filled with upper diagonal entries.
+     */
+    template<class M, class Engine>
+    void run(
+        const M& mat, 
+        Eigen::MatrixXd& W, 
+        Eigen::MatrixXd& V, 
+        Eigen::MatrixXd& B, 
+        Engine& eng, 
+        Intermediates& inter, 
+        int start = 0) 
+    const {
+        const double eps = (epsilon < 0 ? std::pow(std::numeric_limits<double>::epsilon(), 0.8) : epsilon);
+
+        int work = W.cols();
+        auto& F = inter.F;
+        auto& W_next = inter.W_next;
+        auto& otmp = inter.orthog_tmp;
+
+        F = V.col(start);
+        if constexpr(has_multiply_method<M>::value) {
+            W_next.noalias() = mat * F;
+        } else {
+            mat.multiply(F, W_next);
+        }
+
+        // If start = 0, we assume that it's already normalized, see argument description for 'V'.
+        if (start) {
+            orthogonalize_vector(W, W_next, start, otmp);
+        }
+
+        double S = W_next.norm();
+        if (S < eps) {
+            throw -4;
+        }
+        W_next /= S;
+        W.col(start) = W_next;
+
+        // The Lanczos iterations themselves.
+        for (int j = start; j < work; ++j) {
+            if constexpr(has_adjoint_multiply_method<M>::value) {
+                F.noalias() = mat.adjoint() * W.col(j);
+            } else {
+                mat.adjoint_multiply(W.col(j), F);
+            }
+
+            F -= S * V.col(j); // equivalent to daxpy.
+            orthogonalize_vector(V, F, j + 1, otmp);
+
+            if (j + 1 < work) {
+                double R_F = F.norm();
+
+                if (R_F < eps) {
+                    fill_with_random_normals(F, eng);
+                    orthogonalize_vector(V, F, j + 1, otmp);
+                    R_F = F.norm();
+                    F /= R_F;
+                    R_F = 0;
+                } else {
+                    F /= R_F;
+                }
+
+                V.col(j + 1) = F;
+
+                B(j, j) = S;
+                B(j, j + 1) = R_F;
+
+                if constexpr(has_multiply_method<M>::value) {
+                    W_next.noalias() = mat * F;
+                } else {
+                    mat.multiply(F, W_next);
+                }
+
+                // Full re-orthogonalization, using the left-most 'j +  1' columns of W.
+                // Recall that W_next will be the 'j + 2'-th column, i.e., W.col(j + 1) in
+                // 0-indexed terms, so we want to orthogonalize to all previous columns.
+                orthogonalize_vector(W, W_next, j + 1, otmp);
+
+                S = W_next.norm();
+                if (S < eps) {
+                    fill_with_random_normals(W_next, eng);
+                    orthogonalize_vector(W, W_next, j + 1, otmp);
+                    S = W_next.norm();
+                    W_next /= S;
+                    S = 0;
+                } else {
+                    W_next /= S;
+                }
+
+                W.col(j + 1) = W_next;
+            } else {
+                B(j, j) = S;
+            }
+        }
+
+        return;
+    }
+
+private:
+    double epsilon = Defaults::epsilon;
+};
+
+}
+
+#endif

data/vendor/irlba/parallel.hpp

@@ -0,0 +1,474 @@
+#ifndef IRLBA_PARALLEL_HPP
+#define IRLBA_PARALLEL_HPP
+
+#include "utils.hpp"
+#include <vector>
+#include "Eigen/Dense"
+
+/**
+ * @file parallel.hpp
+ *
+ * @brief Sparse matrix class with parallelized multiplication.
+ */
+
+namespace irlba {
+
+/**
+ * @brief Sparse matrix with customizable parallelization.
+ *
+ * This provides an alternative to `Eigen::SparseMatrix` for parallelized multiplication of compressed sparse matrices.
+ * Unlike Eigen, this implementation is able to parallelize when the multiplication does not align well with the storage layout,
+ * e.g., multiplication of a compressed sparse column matrix by a dense vector on the right hand side.
+ * On construction, it also pre-allocates the rows and/or columns to each thread, aiming to balance the number of non-zero elements that each thread needs to process.
+ * All subsequent multiplications can then use these allocations, which is useful for cases like `Irlba` where the cost of pre-allocation is abrogated by repeated multiplication calls.
+ *
+ * Some cursory testing indicates that the performance of this implementation is comparable to Eigen for OpenMP-based parallelization.
+ * However, the real purpose of this class is to support custom parallelization schemes in cases where OpenMP is not available.
+ * This is achieved by defining `IRLBA_CUSTOM_PARALLEL` macro to the name of a function implementing a custom scheme.
+ * Such a function should accept two arguments - an integer specifying the number of threads, and a lambda that accepts a thread number.
+ * It should then loop over the number of threads and launch one job for each thread via the lambda.
+ * Once all threads are complete, the function should return.
+ *
+ * @tparam column_major Whether the matrix should be in compressed sparse column format.
+ * If `false`, this is assumed to be in row-major format.
+ * @tparam ValueArray Array class containing numeric values for the non-zero values.
+ * Should support a read-only `[]` operator.
+ * @tparam IndexArray Array class containing integer values for the indices of the non-zero values.
+ * Should support a read-only `[]` operator.
+ * @tparam PointerArray Array class containing integer values for the pointers to the row/column boundaries.
+ * Should support a read-only `[]` operator.
+ */
+template<
+    bool column_major = true, 
+    class ValueArray = std::vector<double>, 
+    class IndexArray = std::vector<int>, 
+    class PointerArray = std::vector<size_t> 
+>
+class ParallelSparseMatrix {
+public:
+    /**
+     * Default constructor.
+     * This object cannot be used for any operations.
+     */
+    ParallelSparseMatrix() {}
+
+    /**
+     * @param nr Number of rows.
+     * @param nc Number of columns.
+     * @param x Values of non-zero elements.
+     * @param i Indices of non-zero elements.
+     * Each entry corresponds to a value in `x`, so `i` should be an array of length equal to `x`.
+     * If `column_major = true`, `i` should contain row indices; otherwise it should contain column indices.
+     * @param p Pointers to the start of each column (if `column_major = true`) or row (otherwise).
+     * This should be an ordered array of length equal to the number of columns or rows plus 1.
+     * @param nt Number of threads to be used for multiplication.
+     *
+     * `x`, `i` and `p` represent the typical components of a compressed sparse column/row matrix.
+     * Thus, entries in `i` should be sorted within each column/row, where the boundaries between columns/rows are defined by `p`.
+     */
+    ParallelSparseMatrix(size_t nr, size_t nc, std::vector<double> x, std::vector<int> i, std::vector<size_t> p, int nt) : 
+        primary_dim(column_major ? nc : nr), 
+        secondary_dim(column_major ? nr : nc), 
+        nthreads(nt), 
+        values(std::move(x)), 
+        indices(std::move(i)), 
+        ptrs(std::move(p)) 
+    {
+        if (nthreads > 1) {
+            fragment_threads();
+        }
+    }
+
+    /**
+     * @return Number of rows in the matrix.
+     */
+    auto rows() const { 
+        if constexpr(column_major) {
+            return secondary_dim;
+        } else {
+            return primary_dim;
+        }
+    }
+
+    /**
+     * @return Number of columns in the matrix.
+     */
+    auto cols() const { 
+        if constexpr(column_major) {
+            return primary_dim;
+        } else {
+            return secondary_dim;
+        }
+    }
+
+    /**
+     * @return Non-zero elements in compressed sparse row/column format.
+     * This is equivalent to `x` in the constructor.
+     */
+    const ValueArray& get_values() const {
+        return values;
+    }
+
+    /**
+     * @return Indices of non-zero elements, equivalent to `i` in the constructor.
+     * These are row or column indices for compressed sparse row or column format, respectively, depending on `column_major`.
+     */
+    const IndexArray& get_indices() const {
+        return indices;
+    }
+
+    /**
+     * @return Pointers to the start of each row or column, equivalent to `p` in the constructor.
+     */
+    const PointerArray& get_pointers() const {
+        return ptrs;
+    }
+
+private:
+    size_t primary_dim, secondary_dim;
+    int nthreads;
+    ValueArray values;
+    IndexArray indices;
+    PointerArray ptrs;
+
+    typedef typename std::remove_const<typename std::remove_reference<decltype(indices[0])>::type>::type IndexType;
+
+public:
+    /**
+     * This should only be called if `nt > 1` in the constructor, otherwise it will not be initialized.
+     *
+     * @return Vector of length equal to the number of threads,
+     * specifying the first dimension along the primary extent (e.g., column for `column_major = true`) that each thread works on.
+     */
+    const std::vector<size_t>& get_primary_starts() const {
+        return primary_starts;
+    }
+
+    /**
+     * This should only be called if `nt > 1` in the constructor, otherwise it will not be initialized.
+     *
+     * @return Vector of length equal to the number of threads,
+     * specifying the one-past-the-last dimension along the primary extent (e.g., column for `column_major = true`) that each thread works on.
+     */
+    const std::vector<size_t>& get_primary_ends() const {
+        return primary_ends;
+    }
+
+    /**
+     * Type of the elements inside a `PointerArray`.
+     */
+    typedef typename std::remove_const<typename std::remove_reference<decltype(ptrs[0])>::type>::type PointerType;
+
+    /**
+     * This should only be called if `nt > 1` in the constructor, otherwise it will not be initialized.
+     *
+     * @return Vector of length equal to the number of threads plus one.
+     * Each inner vector is of length equal to the size of the primary extent (e.g., number of columns for `column_major = true`).
+     * For thread `i`, the vectors `i` and `i + 1` define the ranges of non-zero elements assigned to that thread within each primary dimension.
+     * This is guaranteed to contain all and only non-zero elements with indices in a contiguous range of secondary dimensions.
+     */
+    const std::vector<std::vector<PointerType> >& get_secondary_nonzero_starts() const {
+        return secondary_nonzero_starts;
+    }
+
+private:
+    std::vector<size_t> primary_starts, primary_ends;
+    std::vector<std::vector<PointerType> > secondary_nonzero_starts;
+
+    void fragment_threads() {
+        auto total_nzeros = ptrs[primary_dim]; // last element - not using back() to avoid an extra requirement on PointerArray.
+        PointerType per_thread = std::ceil(static_cast<double>(total_nzeros) / nthreads);
+        
+        // Splitting columns across threads so each thread processes the same number of nonzero elements.
+        primary_starts.resize(nthreads);
+        primary_ends.resize(nthreads);
+        {
+            size_t primary_counter = 0;
+            PointerType sofar = per_thread;
+            for (int t = 0; t < nthreads; ++t) {
+                primary_starts[t] = primary_counter;
+                while (primary_counter < primary_dim && ptrs[primary_counter + 1] <= sofar) {
+                    ++primary_counter;
+                }
+                primary_ends[t] = primary_counter;
+                sofar += per_thread;
+            }
+        }
+
+        // Splitting rows across threads so each thread processes the same number of nonzero elements.
+        secondary_nonzero_starts.resize(nthreads + 1, std::vector<PointerType>(primary_dim));
+        {
+            std::vector<PointerType> secondary_nonzeros(secondary_dim);
+            for (PointerType i = 0; i < total_nzeros; ++i) { // don't using range for loop to avoid an extra requirement on IndexArray.
+                ++(secondary_nonzeros[indices[i]]);
+            }
+            
+            std::vector<IndexType> secondary_ends(nthreads);
+            IndexType secondary_counter = 0;
+            PointerType sofar = per_thread;
+            PointerType cum_rows = 0;
+
+            for (int t = 0; t < nthreads; ++t) {
+                while (secondary_counter < secondary_dim && cum_rows <= sofar) {
+                    cum_rows += secondary_nonzeros[secondary_counter];
+                    ++secondary_counter;
+                }
+                secondary_ends[t] = secondary_counter;
+                sofar += per_thread;
+            }
+
+            for (size_t c = 0; c < primary_dim; ++c) {
+                auto primary_start = ptrs[c], primary_end = ptrs[c + 1];
+                secondary_nonzero_starts[0][c] = primary_start;
+
+                auto s = primary_start;
+                for (int thread = 0; thread < nthreads; ++thread) {
+                    while (s < primary_end && indices[s] < secondary_ends[thread]) { 
+                        ++s; 
+                    }
+                    secondary_nonzero_starts[thread + 1][c] = s;
+                }
+            }
+        }
+    }
+
+private:
+    template<class Right>
+    void indirect_multiply(const Right& rhs, Eigen::VectorXd& output) const {
+        if constexpr(has_data_method<Right>::value) {
+            // If it has a .data() method, the data values are already computed
+            // and sitting in memory, so we just use that directly.
+            indirect_multiply_internal(rhs, output);
+        } else {
+            // Otherwise, it is presumably an expression that involves some work
+            // to get the values. We realize it into a VectorXd to ensure that 
+            // it is not repeatedly evaluated on each access to 'rhs'.
+            indirect_multiply_internal(Eigen::VectorXd(rhs), output);
+        }
+    }
+
+    template<class Right>
+    void indirect_multiply_internal(const Right& rhs, Eigen::VectorXd& output) const {
+        output.setZero();
+
+        if (nthreads == 1) {
+            for (size_t c = 0; c < primary_dim; ++c) {
+                auto start = ptrs[c];
+                auto end = ptrs[c + 1];
+                auto val = rhs.coeff(c);
+                for (PointerType s = start; s < end; ++s) {
+                    output.coeffRef(indices[s]) += values[s] * val;
+                }
+            }
+            return;
+        }
+
+#ifndef IRLBA_CUSTOM_PARALLEL
+        #pragma omp parallel for num_threads(nthreads)
+        for (int t = 0; t < nthreads; ++t) {
+#else
+        IRLBA_CUSTOM_PARALLEL(nthreads, [&](int t) -> void {
+#endif
+
+            auto starts = secondary_nonzero_starts[t];
+            auto ends = secondary_nonzero_starts[t + 1];
+            for (size_t c = 0; c < primary_dim; ++c) {
+                auto start = starts[c];
+                auto end = ends[c];
+                auto val = rhs.coeff(c);
+                for (PointerType s = start; s < end; ++s) {
+                    output.coeffRef(indices[s]) += values[s] * val;
+                }
+            }
+
+#ifndef IRLBA_CUSTOM_PARALLEL
+        }
+#else
+        });
+#endif
+
+        return;
+    }
+
+private:
+    template<class Right>
+    void direct_multiply(const Right& rhs, Eigen::VectorXd& output) const {
+        if constexpr(has_data_method<Right>::value) {
+            // If it has a .data() method, the data values are already computed
+            // and sitting in memory, so we just use that directly.
+            direct_multiply_internal(rhs, output);
+        } else {
+            // Otherwise, it is presumably an expression that involves some work
+            // to get the values. We realize it into a VectorXd to ensure that 
+            // it is not repeatedly evaluated on each access to 'rhs'.
+            direct_multiply_internal(Eigen::VectorXd(rhs), output);
+        }
+    }
+
+    template<class Right>
+    void direct_multiply_internal(const Right& rhs, Eigen::VectorXd& output) const {
+        if (nthreads == 1) {
+            for (size_t c = 0; c < primary_dim; ++c) {
+                output.coeffRef(c) = column_dot_product(c, rhs);
+            }
+            return;
+        }
+
+#ifndef IRLBA_CUSTOM_PARALLEL
+        #pragma omp parallel for num_threads(nthreads)
+        for (int t = 0; t < nthreads; ++t) {
+#else
+        IRLBA_CUSTOM_PARALLEL(nthreads, [&](int t) -> void {
+#endif
+
+            auto curstart = primary_starts[t];
+            auto curend = primary_ends[t];
+            for (size_t c = curstart; c < curend; ++c) {
+                output.coeffRef(c) = column_dot_product(c, rhs);
+            }
+
+#ifndef IRLBA_CUSTOM_PARALLEL
+        }
+#else
+        });
+#endif
+
+        return;
+    }
+
+    template<class Right>
+    double column_dot_product(size_t c, const Right& rhs) const {
+        PointerType primary_start = ptrs[c], primary_end = ptrs[c + 1];
+        double dot = 0;
+        for (PointerType s = primary_start; s < primary_end; ++s) {
+            dot += values[s] * rhs.coeff(indices[s]);
+        }
+        return dot;
+    }
+
+public:
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of this matrix and `rhs`.
+     */
+    template<class Right>
+    void multiply(const Right& rhs, Eigen::VectorXd& output) const {
+        if constexpr(column_major) {
+            indirect_multiply(rhs, output);
+        } else {
+            direct_multiply(rhs, output);
+        }
+    }
+
+    /**
+     * @tparam Right An `Eigen::VectorXd` or equivalent expression.
+     *
+     * @param[in] rhs The right-hand side of the matrix product.
+     * This should be a vector or have only one column.
+     * @param[out] out The output vector to store the matrix product.
+     * 
+     * @return `out` is filled with the product of the transpose of this matrix and `rhs`.
+     */
+    template<class Right>
+    void adjoint_multiply(const Right& rhs, Eigen::VectorXd& output) const {
+        if constexpr(column_major) {
+            direct_multiply(rhs, output);
+        } else {
+            indirect_multiply(rhs, output);
+        }
+    }
+
+public:
+    /**
+     * @return A dense copy of the sparse matrix data.
+     */
+    Eigen::MatrixXd realize() const {
+        Eigen::MatrixXd output(rows(), cols());
+        output.setZero();
+
+        if constexpr(column_major) {
+            for (size_t c = 0; c < cols(); ++c) {
+                size_t col_start = ptrs[c], col_end = ptrs[c + 1];
+                for (size_t s = col_start; s < col_end; ++s) {
+                    output.coeffRef(indices[s], c) = values[s];
+                }
+            }
+        } else {
+            for (size_t r = 0; r < rows(); ++r) {
+                size_t row_start = ptrs[r], row_end = ptrs[r + 1];
+                for (size_t s = row_start; s < row_end; ++s) {
+                    output.coeffRef(r, indices[s]) = values[s];
+                }
+            }
+        }
+
+        return output;
+    }
+};
+
+/**
+ * @brief Restrict the number of available threads for Eigen.
+ *
+ * @details
+ * Creating an instance of this class will call `Eigen::setNbThreads()` to control the number of available OpenMP threads in Eigen operations.
+ * Destruction will then reset the number of available threads to its prior value.
+ *
+ * If OpenMP is available and `IRLBA_CUSTOM_PARALLEL`, Eigen is restricted to just one thread when an instance of this class is created.
+ * This is done to avoid using OpenMP when a custom parallelization scheme has already been specified.
+ *
+ * If OpenMP is not available, this class has no effect.
+ */ 
+class EigenThreadScope {
+public:
+#ifdef _OPENMP
+    /**
+     * @cond
+     */
+    EigenThreadScope(int n) : previous(Eigen::nbThreads()) {
+#ifndef IRLBA_CUSTOM_PARALLEL
+        Eigen::setNbThreads(n);
+#else
+        Eigen::setNbThreads(1);
+#endif
+    }
+    /**
+     * @endcond
+     */
+#else
+    /**
+     * @param n Number of threads to be used by Eigen.
+     */
+    EigenThreadScope(int n) {}
+#endif
+
+    /**
+     * @cond
+     */
+    EigenThreadScope(const EigenThreadScope&) = delete;
+    EigenThreadScope(EigenThreadScope&&) = delete;
+    EigenThreadScope& operator=(const EigenThreadScope&) = delete;
+    EigenThreadScope& operator=(EigenThreadScope&&) = delete;
+
+    ~EigenThreadScope() { 
+#ifdef _OPENMP
+        Eigen::setNbThreads(previous);
+#endif
+    }
+    /**
+     * @endcond
+     */
+private:
+    int previous;
+};
+
+
+
+
+}
+
+#endif