8000 Merge pull request #14948 from mattip/document-random · numpy/numpy@d379088 · GitHub
[go: up one dir, main page]
Skip to content

Commit d379088

Browse files
charrischarris
authored
Merge pull request #14948 from mattip/document-random
DOC, API: add random.__init__.pxd and document random.* functions
2 parents b491b98 + 0a5e428 commit d379088

File tree

14 files changed

+426
-66
lines changed

14 files changed

+426
-66
lines changed

‎doc/source/reference/random/index.rst

Lines changed: 43 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -22,34 +22,44 @@ Since Numpy version 1.17.0 the Generator can be initialized with a
2222
number of different BitGenerators. It exposes many different probability
2323
distributions. See `NEP 19 <https://www.numpy.org/neps/
2424
nep-0019-rng-policy.html>`_ for context on the updated random Numpy number
25-
routines. The legacy `.RandomState` random number routines are still
25+
routines. The legacy `RandomState` random number routines are still
2626
available, but limited to a single BitGenerator.
2727

28-
For convenience and backward compatibility, a single `~.RandomState`
28+
For convenience and backward compatibility, a single `RandomState`
2929
instance's methods are imported into the numpy.random namespace, see
3030
:ref:`legacy` for the complete list.
3131

32+
.. _random-quick-start:
33+
3234
Quick Start
3335
-----------
3436

35-
By default, `~Generator` uses bits provided by `PCG64` which
36-
has better statistical properties than the legacy mt19937 random
37-
number generator in `~.RandomState`.
37+
Call `default_rng` to get a new instance of a `Generator`, then call its
38+
methods to obtain samples from different distributions. By default,
39+
`Generator` uses bits provided by `PCG64` which has better statistical
40+
properties than the legacy `MT19937` used in `RandomState`.
3841

3942
.. code-block:: python
4043
41-
# Uses the old numpy.random.RandomState
44+
# Do this
45+
from numpy.random import default_rng
46+
rng = default_rng()
47+
vals = rng.standard_normal(10)
48+
more_vals = rng.standard_normal(10)
49+
50+
# instead of this
4251
from numpy import random
43-
random.standard_normal()
52+
vals = random.standard_normal(10)
53+
more_vals = random.standard_normal(10)
4454
45-
`~Generator` can be used as a replacement for `~.RandomState`. Both class
46-
instances now hold a internal `BitGenerator` instance to provide the bit
55+
`Generator` can be used as a replacement for `RandomState`. Both class
56+
instances hold a internal `BitGenerator` instance to provide the bit
4757
stream, it is accessible as ``gen.bit_generator``. Some long-overdue API
4858
cleanup means that legacy and compatibility methods have been removed from
49-
`~.Generator`
59+
`Generator`
5060

5161
=================== ============== ============
52-
`~.RandomState` `~.Generator` Notes
62+
`RandomState` `Generator` Notes
5363
------------------- -------------- ------------
5464
``random_sample``, ``random`` Compatible with `random.random`
5565
``rand``
@@ -58,21 +68,12 @@ cleanup means that legacy and compatibility methods have been removed from
5868
``random_integers``
5969
------------------- -------------- ------------
6070
``tomaxint`` removed Use ``integers(0, np.iinfo(np.int_).max,``
61-
``endpoint=False)``
71+
``endpoint=False)``
6272
------------------- -------------- ------------
63-
``seed`` removed Use `~.SeedSequence.spawn`
73+
``seed`` removed Use `SeedSequence.spawn`
6474
=================== ============== ============
6575

66-
See `new-or-different` for more information
67-
68-
.. code-block:: python
69-
70-
# As replacement for RandomState(); default_rng() instantiates Generator with
71-
# the default PCG64 BitGenerator.
72-
from numpy.random import default_rng
73-
rg = default_rng()
74-
rg.standard_normal()
75-
rg.bit_generator
76+
See :ref:`new-or-different` for more information
7677

