Philox Counter-based RNG¶
- class numpy.random.Philox(seed=None, counter=None, key=None)¶
Container for the Philox (4x64) pseudo-random number generator.
- Parameters
- seed{None, int, array_like[ints], SeedSequence}, optional
A seed to initialize the
BitGenerator
. If None, then fresh, unpredictable entropy will be pulled from the OS. If anint
orarray_like[ints]
is passed, then it will be passed toSeedSequence
to derive the initialBitGenerator
state. One may also pass in aSeedSequence
instance.- counter{None, int, array_like}, optional
Counter to use in the Philox state. Can be either a Python int (long in 2.x) in [0, 2**256) or a 4-element uint64 array. If not provided, the RNG is initialized at 0.
- key{None, int, array_like}, optional
Key to use in the Philox state. Unlike
seed
, the value in key is directly set. Can be either a Python int in [0, 2**128) or a 2-element uint64 array. key andseed
cannot both be used.
Notes
Philox is a 64-bit PRNG that uses a counter-based design based on weaker (and faster) versions of cryptographic functions [1]. Instances using different values of the key produce independent sequences. Philox has a period of \(2^{256} - 1\) and supports arbitrary advancing and jumping the sequence in increments of \(2^{128}\). These features allow multiple non-overlapping sequences to be generated.
Philox
provides a capsule containing function pointers that produce doubles, and unsigned 32 and 64- bit integers. These are not directly consumable in Python and must be consumed by aGenerator
or similar object that supports low-level access.State and Seeding
The
Philox
state vector consists of a 256-bit value encoded as a 4-element uint64 array and a 128-bit value encoded as a 2-element uint64 array. The former is a counter which is incremented by 1 for every 4 64-bit randoms produced. The second is a key which determined the sequence produced. Using different keys produces independent sequences.The input
seed
is processed bySeedSequence
to generate the key. The counter is set to 0.Alternately, one can omit the
seed
parameter and set thekey
andcounter
directly.Parallel Features
The preferred way to use a BitGenerator in parallel applications is to use the
SeedSequence.spawn
method to obtain entropy values, and to use these to generate new BitGenerators:>>> from numpy.random import Generator, Philox, SeedSequence >>> sg = SeedSequence(1234) >>> rg = [Generator(Philox(s)) for s in sg.spawn(10)]
Philox
can be used in parallel applications by calling thejumped
method to advances the state as-if \(2^{128}\) random numbers have been generated. Alternatively,advance
can be used to advance the counter for any positive step in [0, 2**256). When usingjumped
, all generators should be chained to ensure that the segments come from the same sequence.>>> from numpy.random import Generator, Philox >>> bit_generator = Philox(1234) >>> rg = [] >>> for _ in range(10): ... rg.append(Generator(bit_generator)) ... bit_generator = bit_generator.jumped()
Alternatively,
Philox
can be used in parallel applications by using a sequence of distinct keys where each instance uses different key.>>> key = 2**96 + 2**33 + 2**17 + 2**9 >>> rg = [Generator(Philox(key=key+i)) for i in range(10)]
Compatibility Guarantee
Philox
makes a guarantee that a fixedseed
will always produce the same random integer stream.References
- 1
John K. Salmon, Mark A. Moraes, Ron O. Dror, and David E. Shaw, “Parallel Random Numbers: As Easy as 1, 2, 3,” Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis (SC11), New York, NY: ACM, 2011.
Examples
>>> from numpy.random import Generator, Philox >>> rg = Generator(Philox(1234)) >>> rg.standard_normal() 0.123 # random
- Attributes
- lock: threading.Lock
Lock instance that is shared so that the same bit git generator can be used in multiple Generators without corrupting the state. Code that generates values from a bit generator should hold the bit generator’s lock.