API: optimize.dual_annealing: adopt SPEC007 (scipy#21823)

andyfaff · mdhaber · web-flow · commit e5a07270e445 · 2024-11-08T07:51:39.000-06:00
---------

Co-authored-by: Matt Haberland &lt;mhaberla@calpoly.edu&gt;
diff --git a/scipy/_lib/tests/test__util.py b/scipy/_lib/tests/test__util.py
@@ -17,7 +17,8 @@
 from scipy._lib._util import (_aligned_zeros, check_random_state, MapWrapper,
                               getfullargspec_no_self, FullArgSpec,
                               rng_integers, _validate_int, _rename_parameter,
-                              _contains_nan, _rng_html_rewrite, _lazywhere)
+                              _contains_nan, _rng_html_rewrite, _lazywhere,
+                              _transition_to_rng)
 
 skip_xp_backends = pytest.mark.skip_xp_backends
 
@@ -388,6 +389,26 @@ def mock_str():
     assert res == ref
 
 
+@_transition_to_rng("seed", position_num=1, replace_doc=False)
+def _f_seed(o, rng=None):
+    rg = check_random_state(rng)
+    return rg.uniform(size=o)
+
+
+def test__transition_to_rng():
+    # SPEC-007 changes
+    _f_seed(1, rng=1)
+    _f_seed(1, rng=np.random.default_rng())
+    _f_seed(1, seed=1)
+    _f_seed(1, seed=np.random.RandomState())
+    with assert_raises(TypeError):
+        # can't pass both seed and rng
+        _f_seed(1, seed=1234, rng=1234)
+    with assert_raises(TypeError):
+        # use of rng=RandomState should give rise to an error.
+        _f_seed(rng=np.random.RandomState())
+
+
 class TestLazywhere:
     n_arrays = strategies.integers(min_value=1, max_value=3)
     rng_seed = strategies.integers(min_value=1000000000, max_value=9999999999)
diff --git a/scipy/optimize/_dual_annealing.py b/scipy/optimize/_dual_annealing.py
@@ -11,7 +11,7 @@
 from scipy.optimize import OptimizeResult
 from scipy.optimize import minimize, Bounds
 from scipy.special import gammaln
-from scipy._lib._util import check_random_state
+from scipy._lib._util import check_random_state, _transition_to_rng
 from scipy.optimize._constraints import new_bounds_to_old
 
 __all__ = ['dual_annealing']
@@ -38,21 +38,22 @@ class VisitingDistribution:
         makes the algorithm jump to a more distant region.
         The value range is (1, 3]. Its value is fixed for the life of the
         object.
-    rand_gen : {`~numpy.random.RandomState`, `~numpy.random.Generator`}
-        A `~numpy.random.RandomState`, `~numpy.random.Generator` object
-        for using the current state of the created random generator container.
+    rng_gen : {`~numpy.random.Generator`}
+        A `~numpy.random.Generator` object for generating new locations.
+        (can be a `~numpy.random.RandomState` object until SPEC007 transition
+         is fully complete).
 
     """
     TAIL_LIMIT = 1.e8
     MIN_VISIT_BOUND = 1.e-10
 
-    def __init__(self, lb, ub, visiting_param, rand_gen):
+    def __init__(self, lb, ub, visiting_param, rng_gen):
         # if you wish to make _visiting_param adjustable during the life of
         # the object then _factor2, _factor3, _factor5, _d1, _factor6 will
         # have to be dynamically calculated in `visit_fn`. They're factored
         # out here so they don't need to be recalculated all the time.
         self._visiting_param = visiting_param
-        self.rand_gen = rand_gen
+        self.rng_gen = rng_gen
         self.lower = lb
         self.upper = ub
         self.bound_range = ub - lb
@@ -79,7 +80,7 @@ def visiting(self, x, step, temperature):
         if step < dim:
             # Changing all coordinates with a new visiting value
             visits = self.visit_fn(temperature, dim)
-            upper_sample, lower_sample = self.rand_gen.uniform(size=2)
+            upper_sample, lower_sample = self.rng_gen.uniform(size=2)
             visits[visits > self.TAIL_LIMIT] = self.TAIL_LIMIT * upper_sample
             visits[visits < -self.TAIL_LIMIT] = -self.TAIL_LIMIT * lower_sample
             x_visit = visits + x
@@ -94,9 +95,9 @@ def visiting(self, x, step, temperature):
             x_visit = np.copy(x)
             visit = self.visit_fn(temperature, 1)[0]
             if visit > self.TAIL_LIMIT:
-                visit = self.TAIL_LIMIT * self.rand_gen.uniform()
+                visit = self.TAIL_LIMIT * self.rng_gen.uniform()
             elif visit < -self.TAIL_LIMIT:
-                visit = -self.TAIL_LIMIT * self.rand_gen.uniform()
+                visit = -self.TAIL_LIMIT * self.rng_gen.uniform()
             index = step - dim
             x_visit[index] = visit + x[index]
             a = x_visit[index] - self.lower[index]
@@ -110,7 +111,7 @@ def visiting(self, x, step, temperature):
 
     def visit_fn(self, temperature, dim):
         """ Formula Visita from p. 405 of reference [2] """
-        x, y = self.rand_gen.normal(size=(dim, 2)).T
+        x, y = self.rng_gen.normal(size=(dim, 2)).T
 
         factor1 = np.exp(np.log(temperature) / (self._visiting_param - 1.0))
         factor4 = self._factor4_p * factor1
@@ -156,14 +157,14 @@ def __init__(self, lower, upper, callback=None):
         self.upper = upper
         self.callback = callback
 
-    def reset(self, func_wrapper, rand_gen, x0=None):
+    def reset(self, func_wrapper, rng_gen, x0=None):
         """
         Initialize current location is the search domain. If `x0` is not
         provided, a random location within the bounds is generated.
         """
         if x0 is None:
-            self.current_location = rand_gen.uniform(self.lower, self.upper,
-                                                     size=len(self.lower))
+            self.current_location = rng_gen.uniform(self.lower, self.upper,
+                                                    size=len(self.lower))
         else:
             self.current_location = np.copy(x0)
         init_error = True
@@ -181,9 +182,9 @@ def reset(self, func_wrapper, rand_gen, x0=None):
                         'trying new random parameters'
                     )
                     raise ValueError(message)
-                self.current_location = rand_gen.uniform(self.lower,
-                                                         self.upper,
-                                                         size=self.lower.size)
+                self.current_location = rng_gen.uniform(self.lower,
+                                                        self.upper,
+                                                        size=self.lower.size)
                 reinit_counter += 1
             else:
                 init_error = False
@@ -448,10 +449,11 @@ def local_search(self, x, e):
             return e, x_tmp
 
 
+@_transition_to_rng("seed", position_num=10)
 def dual_annealing(func, bounds, args=(), maxiter=1000,
                    minimizer_kwargs=None, initial_temp=5230.,
                    restart_temp_ratio=2.e-5, visit=2.62, accept=-5.0,
-                   maxfun=1e7, seed=None, no_local_search=False,
+                   maxfun=1e7, rng=None, no_local_search=False,
                    callback=None, x0=None):
     """
     Find the global minimum of a function using Dual Annealing.
