ENH: remove convenience functions, require explicit call to gen.brng

Author: mattip

doc/source/reference/randomgen/generator.rst

@@ -15,13 +15,12 @@ changed by passing an instantized basic RNG to ``RandomGenerator``.
 .. autoclass:: RandomGenerator
 	:exclude-members:
 
-Seed and State Manipulation
-===========================
+Accessing the RNG
+=================
 .. autosummary::
    :toctree: generated/
 
-   ~RandomGenerator.seed
-   ~RandomGenerator.state
+   ~RandomGenerator.brng
 
 Simple random data
 ==================

doc/source/reference/randomgen/new-or-different.rst

@@ -64,9 +64,9 @@ What's New or Different
 
 .. ipython:: python
 
-  rg.seed(0)
+  rg.brng.seed(0)
   rg.random_sample(3, dtype='d')
-  rg.seed(0)
+  rg.brng.seed(0)
   rg.random_sample(3, dtype='f')
 
 * Optional ``out`` argument that allows existing arrays to be filled for

numpy/random/randomgen/generator.pyx

@@ -72,7 +72,7 @@ cdef class RandomGenerator:
     >>> rg = MT19937().generator
     >>> rg.standard_normal()
     """
-    cdef public object _basicrng
+    cdef public object brng
     cdef brng_t *_brng
     cdef binomial_t *_binomial
     cdef object lock
@@ -81,7 +81,7 @@ cdef class RandomGenerator:
     def __init__(self, brng=None):
         if brng is None:
             brng = Xoroshiro128()
-        self._basicrng = brng
+        self.brng = brng
 
         capsule = brng.capsule
         cdef const char *name = "BasicRNG"
@@ -99,79 +99,21 @@ cdef class RandomGenerator:
 
     def __str__(self):
         _str = self.__class__.__name__
-        _str += '(' + self._basicrng.__class__.__name__ + ')'
+        _str += '(' + self.brng.__class__.__name__ + ')'
         return _str
 
     # Pickling support:
     def __getstate__(self):
-        return self.state
+        return self.brng.state
 
     def __setstate__(self, state):
-        self.state = state
+        self.brng.state = state
 
     def __reduce__(self):
         from ._pickle import __generator_ctor
         return (__generator_ctor,
-                (self.state['brng'],),
-                self.state)
-
-    def seed(self, *args, **kwargs):
-        """
-        Reseed the basic RNG.
-
-        Parameters depend on the basic RNG used.
-
-        Notes
-        -----
-        Arguments are directly passed to the basic RNG. This is a convenience
-        function.
-
-        The best method to access seed is to directly use a basic RNG instance.
-        This example demonstrates this best practice.
-
-        >>> from numpy.random.randomgen import RandomGenerator, PCG64
-        >>> brng = PCG64(1234567891011)
-        >>> rg = brng.generator
-        >>> brng.seed(1110987654321)
-
-        The method used to create the generator is not important.
-
-        >>> brng = PCG64(1234567891011)
-        >>> rg = RandomGenerator(brng)
-        >>> brng.seed(1110987654321)
-
-        These best practice examples are equivalent to
-
-        >>> rg = RandomGenerator(PCG64(1234567891011))
-        >>> rg.seed(1110987654321)
-
-        """
-        # TODO: Should this remain
-        self._basicrng.seed(*args, **kwargs)
-        return self
-
-    @property
-    def state(self):
-        """
-        Get or set the Basic RNG's state
-
-        Returns
-        -------
-        state : dict
-            Dictionary containing the information required to describe the
-            state of the Basic RNG
-
-        Notes
-        -----
-        This is a trivial pass-through function.  RandomGenerator does not
-        directly contain or manipulate the basic RNG's state.
-
-        """
-        return self._basicrng.state
-
-    @state.setter
-    def state(self, value):
-        self._basicrng.state = value
+                (self.brng.state['brng'],),
+                self.brng.state)
 
     def random_sample(self, size=None, dtype=np.float64, out=None):
         """

numpy/random/randomgen/tests/test_against_numpy.py

@@ -98,12 +98,12 @@ def setup_class(cls):
         cls.rg = RandomGenerator(cls.brng(*cls.seed))
         cls.rs = RandomState(cls.brng(*cls.seed))
         cls.nprs = cls.np.RandomState(*cls.seed)
-        cls.initial_state = cls.rg.state
+        cls.initial_state = cls.rg.brng.state
         cls._set_common_state()
 
     @classmethod
     def _set_common_state(cls):
-        state = cls.rg.state
+        state = cls.rg.brng.state
         st = [[]] * 5
         st[0] = 'MT19937'
         st[1] = state['state']['key']
@@ -125,7 +125,7 @@ def _set_common_state_legacy(cls):
 
     def _is_state_common(self):
         state = self.nprs.get_state()
-        state2 = self.rg.state
+        state2 = self.rg.brng.state
         assert (state[1] == state2['state']['key']).all()
         assert (state[2] == state2['state']['pos'])
 
@@ -138,19 +138,19 @@ def _is_state_common_legacy(self):
         assert_allclose(state[4], state2['gauss'], atol=1e-10)
 
     def test_common_seed(self):
