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 anintorarray_like[ints]is passed, then it will be passed toSeedSequenceto derive the initialBitGeneratorstate. One may also pass in aSeedSequenceinstance.- 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 andseedcannot 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.
Philoxprovides 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 aGeneratoror similar object that supports low-level access.State and Seeding
The
Philoxstate 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
seedis processed bySeedSequenceto generate the key. The counter is set to 0.Alternately, one can omit the
seedparameter and set thekeyandcounterdirectly.Parallel Features
The preferred way to use a BitGenerator in parallel applications is to use the
SeedSequence.spawnmethod 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)]
Philoxcan be used in parallel applications by calling thejumpedmethod to advances the state as-if \(2^{128}\) random numbers have been generated. Alternatively,advancecan 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,
Philoxcan 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
Philoxmakes a guarantee that a fixedseedwill 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.