umappp 0.1.2

data/vendor/knncolle/Kmknn/Kmknn.hpp

@@ -0,0 +1,286 @@
+#ifndef KNNCOLLE_KMKNN_HPP
+#define KNNCOLLE_KMKNN_HPP
+
+#include "../utils/distances.hpp"
+#include "../utils/NeighborQueue.hpp"
+#include "../utils/Base.hpp"
+#include "kmeans/Kmeans.hpp"
+
+#include <algorithm>
+#include <vector>
+#include <random>
+#include <limits>
+#include <cmath>
+
+#ifdef DEBUG
+#include <iostream>
+#endif
+
+/**
+ * @file Kmknn.hpp
+ *
+ * @brief Implements the k-means with k-nearest neighbors (KMKNN) algorithm.
+ */
+
+namespace knncolle {
+
+/**
+ * @brief Perform a nearest neighbor search based on k-means clustering.
+ *
+ * In the k-means with k-nearest neighbors (KMKNN) algorithm (Wang, 2012), k-means clustering is first applied to the data points,
+ * with the number of cluster centers defined as the square root of the number of points.
+ * The cluster assignment and distance to the assigned cluster center for each point represent the KMKNN indexing information, 
+ * allowing us to speed up the nearest neighbor search by exploiting the triangle inequality between cluster centers, the query point and each point in the cluster to narrow the search space.
+ * The advantage of the KMKNN approach is its simplicity and minimal overhead,
+ * resulting in performance improvements over conventional tree-based methods for high-dimensional data where most points need to be searched anyway.
+ *
+ * @tparam DISTANCE Class to compute the distance between vectors, see `distance::Euclidean` for an example.
+ * @tparam INDEX_t Integer type for the indices.
+ * @tparam DISTANCE_t Floating point type for the distances.
+ * @tparam QUERY_t Floating point type for the query data.
+ * @tparam INTERNAL_t Floating point type for the data.
+ *
+ * @see
+ * Wang X (2012). 
+ * A fast exact k-nearest neighbors algorithm for high dimensional search using k-means clustering and triangle inequality. 
+ * _Proc Int Jt Conf Neural Netw_, 43, 6:2351-2358.
+ */
+template<class DISTANCE, typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = DISTANCE_t>
+class Kmknn : public Base<INDEX_t, DISTANCE_t, QUERY_t> {
+private:
+    INDEX_t num_dim;
+    INDEX_t num_obs;
+
+public:
+    INDEX_t nobs() const { return num_obs; } 
+    
+    INDEX_t ndim() const { return num_dim; }
+
+private:
+    std::vector<INTERNAL_t> data;
+    
+    std::vector<INDEX_t> sizes;
+    std::vector<INDEX_t> offsets;
+
+    std::vector<INTERNAL_t> centers;
+
+    std::vector<INDEX_t> observation_id, new_location;
+    std::vector<DISTANCE_t> dist_to_centroid;
+
+public:
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param vals Pointer to an array of length `ndim * nobs`, corresponding to a dimension-by-observation matrix in column-major format, 
+     * i.e., contiguous elements belong to the same observation.
+     * @param power Power of `nobs` to define the number of cluster centers.
+     * By default, a square root is performed.
+     *
+     * @tparam INPUT_t Floating-point type of the input data.
+     */
+    template<typename INPUT_t>
+    Kmknn(INDEX_t ndim, INDEX_t nobs, const INPUT_t* vals, double power = 0.5) : 
+            num_dim(ndim), 
+            num_obs(nobs), 
+            data(ndim * nobs), 
+            sizes(std::ceil(std::pow(num_obs, power))), 
+            offsets(sizes.size()),
+            centers(sizes.size() * ndim),
+            observation_id(nobs),
+            new_location(nobs),
+            dist_to_centroid(nobs)
+    { 
+        std::vector<int> clusters(num_obs);
+        auto ncenters = sizes.size();
+
+        // Try to avoid a copy if we're dealing with the same type;
+        // otherwise, we just dump it into 'data', given that we 
+        // won't be rewriting it for a while anyway.
+        const INTERNAL_t* host;
+        if constexpr(std::is_same<INPUT_t, INTERNAL_t>::value) {
+            host = vals;
+        } else {
+            std::copy(vals, vals + data.size(), data.data());
+            host = data.data();
+        }
+        auto output = kmeans::Kmeans<INTERNAL_t, int>().run(ndim, nobs, host, ncenters, centers.data(), clusters.data());
+        std::swap(sizes, output.sizes);
+
+        // In case there were some duplicate points, we just resize this a bit.
+        if (ncenters != sizes.size()) {
+            ncenters = sizes.size();
+            offsets.resize(ncenters);
+            centers.resize(ncenters * ndim);
+        }
+
+        for (INDEX_t i = 1; i < ncenters; ++i) {
+            offsets[i] = offsets[i - 1] + sizes[i - 1];
+        }
+
+        // Organize points correctly; firstly, sorting by distance from the assigned center.
+        std::vector<std::pair<INTERNAL_t, INDEX_t> > by_distance(nobs);
+        {
+            auto sofar = offsets;
+            for (INDEX_t o = 0; o < nobs; ++o) {
+                const auto& clustid = clusters[o];
+                auto& counter = sofar[clustid];
+                auto& current = by_distance[counter];
+                current.first = DISTANCE::normalize(DISTANCE::template raw_distance<INTERNAL_t>(host + o * num_dim, centers.data() + clustid * num_dim, num_dim));
+                current.second = o;
+                ++counter;
+            }
+
+            for (INDEX_t c = 0; c < ncenters; ++c) {
+                auto begin = by_distance.begin() + offsets[c];
+                std::sort(begin, begin + sizes[c]);
+            }
+        }
+
+        // Now, copying this over. 
+        {
+            auto store = data.data();
+            for (INDEX_t o = 0; o < nobs; ++o, store += num_dim) {
+                const auto& current = by_distance[o];
+                auto source = vals + ndim * current.second; // must use 'vals' here, as 'host' might alias 'data'!
+                std::copy(source, source + ndim, store);
+                observation_id[o] = current.second;
+                new_location[current.second] = o;
+                dist_to_centroid[o] = current.first;
+            }
+        }
+
+        return;
+    }
+
+    std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(INDEX_t index, int k) const {
+        NeighborQueue<INDEX_t, INTERNAL_t> nearest(k, new_location[index]);
+        search_nn(data.data() + new_location[index] * num_dim, nearest);
+        return report(nearest);
+    }
+
+    std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(const QUERY_t* query, int k) const {
+        NeighborQueue<INDEX_t, INTERNAL_t> nearest(k);
+        search_nn(query, nearest);
+        return report(nearest);
+    }
+
+    const QUERY_t* observation(INDEX_t index, QUERY_t* buffer) const {
+        auto candidate = data.data() + num_dim * new_location[index];
+        if constexpr(std::is_same<QUERY_t, INTERNAL_t>::value) {
+            return candidate;
+        } else {
+            std::copy(candidate, candidate + num_dim, buffer);
+            return buffer;
+        }
+    }
+
+    using Base<INDEX_t, DISTANCE_t, QUERY_t>::observation;
+
+private:
+    template<typename INPUT_t>
+    void search_nn(INPUT_t* target, NeighborQueue<INDEX_t, INTERNAL_t>& nearest) const { 
+        /* Computing distances to all centers and sorting them. The aim is to
+         * go through the nearest centers first, to get the shortest
+         * 'threshold' possible through the rest of the search.
+         */
+        std::vector<std::pair<INTERNAL_t, INDEX_t> > center_order(sizes.size());
+        auto clust_ptr = centers.data();
+        for (size_t c = 0; c < sizes.size(); ++c, clust_ptr += num_dim) {
+            center_order[c].first = DISTANCE::template raw_distance<INTERNAL_t>(target, clust_ptr, num_dim);
+            center_order[c].second = c;
+        }
+        std::sort(center_order.begin(), center_order.end());
+        INTERNAL_t threshold_raw = -1;
+
+        // Computing the distance to each center, and deciding whether to proceed for each cluster.
+        for (const auto& curcent : center_order) {
+            const INDEX_t center = curcent.second;
+            const INTERNAL_t dist2center = DISTANCE::normalize(curcent.first);
+
+            const auto cur_nobs = sizes[center];
+            const DISTANCE_t* dIt = dist_to_centroid.data() + offsets[center];
+            const DISTANCE_t maxdist = *(dIt + cur_nobs - 1);
+
+            INDEX_t firstcell=0;
+#if USE_UPPER
+            INTERNAL_t upper_bd = std::numeric_limits<INTERNAL_t>::max();
+#endif
+            
+            if (threshold_raw >= 0) {
+                const INTERNAL_t threshold = DISTANCE::normalize(threshold_raw);
+
+                /* The conditional expression below exploits the triangle inequality; it is equivalent to asking whether:
+                 *     threshold + maxdist < dist2center
+                 * All points (if any) within this cluster with distances above 'lower_bd' are potentially countable.
+                 */
+                const DISTANCE_t lower_bd = dist2center - threshold;
+                if (maxdist < lower_bd) {
+                    continue;
+                }
+                firstcell=std::lower_bound(dIt, dIt + cur_nobs, lower_bd) - dIt;
+#if USE_UPPER
+                /* This exploits the reverse triangle inequality, to ignore points where:
+                 *     threshold + dist2center < point-to-center distance
+                 */
+                upper_bd = threshold + dist2center;
+#endif
+            }
+
+            const auto cur_start = offsets[center];
+            const INTERNAL_t * other_cell = data.data() + num_dim * (cur_start + firstcell);
+            for (auto celldex = firstcell; celldex < cur_nobs; ++celldex, other_cell += num_dim) {
+#if USE_UPPER
+                if (*(dIt + celldex) > upper_bd) {
+                    break;
+                }
+#endif
+                const auto dist2cell_raw = DISTANCE::template raw_distance<INTERNAL_t>(target, other_cell, num_dim);
+                nearest.add(cur_start + celldex, dist2cell_raw);
+                if (nearest.is_full()) {
+                    threshold_raw = nearest.limit(); // Shrinking the threshold, if an earlier NN has been found.
+#if USE_UPPER
+                    upper_bd = DISTANCE::normalize(threshold_raw) + dist2center; 
+#endif
+                }
+            }
+        }
+    }
+
+    template<class QUEUE>
+    auto report(QUEUE& nearest) const {
+        auto output = nearest.template report<DISTANCE_t>();
+        for (auto& s : output) {
+            s.first = observation_id[s.first];
+            s.second = DISTANCE::normalize(s.second);
+        }
+        return output;
+    }
+
+#ifdef DEBUG
+    template<class V>
+    void print_vector(const V& input, const char* msg) const {
+        std::cout << msg << ": ";
+        for (auto v : input) {
+            std::cout << v << " ";
+        }
+        std::cout << std::endl;
+    }
+#endif
+};
+
+/**
+ * Perform a KMKNN search with Euclidean distances.
+ */
+template<typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = DISTANCE_t>
+using KmknnEuclidean = Kmknn<distances::Euclidean, INDEX_t, DISTANCE_t, QUERY_t, INTERNAL_t>;
+
+/**
+ * Perform a KMKNN search with Manhattan distances.
+ * Note that k-means clustering may not provide a particularly good indexing structure for Manhattan distances, so your mileage may vary.
+ */
+template<typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = DISTANCE_t>
+using KmknnManhattan = Kmknn<distances::Manhattan, INDEX_t, DISTANCE_t, QUERY_t, INTERNAL_t>;
+
+};
+
+#endif