-        self.rg.seed(1234)
+        self.rg.brng.seed(1234)
         self.nprs.seed(1234)
         self._is_state_common()
-        self.rg.seed(23456)
+        self.rg.brng.seed(23456)
         self.nprs.seed(23456)
         self._is_state_common()
 
     def test_numpy_state(self):
         nprs = np.random.RandomState()
         nprs.standard_normal(99)
         state = nprs.get_state()
-        self.rg.state = state
-        state2 = self.rg.state
+        self.rg.brng.state = state
+        state2 = self.rg.brng.state
         assert (state[1] == state2['state']['key']).all()
         assert (state[2] == state2['state']['pos'])
 
@@ -383,7 +383,7 @@ def test_scalar(self):
         assert_equal(s1.randint(1000), 419)
         assert_equal(s1.randint(1000), s.randint(1000))
 
-        self.rg.seed(4294967295)
+        self.rg.brng.seed(4294967295)
         self.nprs.seed(4294967295)
         self._is_state_common()
 
@@ -403,9 +403,10 @@ def test_array(self):
     def test_dir(self):
         nprs_d = set(dir(self.nprs))
         rs_d = dir(self.rg)
-        excluded = {'get_state', 'set_state'}
+        excluded = {'get_state', 'set_state', '_basicrng', 'seed', '__getstate__'}
         nprs_d.difference_update(excluded)
-        assert (len(nprs_d.difference(rs_d)) == 0)
+        d = nprs_d.difference(rs_d)
+        assert (len(d) == 0)
 
         npmod = dir(numpy.random)
         mod = dir(generator)

numpy/random/randomgen/tests/test_direct.py

