adding max iterations threshold

Author: bdelespierre

src/Algorithm.php

@@ -30,21 +30,32 @@ public function registerIterationCallback(callable $callback): void
         $this->iterationCallbacks[] = $callback;
     }
 
-    public function clusterize(PointCollectionInterface $points, int $nbClusters): ClusterCollectionInterface
-    {
+    public function clusterize(
+        PointCollectionInterface $points,
+        int $nClusters,
+        ?int $maxIter = null
+    ): ClusterCollectionInterface {
+        $maxIter ??= INF;
+
+        if ($maxIter < 1) {
+            throw new \UnexpectedValueException(
+                "Invalid maximum number of iterations: {$maxIter}"
+            );
+        }
+
         // initialize clusters
-        $clusters = $this->initScheme->initializeClusters($points, $nbClusters);
+        $clusters = $this->initScheme->initializeClusters($points, $nClusters);
 
         // iterate until convergence is reached
         do {
             $this->invokeIterationCallbacks($clusters);
-        } while ($this->iterate($clusters));
+        } while ($this->iterate($clusters) && --$maxIter);
 
         // clustering is done.
         return $clusters;
     }
 
-    private function iterate(ClusterCollectionInterface $clusters): bool
+    protected function iterate(ClusterCollectionInterface $clusters): bool
     {
         /** @var \SplObjectStorage<ClusterInterface, null> */
         $changed = new \SplObjectStorage();
@@ -78,13 +89,13 @@ private function iterate(ClusterCollectionInterface $clusters): bool
 
     private function getClosestCluster(ClusterCollectionInterface $clusters, PointInterface $point): ClusterInterface
     {
-        $min = null;
+        $min = INF;
         $closest = null;
 
         foreach ($clusters as $cluster) {
             $distance = $this->getDistanceBetween($point, $cluster->getCentroid());
 
-            if (is_null($min) || $distance < $min) {
+            if ($distance < $min) {
                 $min = $distance;
                 $closest = $cluster;
             }

tests/Unit/Euclidean/AlgorithmTest.php

@@ -6,11 +6,13 @@
 use Kmeans\Euclidean\Point;
 use Kmeans\Euclidean\Space;
 use Kmeans\Interfaces\AlgorithmInterface;
+use Kmeans\Interfaces\ClusterCollectionInterface;
 use Kmeans\Interfaces\InitializationSchemeInterface;
 use Kmeans\Interfaces\PointCollectionInterface;
 use Kmeans\Interfaces\SpaceInterface;
 use Kmeans\Math;
 use Kmeans\PointCollection;
+use Kmeans\RandomInitialization;
 use Tests\Unit\AlgorithmTest as BaseAlgorithmTest;
 
 /**
@@ -24,6 +26,7 @@
  * @uses \Kmeans\Euclidean\Space
  * @uses \Kmeans\Math
  * @uses \Kmeans\PointCollection
+ * @uses \Kmeans\RandomInitialization
  * @phpstan-import-type ClusterizeScenarioData from BaseAlgorithmTest
  */
 class AlgorithmTest extends BaseAlgorithmTest
@@ -146,4 +149,43 @@ public function testFindCentroidException(): void
             new PointCollection(new \Kmeans\Gps\Space(), [])
         );
     }
+
+    public function testMaxIterations(): void
+    {
+        $algorithm = new class (new RandomInitialization()) extends Algorithm
+        {
+            protected function iterate(ClusterCollectionInterface $clusters): bool
+            {
+                // do nothing and iterate indefinitely
+                return true;
+            }
+        };
+
+        $iterations = 0;
+        $algorithm->registerIterationCallback(function () use (&$iterations) {
+            $iterations++;
+        });
+
+        $space = new Space(1);
+        $points = new PointCollection(
+            $space,
+            array_map([$space, 'makePoint'], [[1],[2],[3]])
+        );
+
+        $algorithm->clusterize($points, 3, 300);
+
+        $this->assertEquals(
+            300,
+            $iterations
+        );
+    }
+
+    public function testMaxIterationsException(): void
+    {
+        $this->expectException(\UnexpectedValueException::class);
+        $this->expectExceptionMessageMatches('/^Invalid maximum number of iterations/');
+
+        $algorithm = new Algorithm(new RandomInitialization());
+        $algorithm->clusterize(new PointCollection(new Space(1), []), 3, 0);
+    }
 }