data/vendor/knncolle/VpTree/VpTree.hpp

@@ -0,0 +1,256 @@
+#ifndef KNNCOLLE_VPTREE_HPP
+#define KNNCOLLE_VPTREE_HPP
+
+#include "../utils/distances.hpp"
+#include "../utils/NeighborQueue.hpp"
+#include "../utils/Base.hpp"
+
+#include <vector>
+#include <random>
+#include <limits>
+#include <tuple>
+
+/**
+ * @file VpTree.hpp
+ *
+ * @brief Implements a vantage point (VP) tree to search for nearest neighbors.
+ */
+
+namespace knncolle {
+
+/**
+ * @brief Perform a nearest neighbor search based on a vantage point (VP) tree.
+ *
+ * In a vantage point tree (Yianilos, 1993), each node contains a subset of points that is split into two further partitions.
+ * The split is determined by picking an arbitrary point inside that subset as the node center, 
+ * computing the distance to all other points from the center, and using the median distance as the "radius" of a hypersphere.
+ * The left child of this node contains all points within that hypersphere while the right child contains the remaining points.
+ * This procedure is applied recursively until all points resolve to individual nodes, thus yielding a VP tree. 
+ * Upon searching, the algorithm traverses the tree and exploits the triangle inequality between query points and node centers to narrow the search space.
+ *
+ * The major advantage of VP trees over more conventional KD-trees or ball trees is that the former does not need to construct intermediate nodes, instead using the data points themselves at the nodes.
+ * This reduces the memory usage of the tree and total number of distance calculations for any search.
+ * It can also be very useful when the concept of an intermediate is not well-defined (e.g., for non-numeric data), though this is not particularly relevant for **knncolle**.
+ *
+ * @tparam DISTANCE Class to compute the distance between vectors, see `distance::Euclidean` for an example.
+ * @tparam INDEX_t Integer type for the indices.
+ * @tparam DISTANCE_t Floating point type for the distances.
+ * @tparam QUERY_t Floating point type for the query data.
+ * @tparam INTERNAL_t Floating point type for the internal data store.
+ *
+ * @see
+ * Yianilos PN (1993).
+ * Data structures and algorithms for nearest neighbor search in general metric spaces.
+ * _Proceedings of the Fourth Annual ACM-SIAM Symposium on Discrete Algorithms_, 311-321.
+ * 
+ * @see
+ * Hanov S (2011).
+ * VP trees: A data structure for finding stuff fast.
+ * http://stevehanov.ca/blog/index.php?id=130
+ */
+template<class DISTANCE, typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = DISTANCE_t>
+class VpTree : public Base<INDEX_t, DISTANCE_t, QUERY_t> {
+    /* Adapted from http://stevehanov.ca/blog/index.php?id=130 */
+
+private:
+    INDEX_t num_dim;
+    INDEX_t num_obs;
+public:
+    INDEX_t nobs() const { return num_obs; } 
+    
+    INDEX_t ndim() const { return num_dim; }
+private:
+    typedef int NodeIndex_t;
+    static const NodeIndex_t LEAF_MARKER=-1;
+
+    // Single node of a VP tree (has a point and radius; left children are closer to point than the radius)
+    struct Node {
+        INTERNAL_t threshold;  // radius 
+        INDEX_t index; // original index of current vantage point 
+        NodeIndex_t left;  // node index of the next vantage point for all children closer than 'threshold' from the current vantage point
+        NodeIndex_t right; // node index of the next vantage point for all children further than 'threshold' from the current vantage point
+        Node(NodeIndex_t i=0) : threshold(0), index(i), left(LEAF_MARKER), right(LEAF_MARKER) {}
+    };
+    std::vector<Node> nodes;
+
+    typedef std::tuple<INDEX_t, const INTERNAL_t*, INTERNAL_t> DataPoint; // internal distances computed using "INTERNAL_t" type, even if output is returned with DISTANCE_t.
+
+    template<class SAMPLER>
+    NodeIndex_t buildFromPoints(NodeIndex_t lower, NodeIndex_t upper, std::vector<DataPoint>& items, SAMPLER& rng) {
+        if (upper == lower) {     // indicates that we're done here!
+            return LEAF_MARKER;
+        }
+
+        NodeIndex_t pos = nodes.size();
+        nodes.resize(pos + 1);
+        Node& node=nodes.back();
+            
+        int gap = upper - lower;
+        if (gap > 1) {      // if we did not arrive at leaf yet
+
+            /* Choose an arbitrary point and move it to the start of the [lower, upper)
+             * interval in 'items'; this is our new vantage point.
+             * 
+             * Yes, I know that the modulo method does not provide strictly
+             * uniform values but statistical correctness doesn't really matter
+             * here... but reproducibility across platforms does matter, and
+             * std::uniform_int_distribution is implementation-dependent!
+             */
+            NodeIndex_t i = static_cast<NodeIndex_t>(rng() % gap + lower);
+            std::swap(items[lower], items[i]);
+            const auto& vantage = items[lower];
+
+            // Compute distances to the new vantage point.
+            const INTERNAL_t* ref = std::get<1>(vantage);
+            for (size_t i = lower + 1; i < upper; ++i) {
+                const INTERNAL_t* loc = std::get<1>(items[i]);
+                std::get<2>(items[i]) = DISTANCE::template raw_distance<INTERNAL_t>(ref, loc, num_dim);
+            }
+
+            // Partition around the median distance from the vantage point.
+            NodeIndex_t median = lower + gap/2;
+            std::nth_element(items.begin() + lower + 1, items.begin() + median, items.begin() + upper,
+                [&](const DataPoint& left, const DataPoint& right) -> bool {
+                    return std::get<2>(left) < std::get<2>(right);
+                }
+            );
+           
+            // Threshold of the new node will be the distance to the median
+            node.threshold = DISTANCE::normalize(std::get<2>(items[median]));
+
+            // Recursively build tree
+            node.index = std::get<0>(vantage);
+            node.left = buildFromPoints(lower + 1, median, items, rng);
+            node.right = buildFromPoints(median, upper, items, rng);
+        } else {
+            node.index = std::get<0>(items[lower]);
+        }
+        
+        return pos;
+    }
+
+private:
+    std::vector<INDEX_t> new_location;
+    std::vector<INTERNAL_t> store;
+
+public:
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param vals Pointer to an array of length `ndim * nobs`, corresponding to a dimension-by-observation matrix in column-major format, 
+     * i.e., contiguous elements belong to the same observation.
+     *
+     * @tparam INPUT_t Floating-point type of the input data.
+     */
+    template<typename INPUT_t>
+    VpTree(INDEX_t ndim, INDEX_t nobs, const INPUT_t* vals) : num_dim(ndim), num_obs(nobs), new_location(nobs), store(ndim * nobs) { 
+        std::vector<DataPoint> items;
+        items.reserve(num_obs);
+        for (INDEX_t i = 0; i < num_obs; ++i) {
+            items.push_back(DataPoint(i, vals + i * num_dim, 0));
+        }
+
+        nodes.reserve(num_obs);
+        std::mt19937_64 rand(1234567890); // seed doesn't really matter, we don't need statistical correctness here.
+        buildFromPoints(0, num_obs, items, rand);
+
+        // Actually populating the store based on the traversal order of the nodes.
+        // This should be more cache efficient than an arbitrary input order.
+        auto sIt = store.begin();
+        for (size_t i = 0; i < num_obs; ++i, sIt += num_dim) {
+            const auto& curnode = nodes[i];
+            new_location[curnode.index] = i;
+            auto start = vals + num_dim * curnode.index;
+            std::copy(start, start + num_dim, sIt);
+        }
+        return;
+    }
+
+    std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(INDEX_t index, int k) const {
+        NeighborQueue<INDEX_t, INTERNAL_t> nearest(k, index);
+        INTERNAL_t tau = std::numeric_limits<INTERNAL_t>::max();
+        search_nn(0, store.data() + new_location[index] * num_dim, tau, nearest);
+        return nearest.template report<DISTANCE_t>();
+    }
+
+    std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(const QUERY_t* query, int k) const {
+        NeighborQueue<INDEX_t, INTERNAL_t> nearest(k);
+        INTERNAL_t tau = std::numeric_limits<INTERNAL_t>::max();
+        search_nn(0, query, tau, nearest);
+        return nearest.template report<DISTANCE_t>();
+    }
+
+    const QUERY_t* observation(INDEX_t index, QUERY_t* buffer) const {
+        auto candidate = store.data() + num_dim * new_location[index];
+        if constexpr(std::is_same<QUERY_t, INTERNAL_t>::value) {
+            return candidate;
+        } else {
+            std::copy(candidate, candidate + num_dim, buffer);
+            return buffer;
+        }
+    }
+
+    using Base<INDEX_t, DISTANCE_t, QUERY_t>::observation;
+
+private:
+    template<typename INPUT_t>
+    void search_nn(NodeIndex_t curnode_index, const INPUT_t* target, INTERNAL_t& tau, NeighborQueue<INDEX_t, INTERNAL_t>& nearest) const { 
+        if (curnode_index == LEAF_MARKER) { // indicates that we're done here
+            return;
+        }
+        
+        // Compute distance between target and current node
+        const auto& curnode=nodes[curnode_index];
+        INTERNAL_t dist = DISTANCE::normalize(DISTANCE::template raw_distance<INTERNAL_t>(store.data() + curnode_index * num_dim, target, num_dim));
+
+        // If current node within radius tau
+        if (dist < tau) {
+            nearest.add(curnode.index, dist);
+            if (nearest.is_full()) {
+                tau = nearest.limit(); // update value of tau (farthest point in result list)
+            }
+        }
+
+        // Return if we arrived at a leaf
+        if (curnode.left == LEAF_MARKER && curnode.right == LEAF_MARKER) {
+            return;
+        }
+        
+        // If the target lies within the radius of ball
+        if (dist < curnode.threshold) {
+            if (dist - tau <= curnode.threshold) {         // if there can still be neighbors inside the ball, recursively search left child first
+                search_nn(curnode.left, target, tau, nearest);
+            }
+            
+            if (dist + tau >= curnode.threshold) {         // if there can still be neighbors outside the ball, recursively search right child
+                search_nn(curnode.right, target, tau, nearest);
+            }
+        
+        // If the target lies outsize the radius of the ball
+        } else {
+            if (dist + tau >= curnode.threshold) {         // if there can still be neighbors outside the ball, recursively search right child first
+                search_nn(curnode.right, target, tau, nearest);
+            }
+            
+            if (dist - tau <= curnode.threshold) {         // if there can still be neighbors inside the ball, recursively search left child
+                search_nn(curnode.left, target, tau, nearest);
+            }
+        }
+    }
+};
+
+/**
+ * Perform a VP tree search with Euclidean distances.
+ */
+template<typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = double>
+using VpTreeEuclidean = VpTree<distances::Euclidean, INDEX_t, DISTANCE_t, QUERY_t, INTERNAL_t>;
+
+/**
+ * Perform a VP tree search with Manhattan distances.
+ */
+template<typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t, typename INTERNAL_t = double>
+using VpTreeManhattan = VpTree<distances::Manhattan, INDEX_t, DISTANCE_t, QUERY_t, INTERNAL_t>;
+
+};
+
+#endif

