{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Philox is a 64-bit PRNG that uses a counter-based design based on weaker (and faster) versions of cryptographic functions " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". Instances using different values of the key produce independent sequences. Philox has a period of " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^{256} - 1" }, { "__type": "Text", "__tag": 4046, "value": " and supports arbitrary advancing and jumping the sequence in increments of " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^{128}" }, { "__type": "Text", "__tag": 4046, "value": ". These features allow multiple non-overlapping sequences to be generated." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._philox:Philox" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " 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 a " }, { "__type": "CrossRef", "__tag": 4002, "value": "Generator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " or similar object that supports low-level access." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "State and Seeding" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._philox:Philox" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " 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." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The input " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": " is processed by " }, { "__type": "CrossRef", "__tag": 4002, "value": "SeedSequence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random.bit_generator:SeedSequence" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to generate the key. The counter is set to 0." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternately, one can omit the " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": " parameter and set the " }, { "__type": "InlineCode", "__tag": 4051, "value": "key" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "counter" }, { "__type": "Text", "__tag": 4046, "value": " directly." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parallel Features" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The preferred way to use a BitGenerator in parallel applications is to use the " }, { "__type": "InlineRole", "__tag": 4003, "value": "SeedSequence.spawn", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method to obtain entropy values, and to use these to generate new BitGenerators:" } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> from numpy.random import Generator, Philox, SeedSequence\n>>> sg = SeedSequence(1234)\n>>> rg = [Generator(Philox(s)) for s in sg.spawn(10)]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._philox:Philox" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " can be used in parallel applications by calling the " }, { "__type": "InlineRole", "__tag": 4003, "value": "jumped", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method to advance the state as-if " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^{128}" }, { "__type": "Text", "__tag": 4046, "value": " random numbers have been generated. Alternatively, " }, { "__type": "InlineRole", "__tag": 4003, "value": "advance", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can be used to advance the counter for any positive step in [0, 2**256). When using " }, { "__type": "InlineRole", "__tag": 4003, "value": "jumped", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", all generators should be chained to ensure that the segments come from the same sequence." } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> from numpy.random import Generator, Philox\n>>> bit_generator = Philox(1234)\n>>> rg = []\n>>> for _ in range(10):\n... rg.append(Generator(bit_generator))\n... bit_generator = bit_generator.jumped()", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternatively, " }, { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._philox:Philox" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " can be used in parallel applications by using a sequence of distinct keys where each instance uses different key." } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> key = 2**96 + 2**33 + 2**17 + 2**9\n>>> rg = [Generator(Philox(key=key+i)) for i in range(10)]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compatibility Guarantee" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random._philox:Philox" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " makes a guarantee that a fixed " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": " will always produce the same random integer stream." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Container for the Philox (4x64) pseudo-random number generator." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "lock: threading.Lock", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "seed", "annotation": "{None, int, array_like[ints], SeedSequence}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A seed to initialize the " }, { "__type": "CrossRef", "__tag": 4002, "value": "BitGenerator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random.bit_generator:BitGenerator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". If None, then fresh, unpredictable entropy will be pulled from the OS. If an " }, { "__type": "InlineCode", "__tag": 4051, "value": "int" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "array_like[ints]" }, { "__type": "Text", "__tag": 4046, "value": " is passed, then it will be passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "SeedSequence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random.bit_generator:SeedSequence" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to derive the initial " }, { "__type": "CrossRef", "__tag": 4002, "value": "BitGenerator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random.bit_generator:BitGenerator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " state. One may also pass in a " }, { "__type": "CrossRef", "__tag": 4002, "value": "SeedSequence", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy.random.bit_generator:SeedSequence" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " instance." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "counter", "annotation": "{None, int, array_like}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "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." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "key", "annotation": "{None, int, array_like}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Key to use in the Philox state. Unlike " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": ", the value in key is directly set. Can be either a Python int in [0, 2**128) or a 2-element uint64 array. " }, { "__type": "ParamRef", "__tag": 4071, "name": "key" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "seed" }, { "__type": "Text", "__tag": 4046, "value": " cannot both be used." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/numpy/random/_philox.cpython-314-x86_64-linux-gnu.so", "item_line": null, "item_type": "class", "aliases": [ "numpy.random.Philox" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from numpy.random import Generator, Philox\nrg = Generator(Philox(1234))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "rg.standard_normal()\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "seed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "counter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "key", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "Philox" }, "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." ], "qa": "numpy.random._philox:Philox", "arbitrary": [], "local_refs": [ "counter", "key", "lock: threading.Lock", "seed" ] }