@@ -507,15 +509,14 @@ def dual_annealing(func, bounds, args=(), maxiter=1000,
         algorithm is in the middle of a local search, this number will be
         exceeded, the algorithm will stop just after the local search is
         done. Default value is 1e7.
-    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 repeatable minimizations. The random numbers
-        generated with this seed only affect the visiting distribution function
+    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`.
+
+        Specify `rng` for repeatable minimizations. The random numbers
+        generated only affect the visiting distribution function
         and new coordinates generation.
     no_local_search : bool, optional
         If `no_local_search` is set to True, a traditional Generalized
@@ -666,19 +667,19 @@ def dual_annealing(func, bounds, args=(), maxiter=1000,
     minimizer_wrapper = LocalSearchWrapper(
         bounds, func_wrapper, *args, **minimizer_kwargs)
 
-    # Initialization of random Generator for reproducible runs if seed provided
-    rand_state = check_random_state(seed)
+    # Initialization of random Generator for reproducible runs if rng provided
+    rng_gen = check_random_state(rng)
     # Initialization of the energy state
     energy_state = EnergyState(lower, upper, callback)
-    energy_state.reset(func_wrapper, rand_state, x0)
+    energy_state.reset(func_wrapper, rng_gen, x0)
     # Minimum value of annealing temperature reached to perform
     # re-annealing
     temperature_restart = initial_temp * restart_temp_ratio
     # VisitingDistribution instance
-    visit_dist = VisitingDistribution(lower, upper, visit, rand_state)
+    visit_dist = VisitingDistribution(lower, upper, visit, rng_gen)
     # Strategy chain instance
     strategy_chain = StrategyChain(accept, visit_dist, func_wrapper,
-                                   minimizer_wrapper, rand_state, energy_state)
+                                   minimizer_wrapper, rng_gen, energy_state)
     need_to_stop = False
     iteration = 0
     message = []
@@ -701,7 +702,7 @@ def dual_annealing(func, bounds, args=(), maxiter=1000,
                 break
             # Need a re-annealing process?
             if temperature < temperature_restart:
-                energy_state.reset(func_wrapper, rand_state)
+                energy_state.reset(func_wrapper, rng_gen)
                 break
             # starting strategy chain
             val = strategy_chain.run(i, temperature)
diff --git a/scipy/optimize/tests/test__differential_evolution.py b/scipy/optimize/tests/test__differential_evolution.py
@@ -493,7 +493,8 @@ def test_quadratic_from_diff_ev(self):
         # test the quadratic function from differential_evolution function
         differential_evolution(self.quadratic,
                                [(-100, 100)],
-                               tol=0.02)
+                               tol=0.02,
+                               seed=1)
 
     def test_rng_gives_repeatability(self):
         result = differential_evolution(self.quadratic,
@@ -523,35 +524,6 @@ def test_random_generator(self):
                                    tol=0.5,
                                    init=init)
 
-    def test_rng_seed_spec007(self):
-        # spec007 involves the transition of RandomState-->Generator
-        # rng is the new name
-        differential_evolution(self.quadratic,
-                               [(-100, 100)],
-                               polish=False,
-                               rng=1,
-                               tol=0.5)
-        # should still be allowed to pass `seed`
-        differential_evolution(self.quadratic,
-                               [(-100, 100)],
-                               polish=False,
-                               seed=1,
-                               tol=0.5)
-        with assert_raises(TypeError):
-            # can't pass both seed and rng
-            differential_evolution(self.quadratic,
-                                   [(-100, 100)],
-                                   polish=False,
-                                   seed=1,
-                                   rng=1,
-                                   tol=0.5)
-            # use of rng=RandomState should give rise to an error.
-            differential_evolution(self.quadratic,
-                                   [(-100, 100)],
-                                   polish=False,
-                                   rng=np.random.RandomState(),
-                                   tol=0.5)
-
     def test_exp_runs(self):
         # test whether exponential mutation loop runs
         solver = DifferentialEvolutionSolver(rosen,
diff --git a/scipy/optimize/tests/test__dual_annealing.py b/scipy/optimize/tests/test__dual_annealing.py