data/vendor/knncolle/knncolle.hpp

@@ -0,0 +1,34 @@
+#ifndef KNNCOLLE_HPP
+#define KNNCOLLE_HPP
+
+#include "BruteForce/BruteForce.hpp"
+#include "VpTree/VpTree.hpp"
+
+#ifndef KNNCOLLE_NO_KMKNN
+#include "Kmknn/Kmknn.hpp"
+#endif
+
+#ifndef KNNCOLLE_NO_ANNOY
+#include "Annoy/Annoy.hpp"
+#endif
+
+#ifndef KNNCOLLE_NO_HNSW
+#include "Hnsw/Hnsw.hpp"
+#endif
+
+#include "utils/find_nearest_neighbors.hpp"
+
+/**
+ * @file knncolle.hpp
+ *
+ * @brief Umbrella header to include all algorithms.
+ *
+ * Developers can avoid the inclusion of unnecessary dependencies by setting:
+ *
+ * - `KNNCOLLE_NO_KMKNN`, to avoid including the `Kmknn.hpp` header (which requires the **kmeans** library).
+ * - `KNNCOLLE_NO_ANNOY`, to avoid including the `Annoy.hpp` header (which requires the **Annoy** library).
+ * - `KNNCOLLE_NO_HNSW`, to avoid including the `Hnsw.hpp` header (which requires the **Hnsw** library).
+ */
+
+#endif
+

