feat(machinelearning): add K-Means clustering algorithm

Author: Tejashribambal19

src/main/java/com/thealgorithms/machinelearning/KMeans.java

@@ -2,13 +2,26 @@
 
 /**
  * Implements the K-Means clustering algorithm using Lloyd's algorithm.
+ *
+ * <p>
+ * K-Means partitions observations into k clusters by iteratively assigning each
+ * point to its nearest centroid and recomputing centroid positions until
+ * convergence or the maximum number of iterations is reached.
  */
 public final class KMeans {
 
     private KMeans() {
+
         // Utility class
     }
 
+    /**
+     * Computes the squared Euclidean distance between two points.
+     *
+     * @param point1 first point
+     * @param point2 second point
+     * @return squared Euclidean distance
+     */
     private static double squaredDistance(double[] point1, double[] point2) {
         double sum = 0.0;
         for (int i = 0; i < point1.length; i++) {
@@ -18,6 +31,13 @@ private static double squaredDistance(double[] point1, double[] point2) {
         return sum;
     }
 
+    /**
+     * Finds the nearest centroid for the given point.
+     *
+     * @param point point to classify
+     * @param centroids current centroids
+     * @return index of the nearest centroid
+     */
     private static int nearestCentroid(double[] point, double[][] centroids) {
         int nearest = 0;
         double minimumDistance = squaredDistance(point, centroids[0]);
@@ -41,6 +61,7 @@ private static int nearestCentroid(double[] point, double[][] centroids) {
      * @param maxIterations maximum number of iterations
      * @param tolerance convergence tolerance
      * @return cluster assignment for each point
+     * @throws IllegalArgumentException if the input is invalid
      */
     public static int[] cluster(
             double[][] points,
@@ -72,18 +93,31 @@ public static int[] cluster(
             throw new IllegalArgumentException("Tolerance cannot be negative.");
         }
 
+        if (points[0] == null) {
+            throw new IllegalArgumentException("Points cannot contain null rows.");
+        }
+
         int dimensions = points[0].length;
+
         if (dimensions == 0) {
             throw new IllegalArgumentException("Points must have at least one dimension.");
         }
 
         for (double[] point : points) {
+            if (point == null) {
+                throw new IllegalArgumentException("Points cannot contain null rows.");
+            }
+
             if (point.length != dimensions) {
                 throw new IllegalArgumentException("All points must have the same dimension.");
             }
         }
 
         for (double[] centroid : initialCentroids) {
+            if (centroid == null) {
+                throw new IllegalArgumentException("Centroids cannot contain null rows.");
+            }
+
             if (centroid.length != dimensions) {
                 throw new IllegalArgumentException("Centroid dimensions must match point dimensions.");
             }

src/test/java/com/thealgorithms/machinelearning/KMeansTest.java

@@ -1,6 +1,7 @@
 package com.thealgorithms.machinelearning;
 
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import org.junit.jupiter.api.Test;
 
 class KMeansTest {
@@ -27,4 +28,219 @@ void testSimpleClustering() {
                 KMeans.cluster(points, centroids, 100, 0.0001)
         );
     }
+
+    @Test
+    void testNullCentroids() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, null, 100, 0.0001)
+        );
+
+    }
+
+    @Test
+    void testEmptyDataset() {
+        double[][] points = {};
+        double[][] centroids = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testEmptyPoints() {
+        double[][] points = {};
+        double[][] centroids = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testNoCentroids() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+
+        double[][] centroids = {};
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testNonPositiveMaxIterations() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+
+        double[][] centroids = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 0, 0.0001)
+        );
+    }
+
+    @Test
+    void testNegativeTolerance() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+        double[][] centroids = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, -1.0)
+        );
+    }
+
+    @Test
+    void testTooManyCentroids() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+
+        double[][] centroids = {
+            {1.0, 1.0},
+            {2.0, 2.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testDimensionMismatchInPoints() {
+        double[][] points = {
+            {1.0, 1.0},
+            {2.0}
+        };
+
+        double[][] centroids = {
+            {1.0, 1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testDimensionMismatchInCentroids() {
+        double[][] points = {
+            {1.0, 1.0}
+        };
+
+        double[][] centroids = {
+            {1.0}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testZeroDimensionPoints() {
+        double[][] points = {
+            {}
+        };
+
+        double[][] centroids = {
+            {}
+        };
+
+        assertThrows(
+                IllegalArgumentException.class,
+                () -> KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testSingleCluster() {
+        double[][] points = {
+            {1.0, 1.0},
+            {2.0, 2.0},
+            {3.0, 3.0}
+        };
+
+        double[][] centroids = {
+            {2.0, 2.0}
+        };
+
+        int[] expected = {
+            0, 0, 0
+        };
+
+        assertArrayEquals(
+                expected,
+                KMeans.cluster(points, centroids, 100, 0.0001)
+        );
+    }
+
+    @Test
+    void testEmptyClusterHandling() {
+        double[][] points = {
+            {0.0, 0.0},
+            {0.1, 0.1},
+            {10.0, 10.0}
+        };
+
+        double[][] centroids = {
+            {0.0, 0.0},
+            {100.0, 100.0}
+        };
+
+        int[] result = KMeans.cluster(points, centroids, 100, 0.0001);
+
+        assertArrayEquals(
+                new int[]{0, 0, 0},
+                result
+        );
+    }
+
+    @Test
+    void testImmediateConvergence() {
+        double[][] points = {
+            {1.0, 1.0},
+            {9.0, 9.0}
+        };
+
+        double[][] centroids = {
+            {1.0, 1.0},
+            {9.0, 9.0}
+        };
+
+        int[] expected = {
+            0, 1
+        };
+
+        assertArrayEquals(
+                expected,
+                KMeans.cluster(points, centroids, 100, 0.000001)
+        );
+    }
 }