diff options
Diffstat (limited to 'doc/source/reference')
| -rw-r--r-- | doc/source/reference/random/brng/dsfmt.rst (renamed from doc/source/reference/randomgen/brng/dsfmt.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/index.rst (renamed from doc/source/reference/randomgen/brng/index.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/mt19937.rst (renamed from doc/source/reference/randomgen/brng/mt19937.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/pcg32.rst (renamed from doc/source/reference/randomgen/brng/pcg32.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/pcg64.rst (renamed from doc/source/reference/randomgen/brng/pcg64.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/philox.rst (renamed from doc/source/reference/randomgen/brng/philox.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/threefry.rst (renamed from doc/source/reference/randomgen/brng/threefry.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/threefry32.rst (renamed from doc/source/reference/randomgen/brng/threefry32.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/xoroshiro128.rst (renamed from doc/source/reference/randomgen/brng/xoroshiro128.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/xorshift1024.rst (renamed from doc/source/reference/randomgen/brng/xorshift1024.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/xoshiro256starstar.rst (renamed from doc/source/reference/randomgen/brng/xoshiro256starstar.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/brng/xoshiro512starstar.rst (renamed from doc/source/reference/randomgen/brng/xoshiro512starstar.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/change-log.rst (renamed from doc/source/reference/randomgen/change-log.rst) | 12 | ||||
| -rw-r--r-- | doc/source/reference/random/entropy.rst (renamed from doc/source/reference/randomgen/entropy.rst) | 2 | ||||
| -rw-r--r-- | doc/source/reference/random/extending.rst (renamed from doc/source/reference/randomgen/extending.rst) | 18 | ||||
| -rw-r--r-- | doc/source/reference/random/generator.rst (renamed from doc/source/reference/randomgen/generator.rst) | 4 | ||||
| -rw-r--r-- | doc/source/reference/random/index.rst (renamed from doc/source/reference/randomgen/index.rst) | 87 | ||||
| -rw-r--r-- | doc/source/reference/random/legacy.rst (renamed from doc/source/reference/randomgen/legacy.rst) | 14 | ||||
| -rw-r--r-- | doc/source/reference/random/multithreading.rst (renamed from doc/source/reference/randomgen/multithreading.rst) | 2 | ||||
| -rw-r--r-- | doc/source/reference/random/new-or-different.rst (renamed from doc/source/reference/randomgen/new-or-different.rst) | 55 | ||||
| -rw-r--r-- | doc/source/reference/random/parallel.rst (renamed from doc/source/reference/randomgen/parallel.rst) | 26 | ||||
| -rw-r--r-- | doc/source/reference/random/performance.py (renamed from doc/source/reference/randomgen/performance.py) | 0 | ||||
| -rw-r--r-- | doc/source/reference/random/performance.rst (renamed from doc/source/reference/randomgen/performance.rst) | 16 | ||||
| -rw-r--r-- | doc/source/reference/random/references.rst (renamed from doc/source/reference/randomgen/references.rst) | 0 | ||||
| -rw-r--r-- | doc/source/reference/routines.rst | 2 |
25 files changed, 146 insertions, 140 deletions
diff --git a/doc/source/reference/randomgen/brng/dsfmt.rst b/doc/source/reference/random/brng/dsfmt.rst index f9de48d61..a47586a50 100644 --- a/doc/source/reference/randomgen/brng/dsfmt.rst +++ b/doc/source/reference/random/brng/dsfmt.rst @@ -1,9 +1,9 @@ Double SIMD Mersenne Twister (dSFMT) ------------------------------------ -.. module:: numpy.random.randomgen.dsfmt +.. module:: numpy.random.dsfmt -.. currentmodule:: numpy.random.randomgen.dsfmt +.. currentmodule:: numpy.random.dsfmt .. autoclass:: DSFMT diff --git a/doc/source/reference/randomgen/brng/index.rst b/doc/source/reference/random/brng/index.rst index aceecc792..5241f9856 100644 --- a/doc/source/reference/randomgen/brng/index.rst +++ b/doc/source/reference/random/brng/index.rst @@ -1,7 +1,9 @@ Basic Random Number Generators ------------------------------ -The random values produced by :class:`~randomgen.generator.RandomGenerator` +.. currentmodule:: numpy.random + +The random values produced by :class:`~RandomGenerator` are produced by a basic RNG. These basic RNGs do not directly provide random numbers and only contains methods used for seeding, getting or setting the state, jumping or advancing the state, and for accessing diff --git a/doc/source/reference/randomgen/brng/mt19937.rst b/doc/source/reference/random/brng/mt19937.rst index 7739e16ce..1bd3597c8 100644 --- a/doc/source/reference/randomgen/brng/mt19937.rst +++ b/doc/source/reference/random/brng/mt19937.rst @@ -1,9 +1,9 @@ Mersenne Twister (MT19937) -------------------------- -.. module:: numpy.random.randomgen.mt19937 +.. module:: numpy.random.mt19937 -.. currentmodule:: numpy.random.randomgen.mt19937 +.. currentmodule:: numpy.random.mt19937 .. autoclass:: MT19937 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/pcg32.rst b/doc/source/reference/random/brng/pcg32.rst index aaf3929e8..f079f5a8c 100644 --- a/doc/source/reference/randomgen/brng/pcg32.rst +++ b/doc/source/reference/random/brng/pcg32.rst @@ -1,9 +1,9 @@ Parallel Congruent Generator (32-bit, PCG32) -------------------------------------------- -.. module:: numpy.random.randomgen.pcg32 +.. module:: numpy.random.pcg32 -.. currentmodule:: numpy.random.randomgen.pcg32 +.. currentmodule:: numpy.random.pcg32 .. autoclass:: PCG32 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/pcg64.rst b/doc/source/reference/random/brng/pcg64.rst index 94e73e491..93f026fcb 100644 --- a/doc/source/reference/randomgen/brng/pcg64.rst +++ b/doc/source/reference/random/brng/pcg64.rst @@ -1,9 +1,9 @@ Parallel Congruent Generator (64-bit, PCG64) -------------------------------------------- -.. module:: numpy.random.randomgen.pcg64 +.. module:: numpy.random.pcg64 -.. currentmodule:: numpy.random.randomgen.pcg64 +.. currentmodule:: numpy.random.pcg64 .. autoclass:: PCG64 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/philox.rst b/doc/source/reference/random/brng/philox.rst index 091c4d3e0..c1e047c54 100644 --- a/doc/source/reference/randomgen/brng/philox.rst +++ b/doc/source/reference/random/brng/philox.rst @@ -1,9 +1,9 @@ Philox Counter-based RNG ------------------------ -.. module:: numpy.random.randomgen.philox +.. module:: numpy.random.philox -.. currentmodule:: numpy.random.randomgen.philox +.. currentmodule:: numpy.random.philox .. autoclass:: Philox :exclude-members: diff --git a/doc/source/reference/randomgen/brng/threefry.rst b/doc/source/reference/random/brng/threefry.rst index 4f5c56bae..eefe16ea0 100644 --- a/doc/source/reference/randomgen/brng/threefry.rst +++ b/doc/source/reference/random/brng/threefry.rst @@ -1,9 +1,9 @@ ThreeFry Counter-based RNG -------------------------- -.. module:: numpy.random.randomgen.threefry +.. module:: numpy.random.threefry -.. currentmodule:: numpy.random.randomgen.threefry +.. currentmodule:: numpy.random.threefry .. autoclass:: ThreeFry :exclude-members: diff --git a/doc/source/reference/randomgen/brng/threefry32.rst b/doc/source/reference/random/brng/threefry32.rst index bd85db4a7..f0d3dc281 100644 --- a/doc/source/reference/randomgen/brng/threefry32.rst +++ b/doc/source/reference/random/brng/threefry32.rst @@ -1,9 +1,9 @@ ThreeFry32 Counter-based RNG ---------------------------- -.. module:: numpy.random.randomgen.threefry32 +.. module:: numpy.random.threefry32 -.. currentmodule:: numpy.random.randomgen.threefry32 +.. currentmodule:: numpy.random.threefry32 .. autoclass:: ThreeFry32 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/xoroshiro128.rst b/doc/source/reference/random/brng/xoroshiro128.rst index 6796c4457..590552236 100644 --- a/doc/source/reference/randomgen/brng/xoroshiro128.rst +++ b/doc/source/reference/random/brng/xoroshiro128.rst @@ -1,9 +1,9 @@ Xoroshiro128+ ------------- -.. module:: numpy.random.randomgen.xoroshiro128 +.. module:: numpy.random.xoroshiro128 -.. currentmodule:: numpy.random.randomgen.xoroshiro128 +.. currentmodule:: numpy.random.xoroshiro128 .. autoclass:: Xoroshiro128 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/xorshift1024.rst b/doc/source/reference/random/brng/xorshift1024.rst index 64df7e050..24ed3df04 100644 --- a/doc/source/reference/randomgen/brng/xorshift1024.rst +++ b/doc/source/reference/random/brng/xorshift1024.rst @@ -1,9 +1,9 @@ Xorshift1024*φ -------------- -.. module:: numpy.random.randomgen.xorshift1024 +.. module:: numpy.random.xorshift1024 -.. currentmodule:: numpy.random.randomgen.xorshift1024 +.. currentmodule:: numpy.random.xorshift1024 .. autoclass:: Xorshift1024 :exclude-members: diff --git a/doc/source/reference/randomgen/brng/xoshiro256starstar.rst b/doc/source/reference/random/brng/xoshiro256starstar.rst index 7603e6f1b..85c445666 100644 --- a/doc/source/reference/randomgen/brng/xoshiro256starstar.rst +++ b/doc/source/reference/random/brng/xoshiro256starstar.rst @@ -1,9 +1,9 @@ Xoshiro256** ------------ -.. module:: numpy.random.randomgen.xoshiro256starstar +.. module:: numpy.random.xoshiro256starstar -.. currentmodule:: numpy.random.randomgen.xoshiro256starstar +.. currentmodule:: numpy.random.xoshiro256starstar .. autoclass:: Xoshiro256StarStar :exclude-members: diff --git a/doc/source/reference/randomgen/brng/xoshiro512starstar.rst b/doc/source/reference/random/brng/xoshiro512starstar.rst index 64f95f750..0c008d56e 100644 --- a/doc/source/reference/randomgen/brng/xoshiro512starstar.rst +++ b/doc/source/reference/random/brng/xoshiro512starstar.rst @@ -1,9 +1,9 @@ Xoshiro512** ------------ -.. module:: numpy.random.randomgen.xoshiro512starstar +.. module:: numpy.random.xoshiro512starstar -.. currentmodule:: numpy.random.randomgen.xoshiro512starstar +.. currentmodule:: numpy.random.xoshiro512starstar .. autoclass:: Xoshiro512StarStar :exclude-members: diff --git a/doc/source/reference/randomgen/change-log.rst b/doc/source/reference/random/change-log.rst index f791c8f54..af3c266ef 100644 --- a/doc/source/reference/randomgen/change-log.rst +++ b/doc/source/reference/random/change-log.rst @@ -1,5 +1,5 @@ -Change Log ----------- +Change Log for the original bashtage/randomgen repo +--------------------------------------------------- v1.16.1 ======= - Synchronized with upstream changes. @@ -7,12 +7,12 @@ v1.16.1 v1.16.0 ======= -- Fixed a bug that affected :class:`~randomgen.dsfmt.DSFMT` when calling - :func:`~randomgen.dsfmt.DSFMT.jump` or :func:`~randomgen.dsfmt.DSFMT.seed` +- Fixed a bug that affected ``randomgen.dsfmt.DSFMT`` when calling + ``~randomgen.dsfmt.DSFMT.jump`` or ``randomgen.dsfmt.DSFMT.seed`` that failed to reset the buffer. This resulted in upto 381 values from the previous state being used before the buffer was refilled at the new state. -- Fixed bugs in :class:`~randomgen.xoshiro512starstar.Xoshiro512StarStar` - and :class:`~randomgen.xorshift1024.Xorshift1024` where the fallback +- Fixed bugs in ``randomgen.xoshiro512starstar.Xoshiro512StarStar`` + and ``randomgen.xorshift1024.Xorshift1024`` where the fallback entropy initialization used too few bytes. This bug is unlikely to be encountered since this path is only encountered if the system random number generator fails. diff --git a/doc/source/reference/randomgen/entropy.rst b/doc/source/reference/random/entropy.rst index 6814edfbe..0664da6f9 100644 --- a/doc/source/reference/randomgen/entropy.rst +++ b/doc/source/reference/random/entropy.rst @@ -1,6 +1,6 @@ System Entropy ============== -.. module:: numpy.random.randomgen.entropy +.. module:: numpy.random.entropy .. autofunction:: random_entropy diff --git a/doc/source/reference/randomgen/extending.rst b/doc/source/reference/random/extending.rst index 64f2ddcc1..f76e3984f 100644 --- a/doc/source/reference/randomgen/extending.rst +++ b/doc/source/reference/random/extending.rst @@ -1,8 +1,10 @@ +.. currentmodule:: numpy.random + Extending --------- The basic RNGs have been designed to be extendable using standard tools for high-performance Python -- numba and Cython. -The :class:`randomgen.generator.RandomGenerator` object can also be used with +The `~RandomGenerator` object can also be used with user-provided basic RNGs as long as these export a small set of required functions. @@ -17,7 +19,7 @@ provided by ``ctypes.next_double``. .. code-block:: python - from randomgen import Xoroshiro128 + from numpy.random import Xoroshiro128 import numpy as np import numba as nb @@ -65,7 +67,7 @@ Cython ====== Cython can be used to unpack the ``PyCapsule`` provided by a basic RNG. -This example uses :class:`~randomgen.xoroshiro128.Xoroshiro128` and +This example uses `~xoroshiro128.Xoroshiro128` and ``random_gauss_zig``, the Ziggurat-based generator for normals, to fill an array. The usual caveats for writing high-performance code using Cython -- removing bounds checks and wrap around, providing array alignment information @@ -77,9 +79,9 @@ removing bounds checks and wrap around, providing array alignment information cimport numpy as np cimport cython from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer - from randomgen.common cimport * - from randomgen.distributions cimport random_gauss_zig - from randomgen.xoroshiro128 import Xoroshiro128 + from numpy.random.common cimport * + from numpy.random.distributions cimport random_gauss_zig + from numpy.random.xoroshiro128 import Xoroshiro128 @cython.boundscheck(False) @@ -137,7 +139,7 @@ examples folder. New Basic RNGs ============== -:class:`~randomgen.generator.RandomGenerator` can be used with other +`~RandomGenerator` can be used with other user-provided basic RNGs. The simplest way to write a new basic RNG is to examine the pyx file of one of the existing basic RNGs. The key structure that must be provided is the ``capsule`` which contains a ``PyCapsule`` to a @@ -158,7 +160,7 @@ used by the basic RNG. The next three are function pointers which return the next 64- and 32-bit unsigned integers, the next random double and the next raw value. This final function is used for testing and so can be set to the next 64-bit unsigned integer function if not needed. Functions inside -:class:`~randomgen.generator.RandomGenerator` use this structure as in +``RandomGenerator`` use this structure as in .. code-block:: c diff --git a/doc/source/reference/randomgen/generator.rst b/doc/source/reference/random/generator.rst index 54325f4d3..9d248732f 100644 --- a/doc/source/reference/randomgen/generator.rst +++ b/doc/source/reference/random/generator.rst @@ -1,8 +1,8 @@ -.. currentmodule:: numpy.random.randomgen +.. currentmodule:: numpy.random Random Generator ---------------- -The :class:`~RandomGenerator` provides access to +The `~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 diff --git a/doc/source/reference/randomgen/index.rst b/doc/source/reference/random/index.rst index a8b6f1c9b..1cbf5c685 100644 --- a/doc/source/reference/randomgen/index.rst +++ b/doc/source/reference/random/index.rst @@ -1,49 +1,46 @@ -.. current_module numpy.random.randomgen +.. currentmodule:: numpy.random -numpy.random.randomgen -====================== +numpy.random +============ -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. +A `~RandomGenerator` can +be initialized with a number of different Random Number Generators (RNG)s, and +exposes many different probability distributions. Quick Start ----------- -By default, `generator.RandomGenerator` uses normals provided by +By default, `RandomGenerator` uses normals provided by `xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in -`numpy.random` +`numpy.random.RandomState` .. code-block:: python - # As replacement for numpy.random - import randomgen.generator as random + # As replacement for numpy.random.RandomState + from numpy import random random.standard_normal() -`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. +`RandomGenerator` can be used as a direct replacement for +`~RandomState`, although the random values are generated by +`~xoroshiro128.Xoroshiro128`. The `RandomGenerator` holds an instance of a RNG. +It is accessable as ``gen.brng``. .. code-block:: python # As replacement for RandomState() - from randomgen import RandomGenerator + from numpy.random import RandomGenerator rg = RandomGenerator() rg.standard_normal() -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`. +Seeds can be passed to any of the basic RNGs. Here `mt19937.MT19937` is used +and the ``RandomGenerator`` is accessed via the attribute `mt19937.MT19937. +generator`. .. code-block:: python - from randomgen import MT19937 + from numpy.random import MT19937 rg = MT19937(12345).generator rg.standard_normal() @@ -59,20 +56,20 @@ 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 <~numpy.random.randomgen.RandomGenerator>` takes the +The `random generator <~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 `~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 -- `~numpy.random. -randomgen.mt19937.MT19937`, the underlying RNG in NumPy -- as the -sole argument. Note that the basic RNG must be instantized. +The ``RandomGenerator`` is the user-facing object +that is nearly identical to :class:`~.RandomState`. The canonical +method to initialize a generator passes a basic RNG -- `~mt19937.MT19937`, the +underlying RNG in NumPy -- as the sole argument. Note that the basic RNG must +be instantized. .. code-block:: python - from randomgen import RandomGenerator, MT19937 + from numpy.random import RandomGenerator, MT19937 rg = RandomGenerator(MT19937()) rg.random_sample() @@ -83,9 +80,8 @@ 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 `~numpy.random.randomgen. -mt19937.MT19937.generator` property from a basic RNG to access an embedded -random generator. +A shorthand method is also available which uses the `~mt19937.MT19937. +generator` property from a basic RNG to access an embedded random generator. .. code-block:: python @@ -97,11 +93,10 @@ What's New or Different .. warning:: The Box-Muller method used to produce NumPy's normals is no longer available - 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. + in `~RandomGenerator`. It is not possible to reproduce the random values + using ``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, `~legacy. LegacyGenerator`, has been created which can fully reproduce the sequence produced by NumPy. @@ -113,18 +108,18 @@ What's New or Different select distributions * Optional ``out`` argument that allows existing arrays to be filled for select distributions -* `~numpy.random.randomgen.entropy.random_entropy` provides access to the system +* `~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 can produce doubles, uint64s and - uint32s via CTypes (`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.ctypes`) - and CFFI (:meth:`~numpy.random.randomgen.xoroshiro128.Xoroshiro128.cffi`). + uint32s via CTypes (`~xoroshiro128.Xoroshiro128.ctypes`) + and CFFI (:meth:`~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 :ref:`Cython <randomgen_cython>`. * Support for Lemire’s method [Lemire]_ of generating uniform integers on an arbitrary interval by setting ``use_masked=True`` in - `~umpy.random.randomgen.generator.RandomGenerator.randint`. + `~RandomGenerator.randint`. See :ref:`new-or-different` for a complete list of improvements and @@ -146,7 +141,7 @@ 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 - `~numpy.random.randomgen.mt19937.MT19937.jump` function that advances the + `~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 @@ -155,24 +150,24 @@ 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 - `~numpy.random.randomgen.xoroshiro128.Xoroshiro128.jump` for details. + `~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 - `~numpy.random.randomgen.xorshift1024.Xorshift1024.jump` for details. More + `~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 - `~numpy.random.randomgen.xoshiro256starstar.Xoshirt256StarStar.jump` for + `~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 - `~numpy.random.randomgen.pcg64.PCG64.advance`. PCG-64 has a period of + `~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 diff --git a/doc/source/reference/randomgen/legacy.rst b/doc/source/reference/random/legacy.rst index 7e87f871c..b9bfabcc7 100644 --- a/doc/source/reference/randomgen/legacy.rst +++ b/doc/source/reference/random/legacy.rst @@ -1,15 +1,15 @@ Legacy Random Generation ------------------------ -The :class:`~randomgen.legacy.LegacyGenerator` provides access to -some legacy generators. These all depend on Box-Muller normals or +The :class:`~legacy.LegacyGenerator` provides access to +legacy generators. These all depend on Box-Muller normals or inverse CDF exponentials or gammas. This class should only be used if it is essential to have randoms that are identical to what would have been produced by NumPy. -:class:`~randomgen.legacy.LegacyGenerator` add additional information +:class:`~legacy.LegacyGenerator` add additional information to the state which is required when using Box-Muller normals since these are produced in pairs. It is important to use -:attr:`~randomgen.legacy.LegacyGenerator.state` +:attr:`~legacy.LegacyGenerator.state` when accessing the state so that these extra values are saved. .. warning:: @@ -27,8 +27,8 @@ when accessing the state so that these extra values are saved. .. code-block:: python - from randomgen import RandomGenerator, MT19937 - from randomgen.legacy import LegacyGenerator + from numpy.random import MT19937 + from numpy.random.legacy import LegacyGenerator from numpy.random import RandomState # Use same seed rs = RandomState(12345) @@ -47,7 +47,7 @@ when accessing the state so that these extra values are saved. lg.standard_exponential() -.. currentmodule:: numpy.random.randomgen.legacy +.. currentmodule:: numpy.random.legacy .. autoclass:: LegacyGenerator :exclude-members: diff --git a/doc/source/reference/randomgen/multithreading.rst b/doc/source/reference/random/multithreading.rst index 6efbcdbe7..f7762b73a 100644 --- a/doc/source/reference/randomgen/multithreading.rst +++ b/doc/source/reference/random/multithreading.rst @@ -16,7 +16,7 @@ that the same seed will produce the same outputs. .. code-block:: ipython - from randomgen import Xorshift1024 + from numpy.random import Xorshift1024 import multiprocessing import concurrent.futures import numpy as np diff --git a/doc/source/reference/randomgen/new-or-different.rst b/doc/source/reference/random/new-or-different.rst index 089efd6fb..7ddebb5b2 100644 --- a/doc/source/reference/randomgen/new-or-different.rst +++ b/doc/source/reference/random/new-or-different.rst @@ -1,41 +1,44 @@ .. _new-or-different: +.. currentmodule:: numpy.random + 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 `~.RandomGenerator`. It is not possible to + reproduce the exact random values using ``RandomGenerator`` for the normal + distribution or any other distribution that relies on the normal such as the + `numpy.random.gamma` or `numpy.random.standard_t`. If you require backward + compatibility, a legacy generator, `~.legacy. + LegacyGenerator`, has been created which can fully reproduce the exact byte + sequence produced by legacy code. -* :func:`~randomgen.entropy.random_entropy` provides access to the system +* `~.entropy.random_entropy` provides access to the system source of randomness that is used in cryptographic applications (e.g., ``/dev/urandom`` on Unix). * Simulate from the complex normal distribution - (:meth:`~randomgen.generator.RandomGenerator.complex_normal`) + (`~.RandomGenerator.complex_normal`) * The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy's default implementation in - :meth:`~randomgen.generator.RandomGenerator.standard_normal`, - :meth:`~randomgen.generator.RandomGenerator.standard_exponential` or - :meth:`~randomgen.generator.RandomGenerator.standard_gamma`. + `~.RandomGenerator.standard_normal`, + `~.RandomGenerator.standard_exponential` or + `~.RandomGenerator.standard_gamma`. * The Box-Muller used to produce NumPy's normals is no longer available. * 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. + uint32s via CTypes (`~.xoroshiro128.Xoroshiro128. + ctypes`) and CFFI (`~.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. .. ipython:: python - from numpy.random.randomgen import Xoroshiro128 + from numpy.random import Xoroshiro128 import numpy.random rg = Xoroshiro128().generator %timeit rg.standard_normal(100000) @@ -55,12 +58,12 @@ What's New or Different to produce either single or double prevision uniform random variables for select distributions - * Uniforms (:meth:`~randomgen.generator.RandomGenerator.random_sample` and - :meth:`~randomgen.generator.RandomGenerator.rand`) - * Normals (:meth:`~randomgen.generator.RandomGenerator.standard_normal` and - :meth:`~randomgen.generator.RandomGenerator.randn`) - * Standard Gammas (:meth:`~randomgen.generator.RandomGenerator.standard_gamma`) - * Standard Exponentials (:meth:`~randomgen.generator.RandomGenerator.standard_exponential`) + * Uniforms (`~.RandomGenerator.random_sample` and + `~.RandomGenerator.rand`) + * Normals (`~.RandomGenerator.standard_normal` and + `~.RandomGenerator.randn`) + * Standard Gammas (`~.RandomGenerator.standard_gamma`) + * Standard Exponentials (`~.RandomGenerator.standard_exponential`) .. ipython:: python @@ -72,10 +75,10 @@ What's New or Different * Optional ``out`` argument that allows existing arrays to be filled for select distributions - * Uniforms (:meth:`~randomgen.generator.RandomGenerator.random_sample`) - * Normals (:meth:`~randomgen.generator.RandomGenerator.standard_normal`) - * Standard Gammas (:meth:`~randomgen.generator.RandomGenerator.standard_gamma`) - * Standard Exponentials (:meth:`~randomgen.generator.RandomGenerator.standard_exponential`) + * Uniforms (`~.RandomGenerator.random_sample`) + * Normals (`~.RandomGenerator.standard_normal`) + * Standard Gammas (`~.RandomGenerator.standard_gamma`) + * Standard Exponentials (`~.RandomGenerator.standard_exponential`) This allows multithreading to fill large arrays in chunks using suitable PRNGs in parallel. @@ -90,7 +93,7 @@ What's New or Different * Support for Lemire’s method of generating uniform integers on an arbitrary interval by setting ``use_masked=True`` in - (:meth:`~randomgen.generator.RandomGenerator.randint`). + (`~.RandomGenerator.randint`). .. ipython:: python diff --git a/doc/source/reference/randomgen/parallel.rst b/doc/source/reference/random/parallel.rst index df6f58d75..41e47039d 100644 --- a/doc/source/reference/randomgen/parallel.rst +++ b/doc/source/reference/random/parallel.rst @@ -7,18 +7,20 @@ or distributed). .. _independent-streams: +.. currentmodule:: numpy.random + Independent Streams ------------------- -:class:`~randomgen.pcg64.PCG64`, :class:`~randomgen.threefry.ThreeFry` -and :class:`~randomgen.philox.Philox` support independent streams. This +:class:`~pcg64.PCG64`, :class:`~threefry.ThreeFry` +and :class:`~philox.Philox` support independent streams. This example shows how many streams can be created by passing in different index values in the second input while using the same seed in the first. .. code-block:: python - from randomgen.entropy import random_entropy - from randomgen import PCG64 + from numpy.random.entropy import random_entropy + from numpy.random import PCG64 entropy = random_entropy(4) # 128-bit number as a seed @@ -26,14 +28,14 @@ values in the second input while using the same seed in the first. streams = [PCG64(seed, stream) for stream in range(10)] -:class:`~randomgen.philox.Philox` and :class:`~randomgen.threefry.ThreeFry` are +:class:`~philox.Philox` and :class:`~threefry.ThreeFry` are counter-based RNGs which use a counter and key. Different keys can be used to produce independent streams. .. code-block:: python import numpy as np - from randomgen import ThreeFry + from numpy.random import ThreeFry key = random_entropy(8) key = key.view(np.uint64) @@ -81,8 +83,8 @@ overlap. .. code-block:: python - from randomgen.entropy import random_entropy - from randomgen import Xorshift1024 + from numpy.random.entropy import random_entropy + from numpy.random import Xorshift1024 entropy = random_entropy(2).astype(np.uint64) # 64-bit number as a seed @@ -97,8 +99,8 @@ overlap. Advance ******* ``advance`` can be used to jump the state an arbitrary number of steps, and so -is a more general approach than ``jump``. :class:`~randomgen.pcg64.PCG64`, -:class:`~randomgen.threefry.ThreeFry` and :class:`~randomgen.philox.Philox` +is a more general approach than ``jump``. :class:`~pcg64.PCG64`, +:class:`~threefry.ThreeFry` and :class:`~philox.Philox` support ``advance``, and since these also support independent streams, it is not usually necessary to use ``advance``. @@ -119,12 +121,12 @@ This occurs for two reasons: Advancing the PRNG state resets any pre-computed random numbers. This is required to ensure exact reproducibility. -This example uses ``advance`` to advance a :class:`~randomgen.pcg64.PCG64` +This example uses ``advance`` to advance a :class:`~pcg64.PCG64` generator 2 ** 127 steps to set a sequence of random number generators. .. code-block:: python - from randomgen import PCG64 + from numpy.random import PCG64 brng = PCG64() brng_copy = PCG64() brng_copy.state = brng.state diff --git a/doc/source/reference/randomgen/performance.py b/doc/source/reference/random/performance.py index 12cbbc5d3..12cbbc5d3 100644 --- a/doc/source/reference/randomgen/performance.py +++ b/doc/source/reference/random/performance.py diff --git a/doc/source/reference/randomgen/performance.rst b/doc/source/reference/random/performance.rst index 2dfb32101..321d49454 100644 --- a/doc/source/reference/randomgen/performance.rst +++ b/doc/source/reference/random/performance.rst @@ -1,26 +1,28 @@ Performance ----------- -.. py:module:: randomgen +.. py:module:: numpy.random + +.. currentmodule:: numpy.random Recommendation ************** The recommended generator for single use is -:class:`~randomgen.xoroshiro128.Xoroshiro128`. The recommended generator +:class:`~xoroshiro128.Xoroshiro128`. The recommended generator for use in large-scale parallel applications is -:class:`~randomgen.xorshift1024.Xorshift1024` +:class:`~xorshift1024.Xorshift1024` where the `jump` method is used to advance the state. For very large scale applications -- requiring 1,000+ independent streams, -:class:`~randomgen.pcg64.PCG64` or :class:`~randomgen.threefry.ThreeFry` are +:class:`~pcg64.PCG64` or :class:`~threefry.ThreeFry` are the best choices. Timings ******* The timings below are the time in ms to produce 1,000,000 random values from a -specific distribution. :class:`~randomgen.xoroshiro128.Xoroshiro128` is the -fastest, followed by :class:`~randomgen.xorshift1024.Xorshift1024` and -:class:`~randomgen.pcg64.PCG64`. The original :class:`~randomgen.mt19937.MT19937` +specific distribution. :class:`~xoroshiro128.Xoroshiro128` is the +fastest, followed by :class:`~xorshift1024.Xorshift1024` and +:class:`~pcg64.PCG64`. The original :class:`~mt19937.MT19937` generator is much slower since it requires 2 32-bit values to equal the output of the faster generators. diff --git a/doc/source/reference/randomgen/references.rst b/doc/source/reference/random/references.rst index 0dc99868f..0dc99868f 100644 --- a/doc/source/reference/randomgen/references.rst +++ b/doc/source/reference/random/references.rst diff --git a/doc/source/reference/routines.rst b/doc/source/reference/routines.rst index 0ed99cbda..e3fbc2be6 100644 --- a/doc/source/reference/routines.rst +++ b/doc/source/reference/routines.rst @@ -42,7 +42,7 @@ indentation. routines.padding routines.polynomials routines.random - randomgen/index + random/index routines.set routines.sort routines.statistics |