diff options
Diffstat (limited to 'doc/source/reference/randomgen')
| -rw-r--r-- | doc/source/reference/randomgen/extending.rst | 2 | ||||
| -rw-r--r-- | doc/source/reference/randomgen/generator.rst | 29 | ||||
| -rw-r--r-- | doc/source/reference/randomgen/index.rst | 120 | ||||
| -rw-r--r-- | doc/source/reference/randomgen/new-or-different.rst | 4 |
4 files changed, 76 insertions, 79 deletions
diff --git a/doc/source/reference/randomgen/extending.rst b/doc/source/reference/randomgen/extending.rst index c9d987b59..64f2ddcc1 100644 --- a/doc/source/reference/randomgen/extending.rst +++ b/doc/source/reference/randomgen/extending.rst @@ -59,6 +59,8 @@ directly in Numba after compiling the file distributions.c into a DLL or so. An example showing the use of a more complicated distribution is in the examples folder. +.. _randomgen_cython: + Cython ====== diff --git a/doc/source/reference/randomgen/generator.rst b/doc/source/reference/randomgen/generator.rst index d59efd68c..54325f4d3 100644 --- a/doc/source/reference/randomgen/generator.rst +++ b/doc/source/reference/randomgen/generator.rst @@ -1,29 +1,26 @@ +.. currentmodule:: numpy.random.randomgen + Random Generator ---------------- -The :class:`~randomgen.generator.RandomGenerator` provides access to -a wide range of distributions, and served as a replacement for -:class:`~numpy.random.RandomState`. The main difference between -the two is that :class:`~randomgen.generator.RandomGenerator` relies -on an additional basic RNG to manage state and generate the random -bits which are then transformed into random values from useful -distributions. The default basic RNG used by -:class:`~randomgen.generator.RandomGenerator` is -:class:`~randomgen.xoroshiro128.Xoroshiro128`. The basic RNG can be -changed by passing an instantized basic RNG to -:class:`~randomgen.generator.RandomGenerator`. +The :class:`~RandomGenerator` provides access to +a wide range of distributions, and served as a replacement for +:class:`~numpy.random.RandomState`. The main difference between +the two is that ``RandomGenerator`` relies on an additional basic RNG to +manage state and generate the random bits, which are then transformed into +random values from useful distributions. The default basic RNG used by +``RandomGenerator`` is :class:`~xoroshiro128.Xoroshiro128`. The basic RNG can be +changed by passing an instantized basic RNG to ``RandomGenerator``. -.. currentmodule:: numpy.random.randomgen.generator .. autoclass:: RandomGenerator :exclude-members: -Seed and State Manipulation -=========================== +Accessing the RNG +================= .. autosummary:: :toctree: generated/ - ~RandomGenerator.seed - ~RandomGenerator.state + ~RandomGenerator.brng Simple random data ================== diff --git a/doc/source/reference/randomgen/index.rst b/doc/source/reference/randomgen/index.rst index 67d0441a2..a8b6f1c9b 100644 --- a/doc/source/reference/randomgen/index.rst +++ b/doc/source/reference/randomgen/index.rst @@ -1,17 +1,21 @@ -Randomgen.RandomGen -=================== -This package contains replacements for the NumPy -:class:`~numpy.random.RandomState` object that allows the core random number -generator be be changed. - .. current_module numpy.random.randomgen +numpy.random.randomgen +====================== + +This package modernizes the legacy +`~numpy.random.RandomState` object and allows changing the core random +number generator (RNG). The `~numpy.random.randomgen.RandomGenerator` can +be initialized with a number of different RNGs, and exposes many different +probability distributions. + + Quick Start ----------- -Like :mod:`numpy.random`, RandomGen can be used at the module level. -This uses the default :class:`~randomgen.generator.RandomGenerator` which -uses normals provided by :class:`~randomgen.xoroshiro128.Xoroshiro128`. +By default, `generator.RandomGenerator` uses normals provided by +`xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in +`numpy.random` .. code-block:: python @@ -19,12 +23,11 @@ uses normals provided by :class:`~randomgen.xoroshiro128.Xoroshiro128`. import randomgen.generator as random random.standard_normal() -:class:`~randomgen.generator.RandomGenerator` can also be used as a -replacement for :class:`~numpy.random.RandomState`, although the random -values are generated by :class:`~randomgen.xoroshiro128.Xoroshiro128`. It -also isn't possible to directly seed a -:class:`~randomgen.generator.RandomGenerator`. - +`numpy.random.randomgen.RandomGenerator` can also be used as a replacement for +`~numpy.random.RandomState`, although the random values are generated by +`~numpyrandom.randomgen.xoroshiro128.Xoroshiro128`. Since ``randomgen`` +separates the `~numpy.random.randomgen.RandomGenerator` from the RNG, it is not +possible to directly seed the generator. .. code-block:: python @@ -34,9 +37,9 @@ also isn't possible to directly seed a rg.standard_normal() -Seeds can be passed to any of the basic RNGs. Here :class:`~randomgen.mt19937.MT19937` -is used and the :class:`~randomgen.generator.RandomGenerator` is accessed via -the property :attr:`~randomgen.mt19937.MT19937.generator`. +Seeds can be passed to any of the basic RNGs. Here `numpy.random.randomgen. +mt19937.MT19937` is used and the `~numpy.random.randomgen.RandomGenerator` is +accessed via the attribute `~numpy.random.randomgen.mt19937.MT19937.generator`. .. code-block:: python @@ -48,24 +51,23 @@ the property :attr:`~randomgen.mt19937.MT19937.generator`. Introduction ------------ RandomGen takes a different approach to producing random numbers from the -:class:`numpy.random.RandomState` object used in NumPy. Random number -generation is separated into two components, a basic RNG and a random -generator. +:class:`numpy.random.RandomState` object. Random number generation is +separated into two components, a basic RNG and a random generator. -The basic RNG has a limited set of responsibilities -- it manages the +The basic RNG has a limited set of responsibilities. It manages the underlying RNG state and provides functions to produce random doubles and random unsigned 32- and 64-bit values. The basic random generator also handles all seeding since this varies when using alternative basic RNGs. -The random generator (:class:`~randomgen.generator.RandomGenerator`) takes the +The `random generator <~numpy.random.randomgen.RandomGenerator>` takes the basic RNG-provided functions and transforms them into more useful distributions, e.g., simulated normal random values. This structure allows alternative basic RNGs to be used without code duplication. -The :class:`~randomgen.generator.RandomGenerator` is the user-facing object +The `~numpy.random.randomgen.RandomGenerator` is the user-facing object that is nearly identical to :class:`~numpy.random.RandomState`. The canonical -method to initialize a generator passes a basic RNG -- -:class:`~randomgen.mt19937.MT19937`, the underlying RNG in NumPy -- as the +method to initialize a generator passes a basic RNG -- `~numpy.random. +randomgen.mt19937.MT19937`, the underlying RNG in NumPy -- as the sole argument. Note that the basic RNG must be instantized. .. code-block:: python @@ -81,9 +83,9 @@ Seed information is directly passed to the basic RNG. rg = RandomGenerator(MT19937(12345)) rg.random_sample() -A shorthand method is also available which uses the -:meth:`~randomgen.mt19937.MT19937.generator` property from a basic RNG to -access an embedded random generator. +A shorthand method is also available which uses the `~numpy.random.randomgen. +mt19937.MT19937.generator` property from a basic RNG to access an embedded +random generator. .. code-block:: python @@ -95,13 +97,14 @@ What's New or Different .. warning:: The Box-Muller method used to produce NumPy's normals is no longer available - in :class:`~randomgen.generator.RandomGenerator`. It is not possible to - reproduce the random values using :class:`~randomgen.generator.RandomGenerator` - for the normal distribution or any other distribution that relies on the - normal such as the gamma or student's t. If you require backward compatibility, a - legacy generator, :class:`~randomgen.legacy.LegacyGenerator`, has been created - which can fully reproduce the sequence produced by NumPy. - + in `~numpy.random.randomgen.RandomGenerator`. It is not possible to + reproduce the random values using `~numpy.random.randomgen.RandomGenerator` + for the normal distribution or any other distribution that + relies on the normal such as the gamma or student's t. If you require + backward compatibility, a legacy generator, `~numpy.random.randomgen.legacy. + LegacyGenerator`, has been created which can fully reproduce the sequence + produced by NumPy. + * The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF implementations. @@ -110,20 +113,18 @@ What's New or Different select distributions * Optional ``out`` argument that allows existing arrays to be filled for select distributions -* Simulate from the complex normal distribution - (:meth:`~randomgen.generator.RandomGenerator.complex_normal`) -* :func:`~randomgen.entropy.random_entropy` provides access to the system +* `~numpy.random.randomgen.entropy.random_entropy` provides access to the system source of randomness that is used in cryptographic applications (e.g., ``/dev/urandom`` on Unix). -* All basic random generators functions to produce doubles, uint64s and - uint32s via CTypes (:meth:`~randomgen.xoroshiro128.Xoroshiro128.ctypes`) - and CFFI (:meth:`~randomgen.xoroshiro128.Xoroshiro128.cffi`). This allows - these basic RNGs to be used in numba. +* All basic random generators functions can produce doubles, uint64s and + uint32s via CTypes (`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.ctypes`) + and CFFI (:meth:`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.cffi`). + This allows these basic RNGs to be used in numba. * The basic random number generators can be used in downstream projects via - Cython. + :ref:`Cython <randomgen_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`). + `~umpy.random.randomgen.generator.RandomGenerator.randint`. See :ref:`new-or-different` for a complete list of improvements and @@ -144,9 +145,9 @@ The main innovation is the inclusion of a number of alternative pseudo-random nu generators, 'in addition' to the standard PRNG in NumPy. The included PRNGs are: * MT19937 - The standard NumPy generator. Produces identical results to NumPy - using the same seed/state. Adds a jump function that advances the generator - as-if 2**128 draws have been made (:meth:`~randomgen.mt19937.MT19937.jump`). - See `NumPy's documentation`_. + using the same seed/state. Adds a + `~numpy.random.randomgen.mt19937.MT19937.jump` function that advances the + generator as-if ``2**128`` draws have been made. See `numpy.random`. * dSFMT - SSE2 enabled versions of the MT19937 generator. Theoretically the same, but with a different state and so it is not possible to produce a sequence identical to MT19937. Supports ``jump`` and so can @@ -154,31 +155,30 @@ generators, 'in addition' to the standard PRNG in NumPy. The included PRNGs are * XoroShiro128+ - Improved version of XorShift128+ with better performance and statistical quality. Like the XorShift generators, it can be jumped to produce multiple streams in parallel applications. See - :meth:`~randomgen.xoroshiro128.Xoroshiro128.jump` for details. + `~numpy.random.randomgen.xoroshiro128.Xoroshiro128.jump` for details. More information about this PRNG is available at the `xorshift, xoroshiro and xoshiro authors' page`_. * XorShift1024*φ - Fast fast generator based on the XSadd generator. Supports ``jump`` and so can be used in parallel applications. See the documentation for - :meth:`~randomgen.xorshift1024.Xorshift1024.jump` for details. More information - about these PRNGs is available at the + `~numpy.random.randomgen.xorshift1024.Xorshift1024.jump` for details. More + information about these PRNGs is available at the `xorshift, xoroshiro and xoshiro authors' page`_. * Xorshiro256** and Xorshiro512** - The most recently introduced XOR, shift, and rotate generator. Supports ``jump`` and so can be used in parallel applications. See the documentation for - :meth:`~randomgen.xoshiro256starstar.Xoshirt256StarStar.jump` for details. More - information about these PRNGs is available at the + `~numpy.random.randomgen.xoshiro256starstar.Xoshirt256StarStar.jump` for + details. More information about these PRNGs is available at the `xorshift, xoroshiro and xoshiro authors' page`_. * PCG-64 - Fast generator that support many parallel streams and can be advanced by an arbitrary amount. See the documentation for - :meth:`~randomgen.pcg64.PCG64.advance`. PCG-64 has a period of + `~numpy.random.randomgen.pcg64.PCG64.advance`. PCG-64 has a period of :math:`2^{128}`. See the `PCG author's page`_ for more details about this class of PRNG. * ThreeFry and Philox - counter-based generators capable of being advanced an arbitrary number of steps or generating independent streams. See the `Random123`_ page for more details about this class of PRNG. -.. _`NumPy's documentation`: https://docs.scipy.org/doc/numpy/reference/routines.random.html .. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/ .. _`xorshift, xoroshiro and xoshiro authors' page`: http://xoroshiro.di.unimi.it/ .. _`PCG author's page`: http://www.pcg-random.org/ @@ -215,14 +215,12 @@ New Features Changes ~~~~~~~ + +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. + .. toctree:: :maxdepth: 2 Change Log <change-log> -Indices and tables -~~~~~~~~~~~~~~~~~~ - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/doc/source/reference/randomgen/new-or-different.rst b/doc/source/reference/randomgen/new-or-different.rst index 0a27b9aa1..089efd6fb 100644 --- a/doc/source/reference/randomgen/new-or-different.rst +++ b/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 |