7778
Something like the following code can be used to support both ``RandomState``
7879
and ``Generator``, with the understanding that the interfaces are slightly
@@ -87,9 +88,9 @@ different
8788
a = rg_integers(1000)
8889
8990
Seeds can be passed to any of the BitGenerators. The provided value is mixed
90-
via `~.SeedSequence` to spread a possible sequence of seeds across a wider
91-
range of initialization states for the BitGenerator. Here `~.PCG64` is used and
92-
is wrapped with a `~.Generator`.
91+
via `SeedSequence` to spread a possible sequence of seeds across a wider
92+
range of initialization states for the BitGenerator. Here `PCG64` is used and
93+
is wrapped with a `Generator`.
9394

9495
.. code-block:: python
9596
@@ -100,7 +101,7 @@ is wrapped with a `~.Generator`.
100101
Introduction
101102
------------
102103
The new infrastructure takes a different approach to producing random numbers
103-
from the `~.RandomState` object. Random number generation is separated into
104+
from the `RandomState` object. Random number generation is separated into
104105
two components, a bit generator and a random generator.
105106

106107
The `BitGenerator` has a limited set of responsibilities. It manages state
@@ -113,8 +114,8 @@ distributions, e.g., simulated normal random values. This structure allows
113114
alternative bit generators to be used with little code duplication.
114115

115116
The `Generator` is the user-facing object that is nearly identical to
116-
`.RandomState`. The canonical method to initialize a generator passes a
117-
`~.PCG64` bit generator as the sole argument.
117+
`RandomState`. The canonical method to initialize a generator passes a
118+
`PCG64` bit generator as the sole argument.
118119

119120
.. code-block:: python
120121
@@ -139,9 +140,9 @@ What's New or Different
139140
The Box-Muller method used to produce NumPy's normals is no longer available
140141
in `Generator`. It is not possible to reproduce the exact random
141142
values using Generator for the normal distribution or any other
142-
distribution that relies on the normal such as the `.RandomState.gamma` or
143-
`.RandomState.standard_t`. If you require bitwise backward compatible
144-
streams, use `.RandomState`.
143+
distribution that relies on the normal such as the `RandomState.gamma` or
144+
`RandomState.standard_t`. If you require bitwise backward compatible
145+
streams, use `RandomState`.
145146

146147
* The Generator's normal, exponential and gamma functions use 256-step Ziggurat
147148
methods which are 2-10 times faster than NumPy's Box-Muller or inverse CDF
@@ -152,20 +153,20 @@ What's New or Different
152153
* Optional ``out`` argument that allows existing arrays to be filled for
153154
select distributions
154155
* All BitGenerators can produce doubles, uint64s and uint32s via CTypes
155-
(`~.PCG64.ctypes`) and CFFI (`~.PCG64.cffi`). This allows the bit generators
156+
(`PCG64.ctypes`) and CFFI (`PCG64.cffi`). This allows the bit generators
156157
to be used in numba.
157158
* The bit generators can be used in downstream projects via
158159
:ref:`Cython <random_cython>`.
159-
* `~.Generator.integers` is now the canonical way to generate integer
160+
* `Generator.integers` is now the canonical way to generate integer
160161
random numbers from a discrete uniform distribution. The ``rand`` and
161-
``randn`` methods are only available through the legacy `~.RandomState`.
162+
``randn`` methods are only available through the legacy `RandomState`.
162163
The ``endpoint`` keyword can be used to specify open or closed intervals.
163164
This replaces both ``randint`` and the deprecated ``random_integers``.
164-
* `~.Generator.random` is now the canonical way to generate floating-point
165-
random numbers, which replaces `.RandomState.random_sample`,
166-
`.RandomState.sample`, and `.RandomState.ranf`. This is consistent with
165+
* `Generator.random` is now the canonical way to generate floating-point
166+
random numbers, which replaces `RandomState.random_sample`,
167+
`RandomState.sample`, and `RandomState.ranf`. This is consistent with
167168
Python's `random.random`.
168-
* All BitGenerators in numpy use `~SeedSequence` to convert seeds into
169+
* All BitGenerators in numpy use `SeedSequence` to convert seeds into
169170
initialized states.
170171

