umappp 0.1.2

data/vendor/kmeans/InitializePCAPartition.hpp

@@ -0,0 +1,309 @@
+#ifndef KMEANS_INITIALIZE_PCA_PARTITION_HPP
+#define KMEANS_INITIALIZE_PCA_PARTITION_HPP
+
+#include <iostream>
+#include <random>
+#include <vector>
+#include <cmath>
+#include <algorithm>
+#include <numeric>
+
+#include "aarand/aarand.hpp"
+#include "powerit/PowerIterations.hpp"
+#include "Base.hpp"
+
+/**
+ * @file InitializePCAPartition.hpp
+ *
+ * @brief Class for k-means initialization with PCA partitioning.
+ */
+namespace kmeans {
+
+/**
+ * @brief Implements the PCA partitioning method of Su and Dy (2007).
+ *
+ * This approach involves the selection of starting points via iterative partitioning based on principal components analysis.
+ * The aim is to obtain well-separated starting points for refinement with algorithms like Hartigan-Wong or Lloyd.
+ * This is achieved by selecting the most dispersed cluster for further partitioning.
+ *
+ * We start from a single cluster containing all points.
+ * At each iteration, we select the cluster with the largest within-cluster sum of squares (WCSS);
+ * we identify the first principal component within that cluster;
+ * and we split the cluster at its center along that axis to obtain two new clusters.
+ * This is repeated until the desired number of clusters is obtained, and the centers and cluster identifiers are then reported.
+ *
+ * The original algorithm favors selection and partitioning of the largest cluster, which has the greatest chance of having the highest WCSS.
+ * For more fine-grained control, we modify the procedure to adjust the effective number of observations contributing to the WCSS.
+ * Specifically, we choose the cluster to partition based on the product of $N$ and the mean squared difference within each cluster,
+ * where $N$ is the cluster size raised to some user-specified power (i.e., the "size adjustment") between 0 and 1.
+ * An adjustment of 1 recapitulates the original algorithm, while smaller values of the size adjustment will reduce the preference towards larger clusters.
+ * A value of zero means that the cluster size is completely ignored, though this seems unwise as it causes excessive splitting of small clusters with unstable WCSS.
+ *
+ * This method is not completely deterministic as a randomization step is used in the PCA.
+ * Nonetheless, the stochasticity is likely to have a much smaller effect than in the other initialization methods.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster index.
+ * @tparam INDEX_t Integer type for the observation index.
+ *
+ * @seealso
+ * Su, T. and Dy, J. G. (2007).
+ * In Search of Deterministic Methods for Initializing K-Means and Gaussian Mixture Clustering,
+ * _Intelligent Data Analysis_ 11, 319-338.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class InitializePCAPartition : public Initialize<DATA_t, CLUSTER_t, INDEX_t> {
+public:
+    /**
+     * @brief Default parameter settings.
+     */
+    struct Defaults {
+        /**
+         * See `set_size_adjustment()` for more details.
+         */
+        static constexpr DATA_t size_adjustment = 1;
+
+        /**
+         * See `set_seed()` for more details.
+         */
+        static constexpr uint64_t seed = 6523u;
+    };
+
+public:
+    /**
+     * @param i Maximum number of power iterations to use in `powerit::PowerIterations::set_iterations()`.
+     * @return A reference to this `InitializePCAPartition` object.
+     */
+    InitializePCAPartition& set_iterations(int i = powerit::PowerIterations::Defaults::iterations) {
+        iters = i;
+        return *this;
+    }
+
+    /**
+     * @param t Convergence threshold to use in `powerit::PowerIterations::set_tolerance()`.
+     * @return A reference to this `InitializePCAPartition` object.
+     */
+    InitializePCAPartition& set_tolerance(DATA_t t = powerit::PowerIterations::Defaults::tolerance) {
+        tol = t;
+        return *this;
+    }
+
+    /**
+     * @param s Size adjustment value, should lie in [0, 1].
+     * @return A reference to this `InitializePCAPartition` object.
+     */
+    InitializePCAPartition& set_size_adjustment(DATA_t s = Defaults::size_adjustment) {
+        adjust = s;
+        return *this;
+    }
+
+    /**
+     * @param Random seed to use to construct the PRNG for the power method.
+     * @return A reference to this `InitializePCAPartition` object.
+     */
+    InitializePCAPartition& set_seed(uint64_t s = Defaults::seed) {
+        seed = s;
+        return *this;
+    }
+private:
+    int iters = powerit::PowerIterations::Defaults::iterations;
+    DATA_t tol = powerit::PowerIterations::Defaults::tolerance;
+    DATA_t adjust = Defaults::size_adjustment;
+    uint64_t seed = Defaults::seed;
+
+public:
+    /**
+     * @cond
+     */
+    static DATA_t normalize(int ndim, DATA_t* x) {
+        DATA_t ss = 0;
+        for (int d = 0; d < ndim; ++d) {
+            ss += x[d] * x[d];
+        }
+
+        if (ss) {
+            ss = std::sqrt(ss);
+            for (int d = 0; d < ndim; ++d) {
+                x[d] /= ss;
+            }
+        }
+        return ss;
+    }
+
+    template<class Rng>
+    std::vector<DATA_t> compute_pc1(int ndim, const std::vector<INDEX_t>& chosen, const DATA_t* data, const DATA_t* center, Rng& eng) const {
+        std::vector<DATA_t> delta(ndim);
+        std::vector<DATA_t> cov(ndim * ndim);
+
+        // Computing the lower triangle of the covariance matrix. 
+        for (auto i : chosen) {
+            auto dptr = data + i * ndim;
+            for (int j = 0; j < ndim; ++j) {
+                delta[j] = dptr[j] - center[j];
+            }
+            for (int j = 0; j < ndim; ++j) {
+                for (int k = 0; k <= j; ++k) {
+                    cov[j * ndim + k] += delta[j] * delta[k];
+                }
+            }
+        }
+
+        // Filling in the other side of the matrix, to enable cache-efficient multiplication.
+        for (size_t j = 0; j < ndim; ++j) {
+            for (size_t k = j + 1; k < ndim; ++k) {
+                cov[j * ndim + k] = cov[k * ndim + j];
+            }
+        }
+
+        powerit::PowerIterations power;
+        power.set_iterations(iters).set_tolerance(tol);
+
+        std::vector<DATA_t> output(ndim);
+        power.run(ndim, cov.data(), output.data(), eng);
+        return output;
+    } 
+
+    static void compute_center(int ndim, INDEX_t nobs, const DATA_t* data, DATA_t* center) {
+        std::fill(center, center + ndim, 0);
+        for (size_t i = 0; i < nobs; ++i) {
+            auto dptr = data + i * ndim;
+            for (int d = 0; d < ndim; ++d) {
+                center[d] += dptr[d];
+            }
+        }
+        for (int d = 0; d < ndim; ++d) {
+            center[d] /= nobs;
+        }
+    }
+
+    static void compute_center(int ndim, const std::vector<INDEX_t>& chosen, const DATA_t* data, DATA_t* center) {
+        std::fill(center, center + ndim, 0);
+        for (auto i : chosen) {
+            auto dptr = data + i * ndim;
+            for (int d = 0; d < ndim; ++d) {
+                center[d] += dptr[d];
+            }
+        }
+        for (int d = 0; d < ndim; ++d) {
+            center[d] /= chosen.size();
+        }
+    }
+
+    static DATA_t update_mrse(int ndim, const std::vector<INDEX_t>& chosen, const DATA_t* data, DATA_t* center) {
+        compute_center(ndim, chosen, data, center);
+
+        DATA_t curmrse = 0;
+        for (auto i : chosen) {
+            auto dptr = data + i * ndim;
+            for (int d = 0; d < ndim; ++d) {
+                DATA_t delta = dptr[d] - center[d];
+                curmrse += delta * delta;
+            }
+        }
+
+        return curmrse / chosen.size();
+    }
+    /**
+     * @endcond
+     */
+public:
+    /*
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param data Pointer to an array where the dimensions are rows and the observations are columns.
+     * Data should be stored in column-major format.
+     * @param ncenters Number of centers to pick.
+     * @param[out] centers Pointer to a `ndim`-by-`ncenters` array where columns are cluster centers and rows are dimensions. 
+     * On output, this will contain the final centroid locations for each cluster.
+     * Data should be stored in column-major order.
+     * @param clusters Pointer to an array of length `nobs`.
+     * This is used as a buffer and the contents on output should not be used.
+     *
+     * @return `centers` is filled with the new cluster centers.
+     * The number of filled centers is returned, see `Initializer::run()`.
+     */
+    CLUSTER_t run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters) {
+        if (nobs == 0) {
+            return 0;
+        }
+
+        std::mt19937_64 rng(seed);
+        std::vector<DATA_t> mrse(ncenters);
+        std::vector<std::vector<INDEX_t> > assignments(ncenters);
+
+        // Setting up the zero'th cluster. (No need to actually compute the
+        // MRSE at this point, as there's nothing to compare it to.)
+        compute_center(ndim, nobs, data, centers);
+        assignments[0].resize(nobs);
+        std::iota(assignments.front().begin(), assignments.front().end(), 0);
+        std::fill(clusters, clusters + nobs, 0);
+
+        for (CLUSTER_t cluster = 1; cluster < ncenters; ++cluster) {
+            DATA_t worst_ss = 0;
+            INDEX_t worst_cluster = 0;
+            for (CLUSTER_t i = 0; i < cluster; ++i) {
+                DATA_t multiplier = assignments[i].size();
+                if (adjust != 1) {
+                    multiplier = std::pow(static_cast<DATA_t>(multiplier), adjust);
+                }
+
+                DATA_t pseudo_ss = mrse[i] * multiplier;
+                if (pseudo_ss > worst_ss) {
+                    worst_ss = pseudo_ss;
+                    worst_cluster = i;
+                }
+            }
+
+            // Extracting the principal component for this bad boy.
+            auto worst_center = centers + worst_cluster * ndim;
+            auto& worst_assignments = assignments[worst_cluster];
+            auto pc1 = compute_pc1(ndim, worst_assignments, data, worst_center, rng);
+
+            // Projecting all points in this cluster along PC1. The center lies
+            // at zero, so everything positive (on one side of the hyperplane
+            // orthogonal to PC1 and passing through the center) gets bumped to
+            // the next cluster.
+            std::vector<INDEX_t>& new_assignments = assignments[cluster];
+            std::vector<INDEX_t> worst_assignments2;
+            for (auto i : worst_assignments) {
+                auto dptr = data + i * ndim;
+                DATA_t proj = 0;
+                for (int d = 0; d < ndim; ++d) {
+                    proj += (dptr[d] - worst_center[d]) * pc1[d];
+                }
+
+                if (proj > 0) {
+                    new_assignments.push_back(i);
+                } else {
+                    worst_assignments2.push_back(i);
+                }
+            }
+
+            // If one or the other is empty, then this entire procedure short
+            // circuits as all future iterations will just re-select this
+            // cluster (which won't get partitioned properly anyway). In the
+            // bigger picture, the quick exit out of the iterations is correct
+            // as we should only fail to partition in this manner if all points
+            // within each remaining cluster are identical.
+            if (new_assignments.empty() || worst_assignments2.empty()) {
+                return cluster;
+            }
+
+            for (auto i : new_assignments) {
+                clusters[i] = cluster;
+            }
+            worst_assignments.swap(worst_assignments2);
+
+            // Computing centers and MRSE.
+            auto new_center = centers + cluster * ndim;
+            mrse[cluster] = update_mrse(ndim, new_assignments, data, new_center);
+            mrse[worst_cluster] = update_mrse(ndim, worst_assignments, data, worst_center);
+        }
+
+        return ncenters;
+    }
+};
+
+}
+
+#endif

