Add Hamerly's accelerated K-means algorithm to linfa-clustering (#439)

* feat(linfa-clustering): Add Hamerly's accelerated K-means algorithm

Implement K-means Hamerly's triangle-inequality optimization as an alternative to Lloyd's algorithm for K-means clustering. For each observation the algorithm maintains upper/lower distance bounds and skips centroid comparisons that cannot change the assignment, yielding the same results as Lloyd but with significantly fewer distance computations when clusters are well separated.

Key changes:
- The new Hamerly K-means algorithm
- Add KMeansAlgorithm enum (Lloyd | Hamerly) and .algorithm() builder method
- Reject Hamerly for incremental fit_with
- Comprehensive tests

* fix: format code

* fix: Change the execution order of linfa-clustering k-means benchmarking

Author: mrsanor

algorithms/linfa-clustering/benches/k_means.rs

@@ -5,7 +5,7 @@ use criterion::{
 use linfa::benchmarks::config;
 use linfa::prelude::*;
 use linfa::DatasetBase;
-use linfa_clustering::{IncrKMeansError, KMeans, KMeansInit};
+use linfa_clustering::{IncrKMeansError, KMeans, KMeansAlgorithm, KMeansInit};
 use linfa_datasets::generate;
 use ndarray::Array2;
 use ndarray_rand::RandomExt;
@@ -36,9 +36,10 @@ impl Drop for Stats {
 fn k_means_bench(c: &mut Criterion) {
     let mut rng = Xoshiro256Plus::seed_from_u64(40);
     let cluster_sizes = [(100, 4), (400, 10), (3000, 10)];
+    let algorithms = [KMeansAlgorithm::Lloyd, KMeansAlgorithm::Hamerly];
     let n_features = 3;
 
-    let mut benchmark = c.benchmark_group("naive_k_means");
+    let mut benchmark = c.benchmark_group("k_means");
     config::set_default_benchmark_configs(&mut benchmark);
     benchmark.plot_config(PlotConfiguration::default().summary_scale(AxisScale::Logarithmic));
 
@@ -47,22 +48,29 @@ fn k_means_bench(c: &mut Criterion) {
         let centroids =
             Array2::random_using((n_clusters, n_features), Uniform::new(-30., 30.), rng);
         let dataset = DatasetBase::from(generate::blobs(cluster_size, &centroids, rng));
-        let mut stats = Stats::default();
+        for &algorithm in &algorithms {
+            let mut stats = Stats::default();
 
-        benchmark.bench_function(
-            BenchmarkId::new("naive_k_means", format!("{n_clusters}x{cluster_size}")),
-            |bencher| {
-                bencher.iter(|| {
-                    let m = KMeans::params_with_rng(black_box(n_clusters), black_box(rng.clone()))
-                        .init_method(KMeansInit::KMeansPlusPlus)
-                        .max_n_iterations(black_box(1000))
-                        .tolerance(black_box(1e-3))
-                        .fit(&dataset)
-                        .unwrap();
-                    stats.add(m.inertia());
-                });
-            },
-        );
+            benchmark.bench_function(
+                BenchmarkId::new(
+                    "k_means",
+                    format!("{algorithm:?}:{n_clusters}x{cluster_size}"),
+                ),
+                |bencher| {
+                    bencher.iter(|| {
+                        let m =
+                            KMeans::params_with_rng(black_box(n_clusters), black_box(rng.clone()))
+                                .init_method(KMeansInit::KMeansPlusPlus)
+                                .algorithm(algorithm)
+                                .max_n_iterations(black_box(1000))
+                                .tolerance(black_box(1e-3))
+                                .fit(&dataset)
+                                .unwrap();
+                        stats.add(m.inertia());
+                    });
+                },
+            );
+        }
     }
 
     benchmark.finish();