171172
See :ref:`new-or-different` for a complete list of improvements and
@@ -202,8 +203,9 @@ Features
202203
c-api
203204
Examples of using Numba, Cython, CFFI <extending>
204205

205-
Original Source
206-
~~~~~~~~~~~~~~~
206+
Original Source of the Generator and BitGenerators
207+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
207208

208209
This package was developed independently of NumPy and was integrated in version
209210
1.17.0. The original repo is at https://github.com/bashtage/randomgen.
211+

‎doc/source/reference/random/legacy.rst

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,3 +121,71 @@ Distributions
121121
~RandomState.wald
122122
~RandomState.weibull
123123
~RandomState.zipf
124+
125+
Functions in `numpy.random`
126+
===========================
127+
Many of the RandomState methods above are exported as functions in
128+
`numpy.random` This usage is discouraged, as it is implemented via a gloabl
129+
`RandomState` instance which is not advised on two counts:
130+
131+
- It uses global state, which means results will change as the code changes
132+
133+
- It uses a `RandomState` rather than the more modern `Generator`.
134+
135+
For backward compatible legacy reasons, we cannot change this. See
136+
`random-quick-start`.
137+
138+
.. autosummary::
139+
:toctree: generated/
140+
141+
beta
142+
binomial
143+
bytes
144+
chisquare
145+
choice
146+
dirichlet
147+
exponential
148+
f
149+
gamma
150+
geometric
151+
get_state
152+
gumbel
153+
hypergeometric
154+
laplace
155+
logistic
156+
lognormal
157+
logseries
158+
multinomial
159+
multivariate_normal
160+
negative_binomial
161+
noncentral_chisquare
162+
noncentral_f
163+
normal
164+
pareto
165+
permutation
166+
poisson
167+
power
168+
rand
169+
randint
170+
randn
171+
random
172+
random_integers
173+
random_sample
174+
ranf
175+
rayleigh
176+
sample
177+
seed
178+
set_state
179+
shuffle
180+
standard_cauchy
181+
standard_exponential
182+
standard_gamma
183+
standard_normal
184+
standard_t
185+
triangular
186+
uniform
187+
vonmises
188+
wald
189+
weibull
190+
zipf
191+

‎numpy/random/__init__.pxd

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
cimport numpy as np
2+
from libc.stdint cimport uint32_t, uint64_t
3+
4+
cdef extern from "numpy/random/bitgen.h":
5+
struct bitgen:
6+
void *state
7+
uint64_t (*next_uint64)(void *st) nogil
8+
uint32_t (*next_uint32)(void *st) nogil
9+
double (*next_double)(void *st) nogil
10+
uint64_t (*next_raw)(void *st) nogil
11+
12+
ctypedef bitgen bitgen_t
13+
14+
from numpy.random._bit_generator cimport BitGenerator, SeedSequence

‎numpy/random/_bounded_integers.pxd.in

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import numpy as np
44
cimport numpy as np
55
ctypedef np.npy_bool bool_t
66

7-
from ._bit_generator cimport bitgen_t
7+
from numpy.random cimport bitgen_t
88

99
cdef inline uint64_t _gen_mask(uint64_t max_val) nogil:
1010
"""Mask generator for use in bounded random numbers"""

‎numpy/random/_common.pxd

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ from libc.stdint cimport uint32_t, uint64_t, int32_t, int64_t
55
import numpy as np
66
cimport numpy as np
77

8-
from ._bit_generator cimport bitgen_t
8+
from numpy.random cimport bitgen_t
99

1010
cdef double POISSON_LAM_MAX
1111
cdef double LEGACY_POISSON_LAM_MAX