data/vendor/kmeans/InitializeRandom.hpp

@@ -0,0 +1,91 @@
+#ifndef KMEANS_INITIALIZE_RANDOM_HPP
+#define KMEANS_INITIALIZE_RANDOM_HPP 
+
+#include <algorithm>
+#include <cstdint>
+#include <random>
+
+#include "Base.hpp"
+#include "random.hpp"
+
+/**
+ * @file InitializeRandom.hpp
+ *
+ * @brief Class for random initialization.
+ */
+
+namespace kmeans {
+
+/**
+ * @cond
+ */
+template<class V, typename DATA_t>
+void copy_into_array(const V& chosen, int ndim, const DATA_t* in, DATA_t* out) {
+    for (auto c : chosen) {
+        auto ptr = in + c * ndim;
+        std::copy(ptr, ptr + ndim, out);
+        out += ndim;
+    }
+    return;
+}
+/**
+ * @endcond
+ */
+
+/**
+ * @brief Initialize starting points by sampling random observations without replacement.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster index.
+ * @tparam INDEX_t Integer type for the observation index.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class InitializeRandom : public Initialize<DATA_t, CLUSTER_t, INDEX_t> { 
+public:
+    /**
+     * @brief Default parameter settings.
+     */
+    struct Defaults {
+        /**
+         * See `set_seed()` for more details.
+         */
+        static constexpr uint64_t seed = 6523u;
+    };
+
+    /**
+     * @param Random seed to use to construct the PRNG prior to sampling.
+     *
+     * @return A reference to this `InitializeRandom` object.
+     */
+    InitializeRandom& set_seed(uint64_t s = Defaults::seed) {
+        seed = s;
+        return *this;
+    }
+private:
+    uint64_t seed = Defaults::seed;
+public:
+    /*
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param data Pointer to an array where the dimensions are rows and the observations are columns.
+     * Data should be stored in column-major format.
+     * @param ncenters Number of centers to pick.
+     * @param[out] centers Pointer to a `ndim`-by-`ncenters` array where columns are cluster centers and rows are dimensions. 
+     * On output, this will contain the final centroid locations for each cluster.
+     * Data should be stored in column-major order.
+     * @param clusters Ignored in this method.
+     *
+     * @return `centers` is filled with the new cluster centers.
+     * The number of filled centers is returned, see `Initializer::run()`.
+     */
+    CLUSTER_t run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters) {
+        std::mt19937_64 eng(seed);
+        auto chosen = sample_without_replacement(nobs, ncenters, eng);
+        copy_into_array(chosen, ndim, data, centers);
+        return chosen.size();
+    }
+};
+
+}
+
+#endif

