diff options
| -rw-r--r-- | doc/source/reference/random/index.rst | 76 | ||||
| -rw-r--r-- | numpy/random/_generator.pyx | 53 |
2 files changed, 109 insertions, 20 deletions
diff --git a/doc/source/reference/random/index.rst b/doc/source/reference/random/index.rst index d559f2327..13ce7c40c 100644 --- a/doc/source/reference/random/index.rst +++ b/doc/source/reference/random/index.rst @@ -23,7 +23,9 @@ number of different BitGenerators. It exposes many different probability distributions. See `NEP 19 <https://www.numpy.org/neps/ nep-0019-rng-policy.html>`_ for context on the updated random Numpy number routines. The legacy `RandomState` random number routines are still -available, but limited to a single BitGenerator. +available, but limited to a single BitGenerator. See :ref:`new-or-different` +for a complete list of improvements and differences from the legacy +``Randomstate``. For convenience and backward compatibility, a single `RandomState` instance's methods are imported into the numpy.random namespace, see @@ -41,13 +43,13 @@ properties than the legacy `MT19937` used in `RandomState`. .. code-block:: python - # Do this + # Do this (new version) from numpy.random import default_rng rng = default_rng() vals = rng.standard_normal(10) more_vals = rng.standard_normal(10) - # instead of this + # instead of this (legacy version) from numpy import random vals = random.standard_normal(10) more_vals = random.standard_normal(10) @@ -73,7 +75,7 @@ cleanup means that legacy and compatibility methods have been removed from ``seed`` removed Use `SeedSequence.spawn` =================== ============== ============ -See :ref:`new-or-different` for more information +See :ref:`new-or-different` for more information. Something like the following code can be used to support both ``RandomState`` and ``Generator``, with the understanding that the interfaces are slightly @@ -97,6 +99,30 @@ is wrapped with a `Generator`. from numpy.random import Generator, PCG64 rg = Generator(PCG64(12345)) rg.standard_normal() + +Here we use `default_rng` to create an instance of `Generator` to generate a +random float: + +>>> import numpy as np +>>> rng = np.random.default_rng(12345) +>>> print(rng) +Generator(PCG64) +>>> rfloat = rng.random() +>>> rfloat +0.22733602246716966 +>>> type(rfloat) +<class 'float'> + +Here we use `default_rng` to create an instance of `Generator` to generate 3 +random integers between 0 (inclusive) and 10 (exclusive): + +>>> import numpy as np +>>> rng = np.random.default_rng(12345) +>>> rints = rng.integers(low=0, high=10, size=3) +>>> rints +array([6, 2, 7]) +>>> type(rints[0]) +<class 'numpy.int64'> Introduction ------------ @@ -113,25 +139,36 @@ bit generator-provided stream and transforms them into more useful distributions, e.g., simulated normal random values. This structure allows alternative bit generators to be used with little code duplication. -The `Generator` is the user-facing object that is nearly identical to -`RandomState`. The canonical method to initialize a generator passes a -`PCG64` bit generator as the sole argument. +The `Generator` is the user-facing object that is nearly identical to the +legacy `RandomState`. It accepts a bit generator instance as an argument. +The default is currently `PCG64` but this may change in future versions. +As a convenience NumPy provides the `default_rng` function to hide these +details: + +>>> from numpy.random import default_rng +>>> rg = default_rng(12345) +>>> print(rg) +Generator(PCG64) +>>> print(rg.random()) +0.22733602246716966 + +One can also instantiate `Generator` directly with a `BitGenerator` instance. -.. code-block:: python +To use the default `PCG64` bit generator, one can instantiate it directly and +pass it to `Generator`: - from numpy.random import default_rng - rg = default_rng(12345) - rg.random() +>>> from numpy.random import Generator, PCG64 +>>> rg = Generator(PCG64(12345)) +>>> print(rg) +Generator(PCG64) -One can also instantiate `Generator` directly with a `BitGenerator` instance. -To use the older `MT19937` algorithm, one can instantiate it directly -and pass it to `Generator`. +Similarly to use the older `MT19937` bit generator (not recommended), one can +instantiate it directly and pass it to `Generator`: -.. code-block:: python - - from numpy.random import Generator, MT19937 - rg = Generator(MT19937(12345)) - rg.random() +>>> from numpy.random import Generator, MT19937 +>>> rg = Generator(MT19937(12345)) +>>> print(rg) +Generator(MT19937) What's New or Different ~~~~~~~~~~~~~~~~~~~~~~~ @@ -211,4 +248,3 @@ Original Source of the Generator and BitGenerators This package was developed independently of NumPy and was integrated in version 1.17.0. The original repo is at https://github.com/bashtage/randomgen. - diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx index 0936ea2e8..cc2852da7 100644 --- a/numpy/random/_generator.pyx +++ b/numpy/random/_generator.pyx @@ -4349,6 +4349,59 @@ def default_rng(seed=None): ----- If ``seed`` is not a `BitGenerator` or a `Generator`, a new `BitGenerator` is instantiated. This function does not manage a default global instance. + + Examples + -------- + ``default_rng`` is the reccomended constructor for the random number class + ``Generator``. Here are several ways we can construct a random + number generator using ``default_rng`` and the ``Generator`` class. + + Here we use ``default_rng`` to generate a random float: + + >>> import numpy as np + >>> rng = np.random.default_rng(12345) + >>> print(rng) + Generator(PCG64) + >>> rfloat = rng.random() + >>> rfloat + 0.22733602246716966 + >>> type(rfloat) + <class 'float'> + + Here we use ``default_rng`` to generate 3 random integers between 0 + (inclusive) and 10 (exclusive): + + >>> import numpy as np + >>> rng = np.random.default_rng(12345) + >>> rints = rng.integers(low=0, high=10, size=3) + >>> rints + array([6, 2, 7]) + >>> type(rints[0]) + <class 'numpy.int64'> + + Here we specify a seed so that we have reproducible results: + + >>> import numpy as np + >>> rng = np.random.default_rng(seed=42) + >>> print(rng) + Generator(PCG64) + >>> arr1 = rng.random((3, 3)) + >>> arr1 + array([[0.77395605, 0.43887844, 0.85859792], + [0.69736803, 0.09417735, 0.97562235], + [0.7611397 , 0.78606431, 0.12811363]]) + + If we exit and restart our Python interpreter, we'll see that we + generate the same random numbers again: + + >>> import numpy as np + >>> rng = np.random.default_rng(seed=42) + >>> arr2 = rng.random((3, 3)) + >>> arr2 + array([[0.77395605, 0.43887844, 0.85859792], + [0.69736803, 0.09417735, 0.97562235], + [0.7611397 , 0.78606431, 0.12811363]]) + """ if _check_bit_generator(seed): # We were passed a BitGenerator, so just wrap it up. |