‎numpy/random/_examples/cython/extending.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import numpy as np
88
cimport numpy as np
99
cimport cython
1010

11-
from numpy.random._bit_generator cimport bitgen_t
11+
from numpy.random cimport bitgen_t
1212
from numpy.random import PCG64
1313

1414
np.import_array()

‎numpy/random/_examples/cython/extending_distributions.pyx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,7 @@ cimport numpy as np
88
cimport cython
99
from cpython.pycapsule cimport PyCapsule_IsValid, PyCapsule_GetPointer
1010
from libc.stdint cimport uint16_t, uint64_t
11-
from numpy.random._bit_generator cimport bitgen_t
12-
11+
from numpy.random cimport bitgen_t
1312
from numpy.random import PCG64
1413

1514

@@ -72,3 +71,4 @@ def uint10_uniforms(Py_ssize_t n):
7271

7372
randoms = np.asarray(random_values)
7473
return randoms
74+

‎numpy/random/_generator.pyx

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ from ._bounded_integers cimport (_rand_bool, _rand_int32, _rand_int64,
1919
_rand_uint8, _gen_mask)
2020
from ._bounded_integers import _integers_types
2121
from ._pcg64 import PCG64
22-
from ._bit_generator cimport bitgen_t
22+
from numpy.random cimport bitgen_t
2323
from ._common cimport (POISSON_LAM_MAX, CONS_POSITIVE, CONS_NONE,
2424
CONS_NON_NEGATIVE, CONS_BOUNDED_0_1, CONS_BOUNDED_GT_0_1,
2525
CONS_GT_1, CONS_POSITIVE_NOT_NAN, CONS_POISSON,
@@ -1004,19 +1004,19 @@ cdef class Generator:
10041004
A floating-point array of shape ``size`` of drawn samples, or a
10051005
single sample if ``size`` was not specified.
10061006
1007+
See Also
1008+
--------
1009+
normal :
1010+
Equivalent function with additional ``loc`` and ``scale`` arguments
1011+
for setting the mean and standard deviation.
1012+
10071013
Notes
10081014
-----
10091015
For random samples from :math:`N(\\mu, \\sigma^2)`, use one of::
10101016
10111017
mu + sigma * gen.standard_normal(size=...)
10121018
gen.normal(mu, sigma, size=...)
10131019
1014-
See Also
1015-
--------
1016-
normal :
1017-
Equivalent function with additional ``loc`` and ``scale`` arguments
1018-
for setting the mean and standard deviation.
1019-
10201020
Examples
10211021
--------
10221022
>>> rng = np.random.default_rng()

‎numpy/random/_mt19937.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import numpy as np
44
cimport numpy as np
55

66
from libc.stdint cimport uint32_t, uint64_t
7-
from ._bit_generator cimport BitGenerator, SeedSequence
7+
from numpy.random cimport BitGenerator, SeedSequence
88

99
__all__ = ['MT19937']
1010

‎numpy/random/_pcg64.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ cimport numpy as np
33

44
from libc.stdint cimport uint32_t, uint64_t
55
from ._common cimport uint64_to_double, wrap_int
6-
from ._bit_generator cimport BitGenerator
6+
from numpy.random cimport BitGenerator
77

88
__all__ = ['PCG64']
99

‎numpy/random/_philox.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ cimport numpy as np
1010

1111
from libc.stdint cimport uint32_t, uint64_t
1212
from ._common cimport uint64_to_double, int_to_array, wrap_int
13-
from ._bit_generator cimport BitGenerator
13+
from numpy.random cimport BitGenerator
1414

1515
__all__ = ['Philox']
1616

‎numpy/random/_sfc64.pyx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ cimport numpy as np
33

44
from libc.stdint cimport uint32_t, uint64_t
55
from ._common cimport uint64_to_double
6-
from ._bit_generator cimport BitGenerator
6+
from numpy.random cimport BitGenerator
77

88
__all__ = ['SFC64']
99

0 commit comments

Comments
 (0)
0