data/vendor/kmeans/Kmeans.hpp

@@ -0,0 +1,161 @@
+#ifndef KMEANS_KMEANS_HPP
+#define KMEANS_KMEANS_HPP
+
+#include "Base.hpp"
+#include "HartiganWong.hpp"
+#include "InitializeKmeansPP.hpp"
+#include "Details.hpp"
+#include <random>
+
+/** 
+ * @file Kmeans.hpp
+ *
+ * @brief Implements the full k-means clustering procedure.
+ */
+
+namespace kmeans {
+
+/**
+ * @brief Top-level class to run k-means clustering.
+ *
+ * k-means clustering aims to partition a dataset of `nobs` observations into `ncenters` clusters where `ncenters` is specified in advance.
+ * Each observation is assigned to its closest cluster based on the distance to the cluster centroids.
+ * The cluster centroids themselves are chosen to minimize the sum of squared Euclidean distances from each observation to its assigned cluster.
+ * This procedure involves some heuristics to choose a good initial set of centroids (see `weighted_initialization()` for details) 
+ * and to converge to a local minimum (see `HartiganWong`, `Lloyd` or `MiniBatch` for details).
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster assignments.
+ * @tparam INDEX_t Integer type for the observation index.
+ * This should have a maximum positive value that is at least 50 times greater than the maximum expected number of observations.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class Kmeans {
+public:
+    /** 
+     * @brief Default parameter values for `Kmeans`.
+     */
+    struct Defaults {
+        /**
+         * See `set_seed()` for more details.
+         */
+        static constexpr uint64_t seed = 5489u;
+    };
+
+private:
+    uint64_t seed = Defaults::seed;
+
+public:
+    /** 
+     * @param s Seed to use for PRNG.
+     * Defaults to default seed for the `std::mt19937_64` constructor.
+     *
+     * @return A reference to this `Kmeans` object.
+     *
+     * This seed is only used for the default `refiner` and `initializer` instances in `run()`.
+     * Otherwise, the seed from individual instances is respected.
+     */
+    Kmeans& set_seed(uint64_t s = 5489u) {
+        seed = s;
+        return *this;
+    }
+
+public:
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param[in] data Pointer to a `ndim`-by-`nobs` array where columns are observations and rows are dimensions. 
+     * Data should be stored in column-major order.
+     * @param ncenters Number of cluster centers.
+     * @param[in, out] centers Pointer to a `ndim`-by-`ncenters` array where columns are cluster centers and rows are dimensions. 
+     * On input, this should contain the initial centroid locations for each cluster if `set_initialization_method()` is `NONE`, otherwise it is ignored.
+     * On output, this will contain the final centroid locations for each cluster.
+     * Data should be stored in column-major order.
+     * @param[in, out] clusters Pointer to an array of length `nobs`.
+     * On input, this should contain the identity of the closest cluster for each observation if `set_initialization_method()` is `REINIT_PRECOMPUTED`, otherwise it is ignored.
+     * On output, this will contain the (0-indexed) cluster assignment for each observation.
+     * @param initializer Pointer to a `Initialize` object containing the desired k-means initialization method, e.g., `InitializeNone`, `InitializeRandom`, `InitializeKmeansPP`.
+     * If `NULL`, this defaults to a default-constructed `InitializeKmeansPP` instance.
+     * @param refiner Pointer to a `Refine` object containing the desired k-means refinement algorithm, e.g., `HartiganWong`, `Lloyd`, `MiniBatch`.
+     * If `NULL`, this defaults to a default-constructed `HartiganWong` instance.
+     *
+     * @return `centers` and `clusters` are filled, and a `Details` object is returned containing clustering statistics.
+     * Note that the actual number of clusters may be less than `ncenters` in pathological cases - 
+     * check the length of `Details::sizes` and the value of `Details::status`.
+     */
+    Details<DATA_t, INDEX_t> run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters, 
+        Initialize<DATA_t, CLUSTER_t, INDEX_t>* initializer = NULL, Refine<DATA_t, CLUSTER_t, INDEX_t>* refiner = NULL)
+    {
+        if (initializer == NULL) {
+            InitializeKmeansPP<DATA_t, CLUSTER_t, INDEX_t> init;
+            ncenters = init.run(ndim, nobs, data, ncenters, centers, clusters); 
+        } else {
+            ncenters = initializer->run(ndim, nobs, data, ncenters, centers, clusters); 
+        }
+
+        if (refiner == NULL) {
+            HartiganWong<DATA_t, CLUSTER_t, INDEX_t> hw;
+            return hw.run(ndim, nobs, data, ncenters, centers, clusters);
+        } else {
+            return refiner->run(ndim, nobs, data, ncenters, centers, clusters);
+        }
+    }
+
+public:
+    /**
+     * @brief Full statistics from k-means clustering.
+     */
+    struct Results {
+        /**
+         * @cond
+         */
+        Results(int ndim, INDEX_t nobs, CLUSTER_t ncenters) : centers(ndim * ncenters), clusters(nobs) {}
+        /**
+         * @endcond
+         */
+
+        /**
+         * A column-major `ndim`-by-`ncenters` array containing per-cluster centroid coordinates.
+         */
+        std::vector<DATA_t> centers;
+
+        /**
+         * An array of length `nobs` containing 0-indexed cluster assignments for each observation.
+         */
+        std::vector<CLUSTER_t> clusters;
+
+        /**
+         * Further details from the chosen k-means algorithm.
+         */
+        Details<DATA_t, INDEX_t> details;
+    };
+
+    /**
+     * @param ndim Number of dimensions.
+     * @param nobs Number of observations.
+     * @param[in] data Pointer to a `ndim`-by-`nobs` array where columns are observations and rows are dimensions. 
+     * Data should be stored in column-major order.
+     * @param ncenters Number of cluster centers.
+     * @param initializer Pointer to a `Initialize` object containing the desired k-means initialization method.
+     * If `NULL`, this defaults to a default-constructed `InitializeKmeansPP` instance.
+     * @param refiner Pointer to a `Refine` object containing the desired k-means refinement algorithm.
+     * If `NULL`, this defaults to a default-constructed `HartiganWong` instance.
+     *
+     * @return `centers` and `clusters` are filled, and a `Results` object is returned containing clustering statistics.
+     * See `run()` for more details.
+     *
+     * For this method, it would be unwise to initialize with any methods that use information from the existing cluster centers. 
+     * We suggest using only `InitializeRandom` or InitializeKmeansPP` here.
+     */
+    Results run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, 
+        Initialize<DATA_t, CLUSTER_t, INDEX_t>* initializer = NULL, Refine<DATA_t, CLUSTER_t, INDEX_t>* refiner = NULL)
+    {
+        Results output(ndim, nobs, ncenters);
+        output.details = run(ndim, nobs, data, ncenters, output.centers.data(), output.clusters.data(), initializer, refiner);
+        return output;
+    }
+};
+
+}
+
+#endif

