1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
.. _numpyrandom:
.. currentmodule:: numpy.random
numpy.random
============
Numpy's random number routines produce psuedo random numbers using
combinations of a `BitGenerator` to create sequences and a `Generator`
to use those sequences to sample from different statistical distributions:
* BitGenerators: Objects that generate random numbers. These are typically
unsigned integer words filled with sequences of either 32 or 64 random bits.
* Generators: Objects that transform sequences of random bits from a
BitGenerator into sequences of numbers that follow a specific probability
distribution (such as uniform, Normal or Binomial) within a specified
interval.
Since Numpy version 1.17.0 the Generator can be initialized with a
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.
For convenience and backward compatibility, a single `RandomState`
instance's methods are imported into the numpy.random namespace, see
:ref:`legacy` for the complete list.
Quick Start
-----------
By default, `Generator` uses normals provided by `xoshiro256.Xoshiro256`
which will be faster than the legacy methods in `RandomState`
.. code-block:: python
# Uses the old numpy.random.RandomState
from numpy import random
random.standard_normal()
`Generator` can be used as a direct replacement for `~RandomState`, although
the random values are generated by `~xoshiro256.Xoshiro256`. The
`Generator` holds an instance of a BitGenerator. It is accessable as
``gen.bit_generator``.
.. code-block:: python
# As replacement for RandomState()
from numpy.random import Generator
rg = Generator()
rg.standard_normal()
rg.bit_generator
Seeds can be passed to any of the BitGenerators. Here `mt19937.MT19937` is used
and is the wrapped with a `~.Generator`.
.. code-block:: python
from numpy.random import Generator, MT19937
rg = Generator(MT19937(12345))
rg.standard_normal()
Introduction
------------
RandomGen takes a different approach to producing random numbers from the
`RandomState` object. Random number generation is separated into two
components, a bit generator and a random generator.
The bit generator has a limited set of responsibilities. It manages state
and provides functions to produce random doubles and random unsigned 32- and
64-bit values. The bit generator also handles all seeding which varies with
different bit generators.
The `random generator <Generator>` takes the
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
`~mt19937.MT19937` bit generator, the underlying bit generator in Python -- as
the sole argument. Note that the BitGenerator must be instantiated.
.. code-block:: python
from numpy.random import Generator, MT19937
rg = Generator(MT19937())
rg.random()
Seed information is directly passed to the bit generator.
.. code-block:: python
rg = Generator(MT19937(12345))
rg.random()
What's New or Different
~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
The Box-Muller method used to produce NumPy's normals is no longer available
in `Generator`. It is not possible to reproduce the exact random
values using Generator 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 bitwise backward compatible
streams, use `RandomState`.
* The Generator's normal, exponential and gamma functions use 256-step Ziggurat
methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
implementations.
* Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64``
to produce either single or double prevision uniform random variables for
select distributions
* Optional ``out`` argument that allows existing arrays to be filled for
select distributions
* `~entropy.random_entropy` provides access to the system
source of randomness that is used in cryptographic applications (e.g.,
``/dev/urandom`` on Unix).
* All BitGenerators can produce doubles, uint64s and uint32s via CTypes
(`~xoshiro256.Xoshiro256.ctypes`) and CFFI
(:meth:`~xoshiro256.Xoshiro256.cffi`). This allows the bit generators to
be used in numba.
* The bit generators can be used in downstream projects via
:ref:`Cython <randomgen_cython>`.
* `~.Generator.integers` is now the canonical way to generate integer
random numbers from a discrete uniform distribution. The ``rand`` and
``randn`` methods are only availabe through the legacy `~.RandomState`.
The ``endpoint`` keyword can be used to specify open or closed intervals.
This replaces both ``randint`` and the deprecated ``random_integers``.
* `~.Generator.random` is now the canonical way to generate floating-point
random numbers, which replaces `random_sample`, `sample`, and `ranf`. This
is consistent with Python's `random.random`.
See :ref:`new-or-different` for a complete list of improvements and
differences from the traditional ``Randomstate``.
Parallel Generation
~~~~~~~~~~~~~~~~~~~
The included generators can be used in parallel, distributed applications in
one of two ways:
* :ref:`independent-streams`
* :ref:`jump-and-advance`
Supported BitGenerators
-----------------------
The included BitGenerators are:
* MT19937 - The standard Python BitGenerator. Produces identical results to
Python using the same seed/state. Adds a `~mt19937.MT19937.jumped` function
that returns a new generator with state as-if ``2**128`` draws have been made.
* 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 ``jumped`` and so can
be used in parallel applications. See the `dSFMT authors' page`_.
* Xorshiro256** and Xorshiro512** - The most recently introduced XOR,
shift, and rotate generator. Supports ``jumped`` and so can be used in
parallel applications. See the documentation for
`~xoshiro256.Xoshirt256.jumped` for details. More information about these bit
generators is available at the `xorshift, xoroshiro and xoshiro authors'
page`_.
* 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 bit generators.
.. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/
.. _`PCG author's page`: http://www.pcg-random.org/
.. _`xorshift, xoroshiro and xoshiro authors' page`: http://xoroshiro.di.unimi.it/
.. _`Random123`: https://www.deshawresearch.com/resources_random123.html
Generator
---------
.. toctree::
:maxdepth: 1
generator
legacy mtrand <legacy>
BitGenerators
-------------
.. toctree::
:maxdepth: 1
BitGenerators <bit_generators/index>
Features
--------
.. toctree::
:maxdepth: 2
Parallel Applications <parallel>
Multithreaded Generation <multithreading>
new-or-different
Comparing Performance <performance>
extending
Reading System Entropy <entropy>
Original Source
~~~~~~~~~~~~~~~
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.
|
