{ "__type": "IngestedDoc", "__tag": 4010, "_content": {}, "_ordered_sections": [], "item_file": null, "item_line": null, "item_type": null, "aliases": [], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "see_also": [], "signature": null, "references": null, "qa": "reference:random:bit_generators:index", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The random values produced by " }, { "__type": "InlineRole", "__tag": 4003, "value": "~Generator", "domain": null, "role": "class", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " originate in a BitGenerator. The BitGenerators do not directly provide random numbers and only contains methods used for seeding, getting or setting the state, jumping or advancing the state, and for accessing low-level wrappers for consumption by code that can efficiently access the functions provided, e.g., " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "numba" } ], "url": "https://numba.pydata.org", "title": "" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Bit generators" } ], "level": 0, "target": "random-bit-generators" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The included BitGenerators are:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "PCG-64 - The default. A fast generator that can be advanced by an arbitrary amount. See the documentation for " }, { "__type": "InlineRole", "__tag": 4003, "value": "~.PCG64.advance", "domain": null, "role": "meth", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". PCG-64 has a period of " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^{128}" }, { "__type": "Text", "__tag": 4046, "value": ". See the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "PCG author's page" } ], "url": "https://www.pcg-random.org/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for more details about this class of PRNG." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "PCG-64 DXSM - An upgraded version of PCG-64 with better statistical properties in parallel contexts. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "upgrading-pcg64", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:upgrading-pcg64" }, "kind": "exists" }, { "__type": "Text", "__tag": 4046, "value": " for more information on these improvements." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "MT19937 - The standard Python BitGenerator. Adds a " }, { "__type": "InlineRole", "__tag": 4003, "value": "MT19937.jumped", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " function that returns a new generator with state as-if " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^{128}" }, { "__type": "Text", "__tag": 4046, "value": " draws have been made." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Philox - A counter-based generator capable of being advanced an arbitrary number of steps or generating independent streams. See the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "Random123" } ], "url": "https://www.deshawresearch.com/resources_random123.html", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " page for more details about this class of bit generators." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SFC64 - A fast generator based on random invertible mappings. Usually the fastest generator of the four. See the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "SFC author's page" } ], "url": "https://pracrand.sourceforge.net/RNG_engines.txt", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " for (a little) more detail." } ] } ] } ] }, { "__type": "Target", "__tag": 4061, "label": "PCG author's page" }, { "__type": "Target", "__tag": 4061, "label": "Random123" }, { "__type": "Target", "__tag": 4061, "label": "SFC author's page" }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n BitGenerator", "execution_status": null }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "MT19937", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:bit_generators:mt19937" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "PCG64", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:bit_generators:pcg64" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "PCG64DXSM", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:bit_generators:pcg64dxsm" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "Philox", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:bit_generators:philox" }, "kind": "exists" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "SFC64", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "docs", "path": "reference:random:bit_generators:sfc64" }, "kind": "exists" } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Supported BitGenerators" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A BitGenerator provides a stream of random values. In order to generate reproducible streams, BitGenerators support setting their initial state via a seed. All of the provided BitGenerators will take an arbitrary-sized non-negative integer, or a list of such integers, as a seed. BitGenerators need to take those inputs and process them into a high-quality internal state for the BitGenerator. All of the BitGenerators in numpy delegate that task to " }, { "__type": "InlineRole", "__tag": 4003, "value": "SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", which uses hashing techniques to ensure that even low-quality seeds generate high-quality initial states." } ] }, { "__type": "Code", "__tag": 4050, "value": "from numpy.random import PCG64\n\nbg = PCG64(12345678903141592653589793)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is designed to be convenient for implementing best practices. We recommend that a stochastic program defaults to using entropy from the OS so that each run is different. The program should print out or log that entropy. In order to reproduce a past value, the program should allow the user to provide that value through some mechanism, a command-line argument is common, so that the user can then re-enter that entropy to reproduce the result. " }, { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can take care of everything except for communicating with the user, which is up to you." } ] }, { "__type": "Code", "__tag": 4050, "value": "from numpy.random import PCG64, SeedSequence\n\n# Get the user's seed somehow, maybe through `argparse`.\n# If the user did not provide a seed, it should return `None`.\nseed = get_user_seed()\nss = SeedSequence(seed)\nprint(f'seed = {ss.entropy}')\nbg = PCG64(ss)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We default to using a 128-bit integer using entropy gathered from the OS. This is a good amount of entropy to initialize all of the generators that we have in numpy. We do not recommend using small seeds below 32 bits for general use. Using just a small set of seeds to instantiate larger state spaces means that there are some initial states that are impossible to reach. This creates some biases if everyone uses such values." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There will not be anything " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "wrong" } ] }, { "__type": "Text", "__tag": 4046, "value": " with the results, per se; even a seed of 0 is perfectly fine thanks to the processing that " }, { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " does. If you just need " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "some" } ] }, { "__type": "Text", "__tag": 4046, "value": " fixed value for unit tests or debugging, feel free to use whatever seed you like. But if you want to make inferences from the results or publish them, drawing from a larger set of seeds is good practice." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you need to generate a good seed \"offline\", then " }, { "__type": "InlineCode", "__tag": 4051, "value": "SeedSequence().entropy" }, { "__type": "Text", "__tag": 4046, "value": " or using " }, { "__type": "InlineCode", "__tag": 4051, "value": "secrets.randbits(128)" }, { "__type": "Text", "__tag": 4046, "value": " from the standard library are both convenient ways." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you need to run several stochastic simulations in parallel, best practice is to construct a random generator instance for each simulation. To make sure that the random streams have distinct initial states, you can use the " }, { "__type": "InlineRole", "__tag": 4003, "value": "spawn", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method of " }, { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". For instance, here we construct a list of 12 instances:" } ] }, { "__type": "Code", "__tag": 4050, "value": "from numpy.random import PCG64, SeedSequence\n\n# High quality initial entropy\nentropy = 0x87351080e25cb0fad77a44a3be03b491\nbase_seq = SeedSequence(entropy)\nchild_seqs = base_seq.spawn(12) # a list of 12 SeedSequences\ngenerators = [PCG64(seq) for seq in child_seqs]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you already have an initial random generator instance, you can shorten the above by using the " }, { "__type": "InlineRole", "__tag": 4003, "value": "~BitGenerator.spawn", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " method:" } ] }, { "__type": "Code", "__tag": 4050, "value": "from numpy.random import PCG64, SeedSequence\n# High quality initial entropy\nentropy = 0x87351080e25cb0fad77a44a3be03b491\nbase_bitgen = PCG64(entropy)\ngenerators = base_bitgen.spawn(12)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An alternative way is to use the fact that a " }, { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " can be initialized by a tuple of elements. Here we use a base entropy value and an integer " }, { "__type": "InlineCode", "__tag": 4051, "value": "worker_id" } ] }, { "__type": "Code", "__tag": 4050, "value": "from numpy.random import PCG64, SeedSequence\n\n# High quality initial entropy\nentropy = 0x87351080e25cb0fad77a44a3be03b491 \nsequences = [SeedSequence((entropy, worker_id)) for worker_id in range(12)]\ngenerators = [PCG64(seq) for seq in sequences]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the sequences produced by the latter method will be distinct from those constructed via " }, { "__type": "InlineRole", "__tag": 4003, "value": "~SeedSequence.spawn", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Code", "__tag": 4050, "value": ".. autosummary:: \n :toctree:generated/\n SeedSequence", "execution_status": null } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Seeding and entropy" } ], "level": 0, "target": "seeding_and_entropy" } ], "local_refs": [] }