API: sparse.linalg.svds: transition to rng (SPEC 7) (scipy#21899)

* API: sparse.linalg.svds: transition to rng (SPEC 7)
* TST: sparse.linalg.svds: make tests deterministic

Author: dschult

scipy/sparse/linalg/_eigen/_svds.py

@@ -4,7 +4,7 @@
 from .arpack import _arpack  # type: ignore[attr-defined]
 from . import eigsh
 
-from scipy._lib._util import check_random_state
+from scipy._lib._util import check_random_state, _transition_to_rng
 from scipy.sparse.linalg._interface import LinearOperator, aslinearoperator
 from scipy.sparse.linalg._eigen.lobpcg import lobpcg  # type: ignore[no-redef]
 from scipy.sparse.linalg._svdp import _svdp
@@ -19,7 +19,7 @@ def _herm(x):
 
 
 def _iv(A, k, ncv, tol, which, v0, maxiter,
-        return_singular, solver, random_state):
+        return_singular, solver, rng):
 
     # input validation/standardization for `solver`
     # out of order because it's needed for other parameters
@@ -90,15 +90,16 @@ def _iv(A, k, ncv, tol, which, v0, maxiter,
     if return_singular not in rs_options:
         raise ValueError(f"`return_singular_vectors` must be in {rs_options}.")
 
-    random_state = check_random_state(random_state)
+    rng = check_random_state(rng)
 
     return (A, k, ncv, tol, which, v0, maxiter,
-            return_singular, solver, random_state)
+            return_singular, solver, rng)
 
 
+@_transition_to_rng("random_state", position_num=9)
 def svds(A, k=6, ncv=None, tol=0, which='LM', v0=None,
          maxiter=None, return_singular_vectors=True,
-         solver='arpack', random_state=None, options=None):
+         solver='arpack', rng=None, options=None):
     """
     Partial singular value decomposition of a sparse matrix.
 
@@ -158,17 +159,11 @@ def svds(A, k=6, ncv=None, tol=0, which='LM', v0=None,
             :ref:`'lobpcg' <sparse.linalg.svds-lobpcg>`, and
             :ref:`'propack' <sparse.linalg.svds-propack>` are supported.
             Default: `'arpack'`.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
-
-        If `random_state` is ``None`` (or `np.random`), the
-        `numpy.random.RandomState` singleton is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance then that instance is used.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator state. When `rng` is None, a new
+        `numpy.random.Generator` is created using entropy from the
+        operating system. Types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
     options : dict, optional
         A dictionary of solver-specific options. No solver-specific options
         are currently supported; this parameter is reserved for future use.
@@ -263,7 +258,7 @@ def svds(A, k=6, ncv=None, tol=0, which='LM', v0=None,
     >>> vT = v.T
     >>> A = u @ np.diag(s) @ vT
     >>> A = A.astype(np.float32)
-    >>> u2, s2, vT2 = svds(A, k=2, random_state=rng)
+    >>> u2, s2, vT2 = svds(A, k=2, rng=rng)
     >>> np.allclose(s2, s)
     True
 
@@ -290,21 +285,21 @@ def svds(A, k=6, ncv=None, tol=0, which='LM', v0=None,
 
     The next example follows that of 'sklearn.decomposition.TruncatedSVD'.
 
-    >>> rng = np.random.RandomState(0)
+    >>> rng = np.random.default_rng(0)
     >>> X_dense = rng.random(size=(100, 100))
     >>> X_dense[:, 2 * np.arange(50)] = 0
     >>> X = sparse.csr_array(X_dense)
-    >>> _, singular_values, _ = svds(X, k=5, random_state=rng)
+    >>> _, singular_values, _ = svds(X, k=5, rng=rng)
     >>> print(singular_values)
-    [ 4.3293...  4.4491...  4.5420...  4.5987... 35.2410...]
+    [ 4.3221...  4.4043...  4.4907...  4.5858... 35.4549...]
 
     The function can be called without the transpose of the input matrix
     ever explicitly constructed.
 
     >>> rng = np.random.default_rng(102524723947864966825913730119128190974)
     >>> G = sparse.random_array((8, 9), density=0.5, random_state=rng)
     >>> Glo = aslinearoperator(G)
-    >>> _, singular_values_svds, _ = svds(Glo, k=5, random_state=rng)
+    >>> _, singular_values_svds, _ = svds(Glo, k=5, rng=rng)
     >>> _, singular_values_svd, _ = linalg.svd(G.toarray())
     >>> np.allclose(singular_values_svds, singular_values_svd[-4::-1])
     True
@@ -436,9 +431,9 @@ def svds(A, k=6, ncv=None, tol=0, which='LM', v0=None,
 
     """
     args = _iv(A, k, ncv, tol, which, v0, maxiter, return_singular_vectors,
-               solver, random_state)
+               solver, rng)
     (A, k, ncv, tol, which, v0, maxiter,
-     return_singular_vectors, solver, random_state) = args
+     return_singular_vectors, solver, rng) = args
 
     largest = (which == 'LM')
     n, m = A.shape
