statgpu 0.1.0__py3-none-any.whl

statgpu/unsupervised/_truncated_svd.py

@@ -0,0 +1,132 @@
+"""Truncated singular value decomposition."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import numpy as np
+
+from statgpu._base import BaseEstimator
+from statgpu._config import Device
+from statgpu.unsupervised._utils import check_2d_array, randomized_svd, reject_sparse, scalar_to_float
+
+
+class TruncatedSVD(BaseEstimator):
+    """
+    Dense truncated SVD with NumPy, CuPy, or Torch backends.
+
+    Unlike PCA, this estimator does not center the input matrix.
+    """
+
+    def __init__(
+        self,
+        n_components: int = 2,
+        algorithm: str = "randomized",
+        n_iter: int = 5,
+        n_oversamples: int = 10,
+        random_state: Optional[int] = None,
+        device: Union[str, Device] = Device.AUTO,
+        n_jobs: Optional[int] = None,
+    ):
+        super().__init__(device=device, n_jobs=n_jobs)
+        self.n_components = n_components
+        self.algorithm = algorithm
+        self.n_iter = n_iter
+        self.n_oversamples = n_oversamples
+        self.random_state = random_state
+
+    def _validate_params(self, n_samples: int, n_features: int):
+        if not isinstance(self.n_components, (int, np.integer)):
+            raise ValueError("n_components must be a positive integer")
+        n_components = int(self.n_components)
+        max_components = min(n_samples, n_features)
+        if n_components < 1 or n_components > max_components:
+            raise ValueError(f"n_components must be in [1, {max_components}] for the input shape")
+        if self.algorithm not in ("randomized", "full"):
+            raise ValueError("algorithm must be one of: 'randomized', 'full'")
+        if not isinstance(self.n_iter, (int, np.integer)) or int(self.n_iter) < 0:
+            raise ValueError("n_iter must be a non-negative integer")
+        if not isinstance(self.n_oversamples, (int, np.integer)) or int(self.n_oversamples) < 0:
+            raise ValueError("n_oversamples must be a non-negative integer")
+        return n_components
+
+    def fit(self, X, y=None):
+        reject_sparse(X, "TruncatedSVD")
+        backend = self._get_backend()
+        X_arr = backend.asarray(X, dtype=backend.float64)
+        check_2d_array(X_arr)
+        n_samples, n_features = X_arr.shape
+        n_components = self._validate_params(n_samples, n_features)
+
+        if self.algorithm == "full":
+            _, singular_values_all, vh = backend.svd(X_arr, full_matrices=False)
+            singular_values = singular_values_all[:n_components]
+            components = vh[:n_components]
+        else:
+            singular_values, components = randomized_svd(
+                backend,
+                X_arr,
+                n_components=n_components,
+                n_oversamples=int(self.n_oversamples),
+                n_iter=int(self.n_iter),
+                random_state=self.random_state,
+            )
+
+        transformed = backend.matmul(X_arr, components.T)
+        transformed_mean = backend.mean(transformed, axis=0, keepdims=True)
+        explained_variance = backend.mean((transformed - transformed_mean) ** 2, axis=0)
+        feature_mean = backend.mean(X_arr, axis=0, keepdims=True)
+        total_variance = backend.sum(backend.mean((X_arr - feature_mean) ** 2, axis=0))
+        if scalar_to_float(total_variance) > 0.0:
+            explained_variance_ratio = explained_variance / total_variance
+        else:
+            explained_variance_ratio = explained_variance * 0.0
+
+        self.components_ = components
+        self.explained_variance_ = explained_variance
+        self.explained_variance_ratio_ = explained_variance_ratio
+        self.singular_values_ = singular_values
+        self.n_components_ = int(n_components)
+        self.n_features_in_ = int(n_features)
+        self._backend_name = backend.name
+        self._fitted = True
+        return self
+
+    def transform(self, X):
+        self._check_is_fitted()
+        reject_sparse(X, "TruncatedSVD")
+        backend = self._get_backend()
+        X_arr = backend.asarray(X, dtype=backend.float64)
+        check_2d_array(X_arr)
+        if X_arr.shape[1] != self.n_features_in_:
+            raise ValueError(f"X has {X_arr.shape[1]} features, expected {self.n_features_in_}")
+        return backend.matmul(X_arr, self.components_.T)
+
+    def fit_transform(self, X, y=None):
+        return self.fit(X, y=y).transform(X)
+
+    def inverse_transform(self, X):
+        self._check_is_fitted()
+        backend = self._get_backend()
+        X_arr = backend.asarray(X, dtype=backend.float64)
+        check_2d_array(X_arr)
+        if X_arr.shape[1] != self.n_components_:
+            raise ValueError(f"X has {X_arr.shape[1]} components, expected {self.n_components_}")
+        return backend.matmul(X_arr, self.components_)
+
+    def predict(self, X):
+        """Alias for transform, provided for BaseEstimator compatibility."""
+        return self.transform(X)
+
+    def get_params(self, deep=True):
+        params = super().get_params(deep=deep)
+        params.update(
+            {
+                "n_components": self.n_components,
+                "algorithm": self.algorithm,
+                "n_iter": self.n_iter,
+                "n_oversamples": self.n_oversamples,
+                "random_state": self.random_state,
+            }
+        )
+        return params

statgpu/unsupervised/_tsne.py

@@ -0,0 +1,192 @@
+"""Exact dense t-SNE."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import numpy as np
+
+from statgpu._base import BaseEstimator
+from statgpu._config import Device
+from statgpu.unsupervised._pca import PCA
+from statgpu.unsupervised._utils import (
+    backend_random_normal,
+    check_2d_array,
+    eye,
+    reject_sparse,
+    scalar_to_float,
+    squared_euclidean_distances,
+)
+
+
+class TSNE(BaseEstimator):
+    """Dense exact t-SNE with backend-native probability and gradient steps."""
+
+    def __init__(
+        self,
+        n_components: int = 2,
+        perplexity: float = 30.0,
+        early_exaggeration: float = 12.0,
+        learning_rate: Union[str, float] = "auto",
+        max_iter: int = 1000,
+        init: str = "pca",
+        random_state: Optional[int] = None,
+        metric: str = "euclidean",
+        device: Union[str, Device] = Device.AUTO,
+        n_jobs: Optional[int] = None,
+    ):
+        super().__init__(device=device, n_jobs=n_jobs)
+        self.n_components = n_components
+        self.perplexity = perplexity
+        self.early_exaggeration = early_exaggeration
+        self.learning_rate = learning_rate
+        self.max_iter = max_iter
+        self.init = init
+        self.random_state = random_state
+        self.metric = metric
+
+    def _validate_params(self, n_samples: int):
+        if self.metric != "euclidean":
+            raise NotImplementedError("TSNE v1 only supports metric='euclidean'")
+        if not isinstance(self.n_components, (int, np.integer)) or int(self.n_components) < 1:
+            raise ValueError("n_components must be a positive integer")
+        if int(self.n_components) >= n_samples:
+            raise ValueError("n_components must be less than n_samples")
+        if float(self.perplexity) <= 0.0 or float(self.perplexity) >= n_samples:
+            raise ValueError("perplexity must be in (0, n_samples)")
+        if float(self.early_exaggeration) <= 0.0:
+            raise ValueError("early_exaggeration must be positive")
+        if not isinstance(self.max_iter, (int, np.integer)) or int(self.max_iter) < 250:
+            raise ValueError("max_iter must be an integer >= 250")
+        if self.init not in ("pca", "random"):
+            raise ValueError("init must be one of: 'pca', 'random'")
+
+    def _joint_probabilities(self, backend, X):
+        n_samples = X.shape[0]
+        distances = squared_euclidean_distances(backend, X)
+        distances = distances * (1.0 - eye(backend, n_samples, dtype=backend.float64))
+        beta = backend.ones((n_samples, 1), dtype=backend.float64)
+        beta_min = backend.zeros((n_samples, 1), dtype=backend.float64)
+        beta_max = backend.full((n_samples, 1), np.inf, dtype=backend.float64)
+        target = float(np.log(self.perplexity))
+        off_diag = 1.0 - eye(backend, n_samples, dtype=backend.float64)
+
+        for _ in range(50):
+            P = backend.exp(-distances * beta) * off_diag
+            sumP = backend.maximum(backend.sum(P, axis=1, keepdims=True), 1e-300)
+            H = backend.log(sumP) + beta * backend.sum(distances * P, axis=1, keepdims=True) / sumP
+            too_high = H > target
+            beta_min = backend.where(too_high, beta, beta_min)
+            beta_max = backend.where(too_high, beta_max, beta)
+            doubled = beta * 2.0
+            halved = beta / 2.0
+            averaged_high = (beta + beta_max) / 2.0
+            averaged_low = (beta + beta_min) / 2.0
+            beta = backend.where(
+                too_high,
+                backend.where(beta_max == np.inf, doubled, averaged_high),
+                backend.where(beta_min == 0.0, halved, averaged_low),
+            )
+
+        P = backend.exp(-distances * beta) * off_diag
+        P = P / backend.maximum(backend.sum(P, axis=1, keepdims=True), 1e-300)
+        P = (P + P.T) / (2.0 * float(n_samples))
+        return backend.maximum(P, 1e-300)
+
+    def _initial_embedding(self, backend, X):
+        n_samples = X.shape[0]
+        if self.init == "random":
+            return backend_random_normal(backend, self.random_state, size=(n_samples, int(self.n_components)), scale=1e-4)
+        pca = PCA(
+            n_components=int(self.n_components),
+            svd_solver="auto",
+            random_state=self.random_state,
+            device=self.device,
+            n_jobs=self.n_jobs,
+        )
+        init = pca.fit_transform(X)
+        first = init[:, :1]
+        first_centered = first - backend.mean(first, axis=0, keepdims=True)
+        scale = backend.sqrt(backend.maximum(backend.mean(first_centered * first_centered), 1e-300))
+        return init / scale * 1e-4
+
+    def _learning_rate(self, n_samples: int) -> float:
+        if self.learning_rate == "auto":
+            return max(float(n_samples) / float(self.early_exaggeration) / 4.0, 10.0)
+        lr = float(self.learning_rate)
+        if lr <= 0.0:
+            raise ValueError("learning_rate must be 'auto' or a positive number")
+        return lr
+
+    def fit(self, X, y=None):
+        reject_sparse(X, "TSNE")
+        backend = self._get_backend()
+        X_arr = backend.asarray(X, dtype=backend.float64)
+        check_2d_array(X_arr)
+        n_samples, n_features = X_arr.shape
+        self._validate_params(n_samples)
+
+        P = self._joint_probabilities(backend, X_arr)
+        Y = self._initial_embedding(backend, X_arr)
+        lr = self._learning_rate(n_samples)
+        momentum = 0.5
+        velocity = backend.zeros_like(Y)
+        gains = backend.ones_like(Y)
+        off_diag = 1.0 - eye(backend, n_samples, dtype=backend.float64)
+        exaggeration_iters = min(250, int(self.max_iter) // 2)
+
+        kl = None
+        for it in range(int(self.max_iter)):
+            P_use = P * float(self.early_exaggeration) if it < exaggeration_iters else P
+            dist_sq = squared_euclidean_distances(backend, Y)
+            inv = (1.0 / (1.0 + dist_sq)) * off_diag
+            Q = inv / backend.maximum(backend.sum(inv), 1e-300)
+            forces = (P_use - Q) * inv
+            row_force = backend.sum(forces, axis=1, keepdims=True)
+            grad = 4.0 * (row_force * Y - backend.matmul(forces, Y))
+            sign_changed = (grad * velocity) < 0.0
+            gains = backend.where(sign_changed, gains + 0.2, gains * 0.8)
+            gains = backend.maximum(gains, 0.01)
+            velocity = momentum * velocity - lr * gains * grad
+            Y = Y + velocity
+            Y = Y - backend.mean(Y, axis=0, keepdims=True)
+            if it == exaggeration_iters:
+                momentum = 0.8
+
+        dist_sq = squared_euclidean_distances(backend, Y)
+        inv = (1.0 / (1.0 + dist_sq)) * off_diag
+        Q = backend.maximum(inv / backend.maximum(backend.sum(inv), 1e-300), 1e-300)
+        kl = backend.sum(P * (backend.log(P) - backend.log(Q)))
+
+        self.embedding_ = Y
+        self.kl_divergence_ = scalar_to_float(kl)
+        self.n_iter_ = int(self.max_iter)
+        self.n_features_in_ = int(n_features)
+        self._backend_name = backend.name
+        self._fitted = True
+        return self
+
+    def fit_transform(self, X, y=None):
+        return self.fit(X, y=y).embedding_
+
+    def transform(self, X):
+        raise NotImplementedError("TSNE v1 does not support transforming new data")
+
+    def predict(self, X):
+        raise NotImplementedError("TSNE v1 does not support prediction")
+
+    def get_params(self, deep=True):
+        params = super().get_params(deep=deep)
+        params.update(
+            {
+                "n_components": self.n_components,
+                "perplexity": self.perplexity,
+                "early_exaggeration": self.early_exaggeration,
+                "learning_rate": self.learning_rate,
+                "max_iter": self.max_iter,
+                "init": self.init,
+                "random_state": self.random_state,
+                "metric": self.metric,
+            }
+        )
+        return params

statgpu/unsupervised/_umap.py

@@ -0,0 +1,224 @@
+"""Dense exact UMAP."""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import numpy as np
+
+from statgpu._base import BaseEstimator
+from statgpu._config import Device
+from statgpu.unsupervised._utils import (
+    backend_random_normal,
+    check_2d_array,
+    eye,
+    reject_sparse,
+    squared_euclidean_distances,
+    topk_smallest,
+)
+
+
+class UMAP(BaseEstimator):
+    """
+    Dense exact UMAP with NumPy, CuPy, or Torch backends.
+
+    Version 1 builds an exact dense Euclidean neighbor graph and does not
+    implement approximate NNDescent or transforming new data.
+    """
+
+    def __init__(
+        self,
+        n_neighbors: int = 15,
+        n_components: int = 2,
+        metric: str = "euclidean",
+        min_dist: float = 0.1,
+        spread: float = 1.0,
+        n_epochs: Optional[int] = None,
+        learning_rate: float = 1.0,
+        init: str = "spectral",
+        negative_sample_rate: int = 5,
+        repulsion_strength: float = 1.0,
+        random_state: Optional[int] = None,
+        device: Union[str, Device] = Device.AUTO,
+        n_jobs: Optional[int] = None,
+    ):
+        super().__init__(device=device, n_jobs=n_jobs)
+        self.n_neighbors = n_neighbors
+        self.n_components = n_components
+        self.metric = metric
+        self.min_dist = min_dist
+        self.spread = spread
+        self.n_epochs = n_epochs
+        self.learning_rate = learning_rate
+        self.init = init
+        self.negative_sample_rate = negative_sample_rate
+        self.repulsion_strength = repulsion_strength
+        self.random_state = random_state
+
+    def _validate_params(self, n_samples: int):
+        if self.metric != "euclidean":
+            raise NotImplementedError("UMAP v1 only supports metric='euclidean'")
+        if not isinstance(self.n_neighbors, (int, np.integer)) or int(self.n_neighbors) < 2:
+            raise ValueError("n_neighbors must be an integer >= 2")
+        if int(self.n_neighbors) >= n_samples:
+            raise ValueError("n_neighbors must be less than n_samples")
+        if not isinstance(self.n_components, (int, np.integer)) or int(self.n_components) < 1:
+            raise ValueError("n_components must be a positive integer")
+        if int(self.n_components) >= n_samples:
+            raise ValueError("n_components must be less than n_samples")
+        if float(self.min_dist) < 0.0:
+            raise ValueError("min_dist must be non-negative")
+        if float(self.spread) <= 0.0:
+            raise ValueError("spread must be positive")
+        if self.init not in ("spectral", "random"):
+            raise ValueError("init must be one of: 'spectral', 'random'")
+        if self.n_epochs is not None:
+            if not isinstance(self.n_epochs, (int, np.integer)) or int(self.n_epochs) < 1:
+                raise ValueError("n_epochs must be None or a positive integer")
+        if float(self.learning_rate) <= 0.0:
+            raise ValueError("learning_rate must be positive")
+        if not isinstance(self.negative_sample_rate, (int, np.integer)) or int(self.negative_sample_rate) < 1:
+            raise ValueError("negative_sample_rate must be a positive integer")
+        if float(self.repulsion_strength) <= 0.0:
+            raise ValueError("repulsion_strength must be positive")
+
+    def _smooth_knn_membership(self, backend, neighbor_distances):
+        rho = neighbor_distances[:, :1]
+        adjusted = backend.maximum(neighbor_distances - rho, 0.0)
+        sigma = backend.maximum(backend.mean(adjusted, axis=1, keepdims=True), 1e-12)
+        membership = backend.exp(-adjusted / sigma)
+        membership[:, 0] = 1.0
+        return membership
+
+    def _fuzzy_graph(self, backend, X):
+        n_samples = X.shape[0]
+        distances = backend.sqrt(squared_euclidean_distances(backend, X))
+        distances = distances + eye(backend, n_samples, dtype=backend.float64) * 1e12
+        neighbor_distances, neighbor_indices = topk_smallest(backend, distances, int(self.n_neighbors))
+        membership = self._smooth_knn_membership(backend, neighbor_distances)
+        graph = backend.zeros((n_samples, n_samples), dtype=backend.float64)
+        rows = backend.reshape(backend.arange(n_samples, dtype=backend.int64), (n_samples, 1))
+        graph[rows, backend.astype(neighbor_indices, backend.int64)] = membership
+        graph = graph + graph.T - graph * graph.T
+        graph = graph * (1.0 - eye(backend, n_samples, dtype=backend.float64))
+        return graph
+
+    def _initial_embedding(self, backend, graph):
+        n_samples = graph.shape[0]
+        if self.init == "random":
+            return backend_random_normal(backend, self.random_state, size=(n_samples, int(self.n_components)), scale=1e-4)
+
+        degree = backend.sum(graph, axis=1)
+        laplacian = backend.diag(degree) - graph
+        eigenvalues, eigenvectors = backend.eigh(laplacian)
+        order = backend.argsort(eigenvalues, axis=0)
+        components = eigenvectors[:, order[1 : int(self.n_components) + 1]]
+        jitter = backend_random_normal(backend, self.random_state, size=(n_samples, int(self.n_components)), scale=1e-4)
+        return components + jitter
+
+    def _epochs(self, n_samples: int) -> int:
+        if self.n_epochs is not None:
+            return int(self.n_epochs)
+        return 500 if n_samples <= 10_000 else 200
+
+    def _attraction_curve_params(self):
+        """
+        Fit UMAP's (a, b) curve parameters from min_dist and spread.
+
+        This mirrors the reference approach used by umap-learn:
+        target(d) = 1                      if d <= min_dist
+                    exp(-(d-min_dist)/spread) otherwise
+        and we fit 1 / (1 + a * d^(2b)) to that target.
+        """
+        min_dist = float(self.min_dist)
+        spread = float(self.spread)
+        xv = np.linspace(0.0, spread * 3.0, 300, dtype=np.float64)
+        yv = np.where(xv <= min_dist, 1.0, np.exp(-(xv - min_dist) / max(spread, 1e-12)))
+
+        def curve(d, a, b):
+            return 1.0 / (1.0 + a * np.power(d, 2.0 * b))
+
+        try:
+            # Optional dependency: keep UMAP functional even when SciPy is absent.
+            from scipy.optimize import curve_fit
+
+            params, _ = curve_fit(
+                curve,
+                xv,
+                yv,
+                p0=(1.0, 1.0),
+                bounds=((1e-12, 1e-12), (1e6, 10.0)),
+                maxfev=20000,
+            )
+            a, b = float(params[0]), float(params[1])
+            if np.isfinite(a) and np.isfinite(b) and a > 0.0 and b > 0.0:
+                return a, b
+        except Exception:
+            pass
+
+        # Conservative fallback to ensure training can proceed.
+        return 1.0, 1.0 / max(spread, 1e-12)
+
+    def fit(self, X, y=None):
+        reject_sparse(X, "UMAP")
+        backend = self._get_backend()
+        X_arr = backend.asarray(X, dtype=backend.float64)
+        check_2d_array(X_arr)
+        n_samples, n_features = X_arr.shape
+        self._validate_params(n_samples)
+
+        graph = self._fuzzy_graph(backend, X_arr)
+        Y = self._initial_embedding(backend, graph)
+        n_epochs = self._epochs(n_samples)
+        a, b = self._attraction_curve_params()
+        off_diag = 1.0 - eye(backend, n_samples, dtype=backend.float64)
+        graph = backend.clip(graph, 0.0, 1.0)
+        repulsion = float(self.repulsion_strength) / float(self.negative_sample_rate)
+
+        for epoch in range(n_epochs):
+            alpha = float(self.learning_rate) * (1.0 - (epoch / max(n_epochs, 1)))
+            diff = backend.expand_dims(Y, 1) - backend.expand_dims(Y, 0)
+            dist_sq = backend.sum(diff * diff, axis=2)
+            inv = (1.0 / (1.0 + float(a) * (dist_sq ** float(b)))) * off_diag
+            attractive = graph
+            repulsive = (1.0 - graph) * inv * repulsion
+            forces = (attractive - repulsive) * inv
+            grad = 2.0 * backend.sum(backend.expand_dims(forces, 2) * diff, axis=1)
+            Y = Y - alpha * grad
+            Y = Y - backend.mean(Y, axis=0, keepdims=True)
+
+        self.embedding_ = Y
+        self.graph_ = graph
+        self.n_epochs_ = int(n_epochs)
+        self.n_features_in_ = int(n_features)
+        self._backend_name = backend.name
+        self._fitted = True
+        return self
+
+    def fit_transform(self, X, y=None):
+        return self.fit(X, y=y).embedding_
+
+    def transform(self, X):
+        raise NotImplementedError("UMAP v1 does not support transforming new data")
+
+    def predict(self, X):
+        raise NotImplementedError("UMAP v1 does not support prediction")
+
+    def get_params(self, deep=True):
+        params = super().get_params(deep=deep)
+        params.update(
+            {
+                "n_neighbors": self.n_neighbors,
+                "n_components": self.n_components,
+                "metric": self.metric,
+                "min_dist": self.min_dist,
+                "spread": self.spread,
+                "n_epochs": self.n_epochs,
+                "learning_rate": self.learning_rate,
+                "init": self.init,
+                "negative_sample_rate": self.negative_sample_rate,
+                "repulsion_strength": self.repulsion_strength,
+                "random_state": self.random_state,
+            }
+        )
+        return params

statgpu/unsupervised/_utils.py

@@ -0,0 +1,134 @@
+"""Shared utilities for unsupervised estimators."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import sparse
+
+
+def check_2d_array(X, name: str = "X") -> None:
+    """Validate that *X* is a non-empty 2D array-like object."""
+    if getattr(X, "ndim", None) != 2:
+        raise ValueError(f"{name} must be a 2D array")
+    if X.shape[0] < 1 or X.shape[1] < 1:
+        raise ValueError(f"{name} must contain at least one sample and one feature")
+
+
+def reject_sparse(X, estimator_name: str) -> None:
+    """Raise a consistent error for unsupported sparse inputs."""
+    if sparse.issparse(X):
+        raise NotImplementedError(f"sparse input is not supported in {estimator_name} v1")
+
+
+def scalar_to_float(x) -> float:
+    """Convert a NumPy/CuPy/Torch scalar to Python float."""
+    if hasattr(x, "detach"):
+        return float(x.detach().cpu().item())
+    if hasattr(x, "get"):
+        return float(x.get())
+    if hasattr(x, "item"):
+        return float(x.item())
+    return float(x)
+
+
+def scalar_to_int(x) -> int:
+    """Convert a NumPy/CuPy/Torch scalar to Python int."""
+    if hasattr(x, "detach"):
+        return int(x.detach().cpu().item())
+    if hasattr(x, "get"):
+        return int(x.get())
+    if hasattr(x, "item"):
+        return int(x.item())
+    return int(x)
+
+
+def draw_random_seed(random_state) -> int:
+    """Draw an integer seed from int/None/RandomState/Generator inputs."""
+    if random_state is None:
+        return int(np.random.SeedSequence().generate_state(1, dtype=np.uint64)[0])
+    if isinstance(random_state, np.random.Generator):
+        return int(random_state.integers(0, np.iinfo(np.int32).max))
+    if isinstance(random_state, np.random.RandomState):
+        return int(random_state.randint(0, np.iinfo(np.int32).max))
+    return int(random_state)
+
+
+def backend_random_normal(backend, random_state, size, scale: float = 1.0):
+    """Generate deterministic normal variates directly on the target backend.
+
+    This avoids allocating a NumPy random matrix and then transferring it to a
+    GPU backend.  The lightweight Box-Muller generator is used only for
+    estimator initialization and randomized projections, where deterministic
+    seeded behavior is more important than cryptographic-quality randomness.
+    """
+    total = int(np.prod(size))
+    seed = draw_random_seed(random_state)
+    idx = backend.arange(total, dtype=backend.float64)
+    xp = backend.xp
+
+    def uniform(offset):
+        values = xp.sin((idx + 1.0 + float(offset)) * (12.9898 + 0.001 * float(seed))) * 43758.5453
+        return values - xp.floor(values)
+
+    u1 = backend.maximum(uniform(0), 1e-12)
+    u2 = uniform(total + 17)
+    z = backend.sqrt(-2.0 * backend.log(u1)) * xp.cos(2.0 * np.pi * u2)
+    return backend.reshape(z * float(scale), size)
+
+
+def squared_euclidean_distances(backend, X, Y=None):
+    """Compute dense squared Euclidean distances with backend arrays."""
+    Y = X if Y is None else Y
+    x_norm = backend.sum(X * X, axis=1, keepdims=True)
+    y_norm = backend.sum(Y * Y, axis=1, keepdims=True)
+    distances = x_norm + y_norm.T - 2.0 * backend.matmul(X, Y.T)
+    return backend.maximum(distances, 0.0)
+
+
+def topk_smallest(backend, distances, k: int):
+    """Return the k smallest values and indices along axis 1."""
+    order = backend.argsort(distances, axis=1)
+    idx = order[:, :k]
+    values = backend.take_along_axis(distances, idx, axis=1)
+    return values, idx
+
+
+def svd_flip_components(backend, components):
+    """Apply a deterministic sign convention to right singular vectors."""
+    max_abs_cols = backend.argmax(backend.abs(components), axis=1)
+    rows = backend.arange(components.shape[0])
+    signs = backend.where(components[rows, max_abs_cols] < 0.0, -1.0, 1.0)
+    return components * backend.reshape(signs, (components.shape[0], 1))
+
+
+def randomized_svd(
+    backend,
+    X,
+    n_components: int,
+    n_oversamples: int = 10,
+    n_iter: int = 2,
+    random_state=None,
+):
+    """Backend randomized SVD for dense matrices."""
+    n_samples, n_features = X.shape
+    n_random = min(min(n_samples, n_features), int(n_components) + int(n_oversamples))
+    omega = backend_random_normal(backend, random_state, size=(n_features, n_random))
+
+    # Re-orthogonalize each power iteration. This is slightly more work than
+    # the raw power method, but greatly improves randomized SVD stability when
+    # singular values are close or the matrix is moderately ill-conditioned.
+    Q, _ = backend.qr(backend.matmul(X, omega))
+    for _ in range(int(n_iter)):
+        Q, _ = backend.qr(backend.matmul(X.T, Q))
+        Q, _ = backend.qr(backend.matmul(X, Q))
+
+    B = backend.matmul(Q.T, X)
+    _, singular_values, vh = backend.svd(B, full_matrices=False)
+    return singular_values[:n_components], svd_flip_components(backend, vh[:n_components])
+
+
+def eye(backend, n: int, dtype=None):
+    """Create an identity matrix on the requested backend."""
+    if hasattr(backend, "eye"):
+        return backend.eye(n, dtype=dtype)
+    return backend.asarray(np.eye(n), dtype=dtype or backend.float64)