data/vendor/kmeans/Lloyd.hpp

@@ -0,0 +1,134 @@
+#ifndef KMEANS_LLOYD_HPP
+#define KMEANS_LLOYD_HPP
+
+#include <vector>
+#include <algorithm>
+#include <numeric>
+#include <cstdint>
+#include <stdexcept>
+#include <limits>
+
+#include "Base.hpp"
+#include "Details.hpp"
+#include "QuickSearch.hpp"
+#include "is_edge_case.hpp"
+#include "compute_centroids.hpp"
+#include "compute_wcss.hpp"
+
+/**
+ * @file Lloyd.hpp
+ *
+ * @brief Implements the Lloyd algorithm for k-means clustering.
+ */
+
+namespace kmeans {
+
+/**
+ * @brief Implements the Lloyd algorithm for k-means clustering.
+ *
+ * The Lloyd algorithm is the simplest k-means clustering algorithm,
+ * involving several iterations of batch assignments and center calculations.
+ * Specifically, we assign each observation to its closest cluster, and once all points are assigned, we recompute the cluster centroids.
+ * This is repeated until there are no reassignments or the maximum number of iterations is reached.
+ *
+ * @tparam DATA_t Floating-point type for the data and centroids.
+ * @tparam CLUSTER_t Integer type for the cluster assignments.
+ * @tparam INDEX_t Integer type for the observation index.
+ *
+ * @see
+ * Lloyd, S. P. (1982).  
+ * Least squares quantization in PCM.
+ * _IEEE Transactions on Information Theory_ 28, 128-137.
+ */
+template<typename DATA_t = double, typename CLUSTER_t = int, typename INDEX_t = int>
+class Lloyd : public Refine<DATA_t, CLUSTER_t, INDEX_t> {
+public:
+    /** 
+     * @brief Default parameter values for `Lloyd`.
+     */
+    struct Defaults {
+        /** 
+         * See `Lloyd::set_max_iterations()`.
+         */
+        static constexpr int max_iterations = 10;
+    };
+
+private:
+    int maxiter = Defaults::max_iterations;
+
+public:
+    /**
+     * @param m Maximum number of iterations.
+     * More iterations increase the opportunity for convergence at the cost of more computational time.
+     *
+     * @return A reference to this `Lloyd` object.
+     */
+    Lloyd& set_max_iterations(int m = Defaults::max_iterations) {
+        maxiter = m;
+        return *this;
+    }
+
+public:
+    Details<DATA_t, INDEX_t> run(int ndim, INDEX_t nobs, const DATA_t* data, CLUSTER_t ncenters, DATA_t* centers, CLUSTER_t* clusters) {
+        if (is_edge_case(nobs, ncenters)) {
+            return process_edge_case(ndim, nobs, data, ncenters, centers, clusters);
+        }
+
+        int iter = 0, status = 0;
+        std::vector<INDEX_t> sizes(ncenters);
+        std::vector<CLUSTER_t> copy(nobs);
+
+        for (iter = 1; iter <= maxiter; ++iter) {
+            // Nearest-neighbor search to assign to the closest cluster.
+            // Note that we move the `updated` check outside of this loop
+            // so that, in the future, this is more easily parallelized.
+            QuickSearch<DATA_t, CLUSTER_t> index(ndim, ncenters, centers);
+            #pragma omp parallel for
+            for (INDEX_t obs = 0; obs < nobs; ++obs) {
+                copy[obs] = index.find(data + obs * ndim);
+            }
+
+            bool updated = false;
+            for (INDEX_t obs = 0; obs < nobs; ++obs) {
+                if (copy[obs] != clusters[obs]) {
+                    updated = true;
+                    break;
+                }
+            }
+            if (!updated) {
+                break;
+            }
+            std::copy(copy.begin(), copy.end(), clusters);
+
+            // Counting the number in each cluster.
+            std::fill(sizes.begin(), sizes.end(), 0);
+            for (INDEX_t obs = 0; obs < nobs; ++obs) {
+                ++sizes[clusters[obs]];
+            }
+
+            for (CLUSTER_t c = 0; c < ncenters; ++ c) {
+                if (!sizes[c]) {
+                    status = 1;
+                    break;
+                }
+            }
+            
+            compute_centroids(ndim, nobs, data, ncenters, centers, clusters, sizes);
+        }
+
+        if (iter == maxiter + 1) {
+            status = 2;
+        }
+
+        return Details<DATA_t, INDEX_t>(
+            std::move(sizes),
+            compute_wcss(ndim, nobs, data, ncenters, centers, clusters),
+            iter, 
+            status
+        );
+    }
+};
+
+}
+
+#endif