data/vendor/knncolle/utils/Base.hpp

@@ -0,0 +1,100 @@
+#ifndef KNNCOLLE_BASE_HPP
+#define KNNCOLLE_BASE_HPP
+
+#include <vector>
+
+/**
+ * @file Base.hpp
+ *
+ * @brief Defines the virtual base class for all **knncolle** methods.
+ */
+
+namespace knncolle {
+
+/**
+ * @brief Virtual base class defining the **knncolle** interface.
+ *
+ * Defines the minimum set of methods, to be implemented by all concrete subclasses. 
+ *
+ * @tparam INDEX_t Integer type for the indices.
+ * @tparam DISTANCE_t Floating point type for the distances.
+ * @tparam QUERY_t Floating point type for the query data.
+ */
+template<typename INDEX_t = int, typename DISTANCE_t = double, typename QUERY_t = DISTANCE_t>
+class Base {
+public:
+    /**
+     * Get the number of observations in the dataset to be searched.
+     */
+    virtual INDEX_t nobs() const = 0;
+    
+    /**
+     * Get the number of dimensions.
+     */
+    virtual INDEX_t ndim() const = 0;
+
+    virtual ~Base() {}
+
+public:
+    /**
+     * Get the vector of coordinates for a given observation in the dataset. 
+     * Type conversions may be performed if `QUERY_t` differs from the type of the internal data store.
+     *
+     * `buffer` may not be filled if a pointer to the internal data store can be returned directly.
+     * This can be assumed to be the case if the return address is not the same as `buffer`.
+     *
+     * @param index Index of the observation.
+     * This should be non-negative and less than the total number of observations in `nobs()`.
+     * @param buffer Buffer to store the coordinates.
+     *
+     * @return A pointer to an array containing the coordinate vector.
+     *
+     */
+    virtual const QUERY_t* observation(INDEX_t index, QUERY_t* buffer) const = 0;
+
+    /**
+     * Get the vector of coordinates for a given observation in the dataset. 
+     * Type conversions may be performed if `QUERY_t` differs from the type of the internal data store.
+     *
+     * @param index Index of the observation.
+     *
+     * @return A vector of coordinates.
+     *
+     */
+    virtual std::vector<QUERY_t> observation(INDEX_t index) const {
+        std::vector<QUERY_t> output(ndim());
+        auto ptr = observation(index, output.data());
+        if (ptr != output.data()) {
+            std::copy(ptr, ptr + output.size(), output.data());
+        }
+        return output;
+    }
+
+public:
+    /** 
+     * Find the nearest neighbors of the `index`-th observation in the dataset.
+     *
+     * @param index The index of the observation of interest.
+     * This should be non-negative and less than the total number of observations in `nobs()`.
+     * @param k The number of neighbors to identify.
+     *
+     * @return A vector of (index, distance) pairs containing the identities of the nearest neighbors in order of increasing distance.
+     * Length is at most `k` but may be shorter if the total number of observations is less than `k + 1`.
+     */
+    virtual std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(INDEX_t index, int k) const = 0;
+
+    /** 
+     * Find the nearest neighbors of a new observation.
+     *
+     * @param query Pointer to an array of length equal to `ndims()`, containing the coordinates of the query point.
+     * @param k The number of neighbors to identify.
+     *
+     * @return A vector of (index, distance) pairs containing the identities of the nearest neighbors in order of increasing distance.
+     * Length is at most `k` but may be shorter if the total number of observations is less than `k`.
+     */
+    virtual std::vector<std::pair<INDEX_t, DISTANCE_t> > find_nearest_neighbors(const QUERY_t* query, int k) const = 0;
+};
+
+}
+
+#endif