8000 ENH: Rename seed_seq argument to seed. · rkern/numpy@73ebbbb · GitHub
[go: up one dir, main page]
Skip to content

Commit 73ebbbb

Browse files
rkernrkern
committed
ENH: Rename seed_seq argument to seed.
The most common use will certainly be to pass in an integer seed, so I want to make sure that we talk in terms of "seeds" first and foremost. I don't want to overload people with new concepts and terminology right out of the gate.
1 parent 34224c1 commit 73ebbbb

File tree

5 files changed

+64
-49
lines changed

5 files changed

+64
-49
lines changed

‎numpy/random/bit_generator.pyx

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ def _coerce_to_uint32_array(x):
116116
Examples
117117
--------
118118
>>> import numpy as np
119-
>>> from seed_seq import _coerce_to_uint32_array
119+
>>> from np.random.bit_generator import _coerce_to_uint32_array
120120
>>> _coerce_to_uint32_array(12345)
121121
array([12345], dtype=uint32)
122122
>>> _coerce_to_uint32_array('12345')
@@ -467,17 +467,20 @@ ISpawnableSeedSequence.register(SeedSequence)
467467

468468
cdef class BitGenerator():
469469
"""
470-
BitGenerator(seed_seq=None)
470+
BitGenerator(seed=None)
471471
472472
Base Class for generic BitGenerators, which provide a stream
473473
of random bits based on different algorithms. Must be overridden.
474474
475475
Parameters
476476
----------
477-
seed_seq : {None, ISeedSequence, int, sequence[int]}, optional
478-
A ISeedSequence to initialize the BitGenerator. If None, one will be
479-
created. If an int or a sequence of ints, it will be used as the
480-
entropy for creating a SeedSequence.
477+
seed : {None, int, array_like[ints], ISeedSequence}, optional
478+
A seed to initialize the `BitGenerator`. If None, then fresh,
479+
unpredictable entropy will be pulled from the OS. If an ``int`` or
480+
``array_like[ints]`` is passed, then it will be passed to
481+
`SeedSequence` to derive the initial `BitGenerator` state. One may also
482+
pass in an implementor of the `ISeedSequence` interface like
483+
`SeedSequence`.
481484
482485
Attributes
483486
----------
@@ -492,7 +495,7 @@ cdef class BitGenerator():
492495
SeedSequence
493496
"""
494497

495-
def __init__(self, seed_seq=None):
498+
def __init__(self, seed=None):
496499
self.lock = Lock()
497500
self._bitgen.state = <void *>0
498501
if type(self) is BitGenerator:
@@ -503,9 +506,9 @@ cdef class BitGenerator():
503506

504507
cdef const char *name = "BitGenerator"
505508
self.capsule = PyCapsule_New(<void *>&self._bitgen, name, NULL)
506-
if not isinstance(seed_seq, ISeedSequence):
507-
seed_seq = SeedSequence(seed_seq)
508-
self._seed_seq = seed_seq
509+
if not isinstance(seed, ISeedSequence):
510+
seed = SeedSequence(seed)
511+
self._seed_seq = seed
509512

510513
# Pickling support:
511514
def __getstate__(self):

‎numpy/random/mt19937.pyx

Copy file name to clipboard
Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,16 +43,19 @@ cdef uint64_t mt19937_raw(void *st) nogil:
4343

