diff --git a/README.md b/README.md index 2d95361ab..34986ebdb 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,9 @@ which can fully reproduce the sequence produced by NumPy. * Normals (`standard_normal`) * Standard Gammas (via `standard_gamma`) +* Support for Lemire's method of generating uniform integers on an + arbitrary interval by setting `use_masked=True`. + ## Included Pseudo Random Number Generators This module includes a number of alternative random @@ -103,6 +106,10 @@ The RNGs include: * Core random number generators can fill existing arrays using the `out` keyword argument * Standardizes integer-values random values as int64 for all platforms. +* `randint` supports generating using rejection sampling on masked + values (the default) or Lemire's method. Lemire's method can be much + faster when the required interval length is much smaller than the + closes power of 2. ### New Functions diff --git a/README.rst b/README.rst index e36f99997..69de75ab3 100644 --- a/README.rst +++ b/README.rst @@ -71,6 +71,9 @@ Features - Normals (``standard_normal``) - Standard Gammas (via ``standard_gamma``) +- Support for Lemire’s method of generating uniform integers on an + arbitrary interval by setting ``use_masked=True``. + Included Pseudo Random Number Generators ---------------------------------------- @@ -111,6 +114,10 @@ New Features - Core random number generators can fill existing arrays using the ``out`` keyword argument - Standardizes integer-values random values as int64 for all platforms. +- ``randint`` supports generating using rejection sampling on masked + values (the default) or Lemire’s method. Lemire’s method can be much + faster when the required interval length is much smaller than the + closes power of 2. New Functions ~~~~~~~~~~~~~ diff --git a/doc/source/change-log.rst b/doc/source/change-log.rst index 29876a4b9..629dd0002 100644 --- a/doc/source/change-log.rst +++ b/doc/source/change-log.rst @@ -1,12 +1,12 @@ Change Log ---------- -After v1.15 -=========== -- Added Xoshiro256** and Xoshiro512**, the preferred generators of this class -- Fixed bug in `jump` method of Random123 generators which did nto specify a default value - - +v1.15.1 +======= +- Added Xoshiro256** and Xoshiro512**, the preferred generators of this class. +- Fixed bug in `jump` method of Random123 generators which did nto specify a default value. +- Added support for generating bounded uniform integers using Lemire's method. +- Synchronized with upstream changes, which requires moving the minimum supported NumPy to 1.13. v1.15 ===== diff --git a/doc/source/index.rst b/doc/source/index.rst index 7db6cbd5b..eac8c1ef1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -119,6 +119,10 @@ What's New or Different these basic RNGs to be used in numba. * The basic random number generators can be used in downstream projects via Cython. +* Support for Lemire’s method [Lemire]_ of generating uniform integers on an + arbitrary interval by setting ``use_masked=True`` in + (:meth:`~randomgen.generator.RandomGenerator.randint`). + See :ref:`new-or-different` for a complete list of improvements and differences. @@ -205,6 +209,7 @@ New Features Comparing Performance extending Reading System Entropy + references Changes ~~~~~~~ diff --git a/doc/source/new-or-different.rst b/doc/source/new-or-different.rst index c94d95c7c..6598c13fe 100644 --- a/doc/source/new-or-different.rst +++ b/doc/source/new-or-different.rst @@ -87,3 +87,12 @@ What's New or Different print(existing) .. * For changes since the previous release, see the :ref:`change-log` + +* Support for Lemire’s method of generating uniform integers on an + arbitrary interval by setting ``use_masked=True`` in + (:meth:`~randomgen.generator.RandomGenerator.randint`). + +.. ipython:: python + + %timeit rg.randint(0, 1535, use_masked=False) + %timeit numpy.random.randint(0, 1535) diff --git a/doc/source/references.rst b/doc/source/references.rst new file mode 100644 index 000000000..0dc99868f --- /dev/null +++ b/doc/source/references.rst @@ -0,0 +1,5 @@ +References +---------- + +.. [Lemire] Daniel Lemire., "Fast Random Integer Generation in an Interval", + CoRR, Aug. 13, 2018, http://arxiv.org/abs/1805.10941. diff --git a/randomgen/generator.pyx b/randomgen/generator.pyx index 1e92d408b..5d239c725 100644 --- a/randomgen/generator.pyx +++ b/randomgen/generator.pyx @@ -574,7 +574,7 @@ cdef class RandomGenerator: def randint(self, low, high=None, size=None, dtype=int, use_masked=True): """ - randint(low, high=None, size=None, dtype='l') + randint(low, high=None, size=None, dtype='l', use_masked=True) Return random integers from `low` (inclusive) to `high` (exclusive). @@ -652,6 +652,11 @@ cdef class RandomGenerator: >>> randomgen.randint([1, 3, 5, 7], [[10], [20]], dtype=np.uint8) array([[ 8, 6, 9, 7], [ 1, 16, 9, 12]], dtype=uint8) + + References + ---------- + .. [1] Daniel Lemire., "Fast Random Integer Generation in an Interval", + CoRR, Aug. 13, 2018, http://arxiv.org/abs/1805.10941. """ if high is None: high = low