Merge pull request #78 from bashtage/restore-random-uintegers

bashtage · web-flow · commit 18b4eee10231 · 2017-01-19T22:29:29.000Z
ENH: Readd random uintegers
diff --git a/README.md b/README.md
@@ -93,6 +93,8 @@ commonly used in cryptographic applications
 * `random_raw` - Direct access to the values produced by the underlying 
 PRNG. The range of the values returned depends on the specifics of the 
 PRNG implementation.
+* `random_uintegers` - unsigned integers, either 32- (`[0, 2**32-1]`)
+or 64-bit (`[0, 2**64-1]`)
 * `jump` - Jumps RNGs that support it.  `jump` moves the state a great 
 distance. _Only available if supported by the RNG._
 * `advance` - Advanced the core RNG 'as-if' a number of draws were made, 
diff --git a/README.rst b/README.rst
@@ -97,6 +97,8 @@ New Functions
 -  ``random_raw`` - Direct access to the values produced by the
    underlying PRNG. The range of the values returned depends on the
    specifics of the PRNG implementation.
+-  ``random_uintegers`` - unsigned integers, either 32-
+   (``[0, 2**32-1]``) or 64-bit (``[0, 2**64-1]``)
 -  ``jump`` - Jumps RNGs that support it. ``jump`` moves the state a
    great distance. *Only available if supported by the RNG.*
 -  ``advance`` - Advanced the core RNG 'as-if' a number of draws were
diff --git a/doc/source/dsfmt.rst b/doc/source/dsfmt.rst
@@ -37,6 +37,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/mlfg.rst b/doc/source/mlfg.rst
@@ -31,6 +31,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/mrg32k3a.rst b/doc/source/mrg32k3a.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/mt19937.rst b/doc/source/mt19937.rst
@@ -32,6 +32,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/pcg32.rst b/doc/source/pcg32.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/pcg64.rst b/doc/source/pcg64.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/xoroshiro128plus.rst b/doc/source/xoroshiro128plus.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/xorshift1024.rst b/doc/source/xorshift1024.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/doc/source/xorshift128.rst b/doc/source/xorshift128.rst
@@ -38,6 +38,7 @@ Simple random data
    sample
    choice
    bytes
+   random_uintegers
    random_raw
 
 Permutations
diff --git a/randomstate/randomstate.pyx b/randomstate/randomstate.pyx
@@ -603,6 +603,64 @@ cdef class RandomState:
         self.__seed = state['seed']
         self.__stream = state['stream'] if 'stream' in state else None
 
+    def random_uintegers(self, size=None, int bits=64):
+        """
+        random_uintegers(size=None, bits=64)
+
+        Return random unsigned integers
+
+        Parameters
+        ----------
+        size : int or tuple of ints, optional
+            Output shape.  If the given shape is, e.g., ``(m, n, k)``, then
+            ``m * n * k`` samples are drawn.  Default is None, in which case a
+            single value is returned.
+        bits : int {32, 64}
+            Size of the unsigned integer to return, either 32 bit or 64 bit.
+
+        Returns
+        -------
+        out : uint or ndarray
+            Drawn samples.
+
+        Notes
+        -----
+        This method effectively exposes access to the raw underlying
+        pseudo-random number generator since these all produce unsigned
+        integers. In practice these are most useful for generating other
+        random numbers.
+
+        These should not be used to produce bounded random numbers by
+        simple truncation.
+        """
+        cdef uint32_t [:] randoms32
+        cdef uint64_t [:] randoms64
+        cdef aug_state* rng_state
+        cdef Py_ssize_t i, n
+        rng_state = &self.rng_state
+        if bits == 64:
+            if size is None:
+                with self.lock:
+                    return random_uint64(rng_state)
+            n = compute_numel(size)
+            randoms64 = np.empty(n, np.uint64)
+            with self.lock, nogil:
+                for i in range(n):
+                    randoms64[i] = random_uint64(rng_state)
+            return np.asarray(randoms64).reshape(size)
+        elif bits == 32:
+            if size is None:
+                with self.lock:
+                    return random_uint32(rng_state)
+            n = compute_numel(size)
+            randoms32 = np.empty(n, np.uint32)
+            with self.lock, nogil:
+                for i in range(n):
+                    randoms32[i] = random_uint32(rng_state)
+            return np.asarray(randoms32).reshape(size)
+        else:
+            raise ValueError('Unknown value of bits.  Must be either 32 or 64.')
+
     def random_raw(self, size=None):
         """
         random_raw(self, size=None)
@@ -4523,6 +4581,7 @@ permutation = _rand.permutation
 sample = ranf = random = random_sample
 
 random_raw = _rand.random_raw
+random_uintegers = _rand.random_uintegers
 
 
 IF RS_RNG_JUMPABLE:
diff --git a/randomstate/tests/test_numpy_mt19937.py b/randomstate/tests/test_numpy_mt19937.py
diff --git a/randomstate/tests/test_smoke.py b/randomstate/tests/test_smoke.py