@@ -477,7 +472,7 @@ def matmat_XH_X(x):
         if k == 1 and v0 is not None:
             X = np.reshape(v0, (-1, 1))
         else:
-            X = random_state.standard_normal(size=(min(A.shape), k))
+            X = rng.standard_normal(size=(min(A.shape), k))
 
         _, eigvec = lobpcg(XH_X, X, tol=tol ** 2, maxiter=maxiter,
                            largest=largest)
@@ -488,7 +483,7 @@ def matmat_XH_X(x):
         irl_mode = (which == 'SM')
         res = _svdp(A, k=k, tol=tol**2, which=which, maxiter=None,
                     compute_u=jobu, compute_v=jobv, irl_mode=irl_mode,
-                    kmax=maxiter, v0=v0, random_state=random_state)
+                    kmax=maxiter, v0=v0, rng=rng)
 
         u, s, vh, _ = res  # but we'll ignore bnd, the last output
 
@@ -510,7 +505,7 @@ def matmat_XH_X(x):
 
     elif solver == 'arpack' or solver is None:
         if v0 is None:
-            v0 = random_state.standard_normal(size=(min(A.shape),))
+            v0 = rng.standard_normal(size=(min(A.shape),))
         _, eigvec = eigsh(XH_X, k=k, tol=tol ** 2, maxiter=maxiter,
                           ncv=ncv, which=which, v0=v0)
         # arpack do not guarantee exactly orthonormal eigenvectors

scipy/sparse/linalg/_eigen/_svds_doc.py

@@ -1,6 +1,6 @@
 def _svds_arpack_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
                      maxiter=None, return_singular_vectors=True,
-                     solver='arpack', random_state=None):
+                     solver='arpack', rng=None):
     """
     Partial singular value decomposition of a sparse matrix using ARPACK.
 
@@ -54,17 +54,11 @@ def _svds_arpack_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
             :ref:`'lobpcg' <sparse.linalg.svds-lobpcg>` and
             :ref:`'propack' <sparse.linalg.svds-propack>`
             are also supported.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
-
-        If `random_state` is ``None`` (or `np.random`), the
-        `numpy.random.RandomState` singleton is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance then that instance is used.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator state. When `rng` is None, a new
+        `numpy.random.Generator` is created using entropy from the
+        operating system. Types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
     options : dict, optional
         A dictionary of solver-specific options. No solver-specific options
         are currently supported; this parameter is reserved for future use.
@@ -134,7 +128,7 @@ def _svds_arpack_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
 
 def _svds_lobpcg_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
                      maxiter=None, return_singular_vectors=True,
-                     solver='lobpcg', random_state=None):
+                     solver='lobpcg', rng=None):
     """
     Partial singular value decomposition of a sparse matrix using LOBPCG.
 
@@ -184,17 +178,11 @@ def _svds_lobpcg_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
             :ref:`'arpack' <sparse.linalg.svds-arpack>` and
             :ref:`'propack' <sparse.linalg.svds-propack>`
             are also supported.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
-
-        If `random_state` is ``None`` (or `np.random`), the
-        `numpy.random.RandomState` singleton is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance then that instance is used.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator state. When `rng` is None, a new
+        `numpy.random.Generator` is created using entropy from the
+        operating system. Types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
     options : dict, optional
         A dictionary of solver-specific options. No solver-specific options
         are currently supported; this parameter is reserved for future use.
@@ -265,7 +253,7 @@ def _svds_lobpcg_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
 
 def _svds_propack_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
                       maxiter=None, return_singular_vectors=True,
-                      solver='propack', random_state=None):
+                      solver='propack', rng=None):
     """
     Partial singular value decomposition of a sparse matrix using PROPACK.
 
@@ -314,17 +302,11 @@ def _svds_propack_doc(A, k=6, ncv=None, tol=0, which='LM', v0=None,
             :ref:`'arpack' <sparse.linalg.svds-arpack>` and
             :ref:`'lobpcg' <sparse.linalg.svds-lobpcg>`
             are also supported.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
-
-        If `random_state` is ``None`` (or `np.random`), the
-        `numpy.random.RandomState` singleton is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance then that instance is used.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator state. When `rng` is None, a new
+        `numpy.random.Generator` is created using entropy from the
+        operating system. Types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
     options : dict, optional
         A dictionary of solver-specific options. No solver-specific options
         are currently supported; this parameter is reserved for future use.