MAINT: SPEC-007 optimize.check_grad

Author: andyfaff

scipy/optimize/_optimize.py

@@ -39,7 +39,7 @@
 from ._numdiff import approx_derivative
 from scipy._lib._util import getfullargspec_no_self as _getfullargspec
 from scipy._lib._util import (MapWrapper, check_random_state, _RichResult,
-                              _call_callback_maybe_halt)
+                              _call_callback_maybe_halt, _transition_to_rng)
 from scipy.optimize._differentiable_functions import ScalarFunction, FD_METHODS
 from scipy._lib._array_api import (array_namespace, xp_atleast_nd,
                                    xp_create_diagonal)
@@ -1031,9 +1031,10 @@ def approx_fprime(xk, f, epsilon=_epsilon, *args):
                              args=args, f0=f0)
 
 
+@_transition_to_rng("seed", position_num=6, replace_doc=False)
 def check_grad(func, grad, x0, *args, epsilon=_epsilon,
-                direction='all', seed=None):
-    """Check the correctness of a gradient function by comparing it against a
+                direction='all', rng=None):
+    r"""Check the correctness of a gradient function by comparing it against a
     (forward) finite-difference approximation of the gradient.
 
     Parameters
@@ -1056,14 +1057,31 @@ def check_grad(func, grad, x0, *args, epsilon=_epsilon,
         using `func`. By default it is ``'all'``, in which case, all
         the one hot direction vectors are considered to check `grad`.
         If `func` is a vector valued function then only ``'all'`` can be used.
-    seed : {None, int, `numpy.random.Generator`, `numpy.random.RandomState`}, optional
-        If `seed` is None (or `np.random`), the `numpy.random.RandomState`
-        singleton is used.
-        If `seed` is an int, a new ``RandomState`` instance is used,
-        seeded with `seed`.
-        If `seed` is already a ``Generator`` or ``RandomState`` instance then
-        that instance is used.
-        Specify `seed` for reproducing the return value from this function.
+    rng : {None, int, `numpy.random.Generator`, `numpy.random.RandomState`}, optional
+        If `rng` is passed by keyword, types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
+        If `rng` is already a ``Generator`` instance, then the provided instance is
+        used. Specify `rng` for repeatable function behavior.
+
+        If this argument is passed by position or `seed` is passed by keyword,
+        legacy behavior for the argument `seed` applies:
+
+        - If `seed` is None (or `numpy.random`), the `numpy.random.RandomState`
+          singleton is used.
+        - If `seed` is an int, a new ``RandomState`` instance is used,
+          seeded with `seed`.
+        - If `seed` is already a ``Generator`` or ``RandomState`` instance then
+          that instance is used.
+
+        .. versionchanged:: 1.15.0
+            As part of the `SPEC-007 <https://scientific-python.org/specs/spec-0007/>`_
+            transition from use of `numpy.random.RandomState` to
+            `numpy.random.Generator`, this keyword was changed from `seed` to `rng`.
+            For an interim period, both keywords will continue to work, although only one
+            may be specified at a time. After the interim period, function calls using the
+            `seed` keyword will emit warnings. The behavior of both `seed` and
+            `rng` are outlined above, but only the `rng` keyword should be used in new code.
+
         The random numbers generated with this seed affect the random vector
         along which gradients are computed to check ``grad``. Note that `seed`
         is only used when `direction` argument is set to `'random'`.
@@ -1106,8 +1124,8 @@ def g(w, func, x0, v, *args):
         if _grad.ndim > 1:
             raise ValueError("'random' can only be used with scalar valued"
                              " func")
-        random_state = check_random_state(seed)
-        v = random_state.normal(0, 1, size=(x0.shape))
+        rng_gen = check_random_state(rng)
+        v = rng_gen.standard_normal(size=(x0.shape))
         _args = (func, x0, v) + args
         _func = g
         vars = np.zeros((1,))

scipy/optimize/tests/test_optimize.py

@@ -52,21 +52,22 @@ def der_expit(x):
 
     r = optimize.check_grad(expit, der_expit, x0)
     assert_almost_equal(r, 0)
+    # SPEC-007 leave one call with seed to check it still works
     r = optimize.check_grad(expit, der_expit, x0,
                             direction='random', seed=1234)
     assert_almost_equal(r, 0)
 
     r = optimize.check_grad(expit, der_expit, x0, epsilon=1e-6)
     assert_almost_equal(r, 0)
     r = optimize.check_grad(expit, der_expit, x0, epsilon=1e-6,
-                            direction='random', seed=1234)
+                            direction='random', rng=1234)
     assert_almost_equal(r, 0)
 
     # Check if the epsilon parameter is being considered.
     r = abs(optimize.check_grad(expit, der_expit, x0, epsilon=1e-1) - 0)
     assert r > 1e-7
     r = abs(optimize.check_grad(expit, der_expit, x0, epsilon=1e-1,
-                                direction='random', seed=1234) - 0)
+                                direction='random', rng=1234) - 0)
     assert r > 1e-7
 
     def x_sinx(x):
@@ -78,16 +79,16 @@ def der_x_sinx(x):
     x0 = np.arange(0, 2, 0.2)
 
     r = optimize.check_grad(x_sinx, der_x_sinx, x0,
-                            direction='random', seed=1234)
+                            direction='random', rng=1234)
     assert_almost_equal(r, 0)
 
     assert_raises(ValueError, optimize.check_grad,
                   x_sinx, der_x_sinx, x0,
-                  direction='random_projection', seed=1234)
+                  direction='random_projection', rng=1234)
 
     # checking can be done for derivatives of vector valued functions
     r = optimize.check_grad(himmelblau_grad, himmelblau_hess, himmelblau_x0,
-                            direction='all', seed=1234)
+                            direction='all', rng=1234)
     assert r < 5e-7