4444
cdef class MT19937(BitGenerator):
4545
"""
46-
MT19937(seed_seq=None)
46+
MT19937(seed=None)
4747
4848
Container for the Mersenne Twister pseudo-random number generator.
4949
5050
Parameters
5151
----------
52-
seed_seq : {None, SeedSequence, int, array_like[ints]}, optional
53-
A SeedSequence to initialize the BitGenerator. If None, one will be
54-
created. If an int or array_like[ints], it will be used as the entropy
55-
for creating a SeedSequence.
52+
seed : {None, int, array_like[ints], ISeedSequence}, optional
53+
A seed to initialize the `BitGenerator`. If None, then fresh,
54+
unpredictable entropy will be pulled from the OS. If an ``int`` or
55+
``array_like[ints]`` is passed, then it will be passed to
56+
`SeedSequence` to derive the initial `BitGenerator` state. One may also
57+
pass in an implementor of the `ISeedSequence` interface like
58+
`SeedSequence`.
5659
5760
Attributes
5861
----------

‎numpy/random/pcg64.pyx

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,13 @@ cdef class PCG64(BitGenerator):
4343
4444
Parameters
4545
----------
46-
seed_seq : {None, SeedSequence, int, array_like[ints]}, optional
47-
A SeedSequence to initialize the BitGenerator. If None, one will be
48-
created. If an int or array_like[ints], it will be used as the entropy
49-
for creating a SeedSequence.
46+
seed : {None, int, array_like[ints], ISeedSequence}, optional
47+
A seed to initialize the `BitGenerator`. If None, then fresh,
48+
unpredictable entropy will be pulled from the OS. If an ``int`` or
49+
``array_like[ints]`` is passed, then it will be passed to
50+
`SeedSequence` to derive the initial `BitGenerator` state. One may also
51+
pass in an implementor of the `ISeedSequence` interface like
52+
`SeedSequence`.
5053
5154
Notes
5255
-----
@@ -98,8 +101,8 @@ cdef class PCG64(BitGenerator):
98101
cdef pcg64_state rng_state
99102
cdef pcg64_random_t pcg64_random_state
100103

101-
def __init__(self, seed_seq=None):
102-
BitGenerator.__init__(self, seed_seq)
104+
def __init__(self, seed=None):
105+
BitGenerator.__init__(self, seed)
103106
self.rng_state.pcg_state = &self.pcg64_random_state
104107

105108
self._bitgen.state = <void *>&self.rng_state

‎numpy/random/philox.pyx

Lines changed: 24 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -62,18 +62,21 @@ cdef class Philox(BitGenerator):
6262
6363
Parameters
6464
----------
65-
seed_seq : {None, SeedSequence, int, array_like[ints]}, optional
66-
A SeedSequence to initialize the BitGenerator. If None, one will be
67-
created. If an int or array_like[ints], it will be used as the entropy
68-
for creating a SeedSequence.
65+
seed : {None, int, array_like[ints], ISeedSequence}, optional
66+
A seed to initialize the `BitGenerator`. If None, then fresh,
67+
unpredictable entropy will be pulled from the OS. If an ``int`` or
68+
``array_like[ints]`` is passed, then it will be passed to
69+
`SeedSequence` to derive the initial `BitGenerator` state. One may also
70+
pass in an implementor of the `ISeedSequence` interface like
71+
`SeedSequence`.
6972
counter : {None, int, array_like}, optional
7073
Counter to use in the Philox state. Can be either
7174
a Python int (long in 2.x) in [0, 2**256) or a 4-element uint64 array.
7275
If not provided, the RNG is initialized at 0.
7376
key : {None, int, array_like}, optional
7477
Key to use in the Philox state. Unlike seed, the value in key is
75-
directly set. Can be either a Python int (long in 2.x) in [0, 2**128)
76-
or a 2-element uint64 array. `key` and `seed` cannot both be used.
78+
directly set. Can be either a Python int in [0, 2**128) or a 2-element
79+
uint64 array. `key` and `seed` cannot both be used.
7780
7881
Attributes
7982
----------
@@ -99,18 +102,16 @@ cdef class Philox(BitGenerator):
99102
100103
**State and Seeding**
101104
102-
The ``Philox`` state vector consists of a 2 256-bit values encoded as
103-
4-element uint64 arrays. One is a counter which is incremented by 1 for
104-
every 4 64-bit randoms produced. The second is a key which determined
105-
the sequence produced. Using different keys produces independent
106-
sequences.
105+
The ``Philox`` state vector consists of a 256-bit counter encoded as
106+
a 4-element uint64 array and a 128-bit key encoded as a 2-element uint64
107+
array. The counter is incremented by 1 for every 4 64-bit randoms produced.
108+
The key which determines the sequence produced. Using different keys
109+
produces independent sequences.
107110
108-
``Philox`` is seeded using either a single 64-bit unsigned integer
109-
or a vector of 64-bit unsigned integers. In either case, the seed is
110-
used as an input for a second random number generator,
111-
SplitMix64, and the output of this PRNG function is used as the initial state.
112-
Using a single 64-bit value for the seed can only initialize a small range of
113-
the possible initial state values.
111+
By default, providing a ``seed`` value will derive the 128-bit key using
112+
`SeedSequence`; the counter will be initialized to 0. On the other hand,
113+
one may omit the ``seed`` and provide the ``key`` and/or ``counter``
114+
directly if one wishes to manually control the key.
114115
115116
**Parallel Features**
116117
@@ -136,7 +137,7 @@ cdef class Philox(BitGenerator):
136137
137138
**Compatibility Guarantee**
138139
139-
``Philox`` makes a guarantee that a fixed seed and will always produce
140+
``Philox`` makes a guarantee that a fixed seed will always produce
140141
the same random integer stream.
141142
142143
Examples
@@ -157,16 +158,18 @@ cdef class Philox(BitGenerator):
157158
cdef philox4x64_key_t philox_key
158159
cdef philox4x64_ctr_t philox_ctr
159160

160-
def __init__(self, seed_seq=None, counter=None, key=None):
161-
if seed_seq is not None and key is not None:
161+
def __init__(self, seed=None, counter=None, key=None):
162+
if seed is not None and key is not None:
162163
raise ValueError('seed and key cannot be both used')
163-
BitGenerator.__init__(self, seed_seq)
164+
BitGenerator.__init__(self, seed)
164165
self.rng_state.ctr = &self.philox_ctr
165166
self.rng_state.key = &self.philox_key
166167
if key is not None:
167168
key = int_to_array(key, 'key', 128, 64)
168169
for i in range(2):
169170
self.rng_state.key.v[i] = key[i]
171+
# The seed sequence is invalid.
172+
self._seed_seq = None
170173
else:
171174
key = self._seed_seq.generate_state(2, np.uint64)
172175
for i in range(2):

‎numpy/random/sfc64.pyx

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -32,16 +32,19 @@ cdef double sfc64_double(void* st) nogil:
3232

3333
cdef class SFC64(BitGenerator):
3434
"""
35-
SFC64(seed_seq=None)
35+
SFC64(seed=None)
3636
3737
BitGenerator for Chris Doty-Humphrey's Small Fast Chaotic PRNG.
3838
3939
Parameters
4040
----------
41-
seed_seq : {None, ISeedSequence, int, array_like[ints]}, optional
42-
A SeedSequence to initialize the BitGenerator. If None, one will be
43-
created. If an int or array_like[ints], it will be used as the entropy
44-
for creating a SeedSequence.
41+
seed : {None, int, array_like[ints], ISeedSequence}, optional
42+
A seed to initialize the `BitGenerator`. If None, then fresh,
43+
unpredictable entropy will be pulled from the OS. If an ``int`` or
44+
``array_like[ints]`` is passed, then it will be passed to
45+
`SeedSequence` to derive the initial `BitGenerator` state. One may also
46+
pass in an implementor of the `ISeedSequence` interface like
47+
`SeedSequence`.
4548
4649
Notes
4750
-----
@@ -72,8 +75,8 @@ cdef class SFC64(BitGenerator):
7275

7376
cdef sfc64_state rng_state
7477

75-
def __init__(self, seed_seq=None):
76-
BitGenerator.__init__(self, seed_seq)
78+
def __init__(self, seed=None):
79+
BitGenerator.__init__(self, seed)
7780
self._bitgen.state = <void *>&self.rng_state
7881
self._bitgen.next_uint64 = &sfc64_uint64
7982
self._bitgen.next_uint32 = &sfc64_uint32

0 commit comments

Comments
 (0)
0