feat(clustering): add random_state to KMeans and MiniBatchKMeans

Replaces the hardcoded random_state=42 with a parameter. Default stays at 42 for reproducibility; pass random_state=None for non-deterministic seeding.

Adds 3 tests per class covering default-seed reproducibility, explicit-seed reproducibility (labels and centers exact, inertia with rel=1e-5 for float32 BLAS ULPs), and None opt-in. docs/guide/analysis.md gets a short note. 588 CPU tests pass; 81 GPU tests pass under serial pytest-xdist.

Author: FridrichMethod

docs/guide/analysis.md

@@ -356,6 +356,10 @@ result = KMeans(n_clusters=10)(pca.projections)
 result = MiniBatchKMeans(n_clusters=10, batch_size=1024)(pca.projections)
 result = RegularSpace(dmin=0.5)(pca.projections)
 
+# Seed is configurable -- defaults to 42 for reproducible runs.  Pass
+# random_state=None to let scikit-learn pick a non-deterministic seed.
+result = KMeans(n_clusters=10, random_state=2024)(pca.projections)
+
 # result.labels, result.n_clusters, result.cluster_centers,
 # result.medoid_frames, result.inertia
 ```

src/mdpp/analysis/clustering.py

@@ -606,14 +606,19 @@ class KMeans:
 
     Args:
         n_clusters: Number of clusters.
+        random_state: Seed for centroid initialisation. Defaults to 42 for
+            reproducible runs across sessions. Pass ``None`` to let
+            scikit-learn pick a non-deterministic seed.
         dtype: Output float dtype for *cluster_centers*.
 
     Example::
 
         result = KMeans(n_clusters=10)(pca.projections)
+        result = KMeans(n_clusters=10, random_state=None)(pca.projections)
     """
 
     n_clusters: int = 10
+    random_state: int | None = 42
     dtype: DtypeArg = None
 
     def __call__(self, features: ArrayLike) -> FeatureClusteringResult:
@@ -627,7 +632,11 @@ def __call__(self, features: ArrayLike) -> FeatureClusteringResult:
         if self.n_clusters < 1:
             raise ValueError(f"n_clusters must be >= 1, got {self.n_clusters!r}")
 
-        km = _SklearnKMeans(n_clusters=self.n_clusters, n_init="auto", random_state=42)
+        km = _SklearnKMeans(
+            n_clusters=self.n_clusters,
+            n_init="auto",
+            random_state=self.random_state,
+        )
         labels = km.fit_predict(feature_matrix)
         centers = np.asarray(km.cluster_centers_)
         inertia = float(km.inertia_)  # type: ignore[arg-type]  # set after fit
@@ -643,15 +652,21 @@ class MiniBatchKMeans:
     Args:
         n_clusters: Number of clusters.
         batch_size: Mini-batch size.
+        random_state: Seed for centroid initialisation and mini-batch
+            sampling. Defaults to 42 for reproducible runs across
+            sessions. Pass ``None`` to let scikit-learn pick a
+            non-deterministic seed.
         dtype: Output float dtype for *cluster_centers*.
 
     Example::
 
         result = MiniBatchKMeans(n_clusters=10, batch_size=1024)(pca.projections)
+        result = MiniBatchKMeans(n_clusters=10, random_state=None)(pca.projections)
     """
 
     n_clusters: int = 10
     batch_size: int = 1024
+    random_state: int | None = 42
     dtype: DtypeArg = None
 
     def __call__(self, features: ArrayLike) -> FeatureClusteringResult:
@@ -671,7 +686,7 @@ def __call__(self, features: ArrayLike) -> FeatureClusteringResult:
             n_clusters=self.n_clusters,
             batch_size=self.batch_size,
             n_init="auto",
-            random_state=42,
+            random_state=self.random_state,
         )
         labels = mbk.fit_predict(feature_matrix)
         centers = np.asarray(mbk.cluster_centers_)

tests/analysis/test_clustering.py

@@ -637,6 +637,33 @@ def test_invalid_n_clusters_raises(self, clustered_features: NDArray[np.floating
         with pytest.raises(ValueError, match="n_clusters must be >= 1"):
             KMeans(n_clusters=0)(clustered_features)
 
+    def test_random_state_default_is_reproducible(
+        self, clustered_features: NDArray[np.floating]
+    ) -> None:
+        """Two runs with the default random_state must produce identical labels."""
+        a = KMeans(n_clusters=3)(clustered_features)
+        b = KMeans(n_clusters=3)(clustered_features)
+        np.testing.assert_array_equal(a.labels, b.labels)
+
+    def test_random_state_explicit_seed_is_reproducible(
+        self, clustered_features: NDArray[np.floating]
+    ) -> None:
+        """The same explicit seed must produce identical cluster assignments."""
+        # Labels and centers must match exactly; inertia is allowed to drift
+        # by a few ULPs because BLAS reduction order varies across runs even
+        # at fixed input + seed in float32.
+        a = KMeans(n_clusters=3, random_state=7)(clustered_features)
+        b = KMeans(n_clusters=3, random_state=7)(clustered_features)
+        np.testing.assert_array_equal(a.labels, b.labels)
+        np.testing.assert_array_equal(a.cluster_centers, b.cluster_centers)
+        assert a.inertia == pytest.approx(b.inertia, rel=1e-5)
+
+    def test_random_state_none_runs(self, clustered_features: NDArray[np.floating]) -> None:
+        """random_state=None must not raise and must still recover all clusters."""
+        result = KMeans(n_clusters=3, random_state=None)(clustered_features)
+        assert isinstance(result, FeatureClusteringResult)
+        assert result.n_clusters == 3
+
 
 # ---------------------------------------------------------------------------
 # Feature-vector clustering tests: MiniBatchKMeans
@@ -668,6 +695,25 @@ def test_invalid_batch_size_raises(self, clustered_features: NDArray[np.floating
         with pytest.raises(ValueError, match="batch_size must be >= 1"):
             MiniBatchKMeans(batch_size=0)(clustered_features)
 
+    def test_random_state_explicit_seed_is_reproducible(
+        self, clustered_features: NDArray[np.floating]
+    ) -> None:
+        """The same explicit seed must produce identical cluster assignments."""
+        # Labels and centers must match exactly; inertia is allowed to drift
+        # by a few ULPs because BLAS reduction order varies across runs even
+        # at fixed input + seed in float32.
+        a = MiniBatchKMeans(n_clusters=3, batch_size=16, random_state=11)(clustered_features)
+        b = MiniBatchKMeans(n_clusters=3, batch_size=16, random_state=11)(clustered_features)
+        np.testing.assert_array_equal(a.labels, b.labels)
+        np.testing.assert_array_equal(a.cluster_centers, b.cluster_centers)
+        assert a.inertia == pytest.approx(b.inertia, rel=1e-5)
+
+    def test_random_state_none_runs(self, clustered_features: NDArray[np.floating]) -> None:
+        """random_state=None must not raise and must still recover all clusters."""
+        result = MiniBatchKMeans(n_clusters=3, random_state=None)(clustered_features)
+        assert isinstance(result, FeatureClusteringResult)
+        assert result.n_clusters == 3
+
 
 # ---------------------------------------------------------------------------
 # Feature-vector clustering tests: RegularSpace