@@ -206,30 +206,30 @@ def test_uniform_float(self):
     def test_seed_float(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(self.seed_error_type, rs.seed, np.pi)
-        assert_raises(self.seed_error_type, rs.seed, -np.pi)
+        assert_raises(self.seed_error_type, rs.brng.seed, np.pi)
+        assert_raises(self.seed_error_type, rs.brng.seed, -np.pi)
 
     def test_seed_float_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(self.seed_error_type, rs.seed, np.array([np.pi]))
-        assert_raises(self.seed_error_type, rs.seed, np.array([-np.pi]))
-        assert_raises(ValueError, rs.seed, np.array([np.pi, -np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([0, np.pi]))
-        assert_raises(TypeError, rs.seed, [np.pi])
-        assert_raises(TypeError, rs.seed, [0, np.pi])
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([np.pi]))
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([-np.pi]))
+        assert_raises(ValueError, rs.brng.seed, np.array([np.pi, -np.pi]))
+        assert_raises(TypeError, rs.brng.seed, np.array([0, np.pi]))
+        assert_raises(TypeError, rs.brng.seed, [np.pi])
+        assert_raises(TypeError, rs.brng.seed, [0, np.pi])
 
     def test_seed_out_of_range(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(ValueError, rs.seed, 2 ** (2 * self.bits + 1))
-        assert_raises(ValueError, rs.seed, -1)
+        assert_raises(ValueError, rs.brng.seed, 2 ** (2 * self.bits + 1))
+        assert_raises(ValueError, rs.brng.seed, -1)
 
     def test_seed_out_of_range_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(ValueError, rs.seed, [2 ** (2 * self.bits + 1)])
-        assert_raises(ValueError, rs.seed, [-1])
+        assert_raises(ValueError, rs.brng.seed, [2 ** (2 * self.bits + 1)])
+        assert_raises(ValueError, rs.brng.seed, [-1])
 
     def test_repr(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
@@ -412,18 +412,18 @@ def setup_class(cls):
 
     def test_seed_float_array(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(self.seed_error_type, rs.seed, np.array([np.pi]))
-        assert_raises(self.seed_error_type, rs.seed, np.array([-np.pi]))
-        assert_raises(self.seed_error_type, rs.seed, np.array([np.pi, -np.pi]))
-        assert_raises(self.seed_error_type, rs.seed, np.array([0, np.pi]))
-        assert_raises(self.seed_error_type, rs.seed, [np.pi])
-        assert_raises(self.seed_error_type, rs.seed, [0, np.pi])
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([np.pi]))
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([-np.pi]))
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([np.pi, -np.pi]))
+        assert_raises(self.seed_error_type, rs.brng.seed, np.array([0, np.pi]))
+        assert_raises(self.seed_error_type, rs.brng.seed, [np.pi])
+        assert_raises(self.seed_error_type, rs.brng.seed, [0, np.pi])
 
     def test_seed_out_of_range_array(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(self.seed_error_type, rs.seed,
+        assert_raises(self.seed_error_type, rs.brng.seed,
                       [2 ** (2 * self.bits + 1)])
-        assert_raises(self.seed_error_type, rs.seed, [-1])
+        assert_raises(self.seed_error_type, rs.brng.seed, [-1])
 
 
 class TestPhilox(Base):
@@ -464,43 +464,45 @@ def setup_class(cls):
     def test_seed_out_of_range(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(ValueError, rs.seed, 2 ** (self.bits + 1))
-        assert_raises(ValueError, rs.seed, -1)
-        assert_raises(ValueError, rs.seed, 2 ** (2 * self.bits + 1))
+        assert_raises(ValueError, rs.brng.seed, 2 ** (self.bits + 1))
+        assert_raises(ValueError, rs.brng.seed, -1)
+        assert_raises(ValueError, rs.brng.seed, 2 ** (2 * self.bits + 1))
 
     def test_seed_out_of_range_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(ValueError, rs.seed, [2 ** (self.bits + 1)])
-        assert_raises(ValueError, rs.seed, [-1])
-        assert_raises(TypeError, rs.seed, [2 ** (2 * self.bits + 1)])
+        assert_raises(ValueError, rs.brng.seed, [2 ** (self.bits + 1)])
+        assert_raises(ValueError, rs.brng.seed, [-1])
+        assert_raises(TypeError, rs.brng.seed, [2 ** (2 * self.bits + 1)])
 
     def test_seed_float(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(TypeError, rs.seed, np.pi)
-        assert_raises(TypeError, rs.seed, -np.pi)
+        assert_raises(TypeError, rs.brng.seed, np.pi)
+        assert_raises(TypeError, rs.brng.seed, -np.pi)
 
     def test_seed_float_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(TypeError, rs.seed, np.array([np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([-np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([np.pi, -np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([0, np.pi]))
-        assert_raises(TypeError, rs.seed, [np.pi])
-        assert_raises(TypeError, rs.seed, [0, np.pi])
+        brng = rs.brng
+        assert_raises(TypeError, brng.seed, np.array([np.pi]))
+        assert_raises(TypeError, brng.seed, np.array([-np.pi]))
+        assert_raises(TypeError, brng.seed, np.array([np.pi, -np.pi]))
+        assert_raises(TypeError, brng.seed, np.array([0, np.pi]))
+        assert_raises(TypeError, brng.seed, [np.pi])
+        assert_raises(TypeError, brng.seed, [0, np.pi])
 
     def test_state_tuple(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        state = rs.state
+        brng = rs.brng
+        state = brng.state
         desired = rs.randint(2 ** 16)
         tup = (state['brng'], state['state']['key'], state['state']['pos'])
-        rs.state = tup
+        brng.state = tup
         actual = rs.randint(2 ** 16)
         assert_equal(actual, desired)
         tup = tup + (0, 0.0)
-        rs.state = tup
+        brng.state = tup
         actual = rs.randint(2 ** 16)
         assert_equal(actual, desired)
 
@@ -542,25 +544,25 @@ def test_gauss_inv(self):
     def test_seed_out_of_range_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(ValueError, rs.seed, [2 ** (self.bits + 1)])
-        assert_raises(ValueError, rs.seed, [-1])
-        assert_raises(TypeError, rs.seed, [2 ** (2 * self.bits + 1)])
+        assert_raises(ValueError, rs.brng.seed, [2 ** (self.bits + 1)])
+        assert_raises(ValueError, rs.brng.seed, [-1])
+        assert_raises(TypeError, rs.brng.seed, [2 ** (2 * self.bits + 1)])
 
     def test_seed_float(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(TypeError, rs.seed, np.pi)
-        assert_raises(TypeError, rs.seed, -np.pi)
+        assert_raises(TypeError, rs.brng.seed, np.pi)
+        assert_raises(TypeError, rs.brng.seed, -np.pi)
 
     def test_seed_float_array(self):
         # GH #82
         rs = RandomGenerator(self.brng(*self.data1['seed']))
-        assert_raises(TypeError, rs.seed, np.array([np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([-np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([np.pi, -np.pi]))
-        assert_raises(TypeError, rs.seed, np.array([0, np.pi]))
-        assert_raises(TypeError, rs.seed, [np.pi])
-        assert_raises(TypeError, rs.seed, [0, np.pi])
+        assert_raises(TypeError, rs.brng.seed, np.array([np.pi]))
+        assert_raises(TypeError, rs.brng.seed, np.array([-np.pi]))
+        assert_raises(TypeError, rs.brng.seed, np.array([np.pi, -np.pi]))
+        assert_raises(TypeError, rs.brng.seed, np.array([0, np.pi]))
+        assert_raises(TypeError, rs.brng.seed, [np.pi])
+        assert_raises(TypeError, rs.brng.seed, [0, np.pi])
 
     def test_uniform_float(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
@@ -578,9 +580,9 @@ def test_uniform_float(self):
     def test_buffer_reset(self):
         rs = RandomGenerator(self.brng(*self.data1['seed']))
         rs.random_sample(1)
-        assert rs.state['buffer_loc'] != 382
-        rs.seed(*self.data1['seed'])
-        assert rs.state['buffer_loc'] == 382
+        assert rs.brng.state['buffer_loc'] != 382
+        rs.brng.seed(*self.data1['seed'])
+        assert rs.brng.state['buffer_loc'] == 382
 
 
 class TestThreeFry32(Base):