{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol' sequences " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " provide " }, { "__type": "InlineMath", "__tag": 4057, "value": "n=2^m" }, { "__type": "Text", "__tag": 4046, "value": " low discrepancy points in " }, { "__type": "InlineMath", "__tag": 4057, "value": "[0,1)^{d}" }, { "__type": "Text", "__tag": 4046, "value": ". Scrambling them " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " makes them suitable for singular integrands, provides a means of error estimation, and can improve their rate of convergence. The scrambling strategy which is implemented is a (left) linear matrix scramble (LMS) followed by a digital random shift (LMS+shift) " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There are many versions of Sobol' sequences depending on their 'direction numbers'. This code uses direction numbers from " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": ". Hence, the maximum number of dimension is 21201. The direction numbers have been precomputed with search criterion 6 and can be retrieved at https://web.maths.unsw.edu.au/~fkuo/sobol/." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "warning", "base_type": "warning", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "warning " } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol' sequences are a quadrature rule and they lose their balance properties if one uses a sample size that is not a power of 2, or skips the first point, or thins the sequence " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "5" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineMath", "__tag": 4057, "value": "n=2^m" }, { "__type": "Text", "__tag": 4046, "value": " points are not enough then one should take " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^M" }, { "__type": "Text", "__tag": 4046, "value": " points for " }, { "__type": "InlineMath", "__tag": 4057, "value": "M>m" }, { "__type": "Text", "__tag": 4046, "value": ". When scrambling, the number R of independent replicates does not have to be a power of 2." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol' sequences are generated to some number " }, { "__type": "InlineMath", "__tag": 4057, "value": "B" }, { "__type": "Text", "__tag": 4046, "value": " of bits. After " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^B" }, { "__type": "Text", "__tag": 4046, "value": " points have been generated, the sequence would repeat. Hence, an error is raised. The number of bits can be controlled with the parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "bits" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ], "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": "Engine for generating (scrambled) Sobol' sequences." } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "d", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Dimensionality of the sequence. Max dimensionality is 21201." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "scramble", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, use LMS+shift scrambling. Otherwise, no scrambling is done. Default is True." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "bits", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of bits of the generator. Control the maximum number of points that can be generated, which is " }, { "__type": "InlineCode", "__tag": 4051, "value": "2**bits" }, { "__type": "Text", "__tag": 4046, "value": ". Maximal value is 64. It does not correspond to the return type, which is always " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.float64" }, { "__type": "Text", "__tag": 4046, "value": " to prevent points from repeating themselves. Default is None, which for backward compatibility, corresponds to 30." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.9.0" } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "optimization", "annotation": "{None, \"random-cd\", \"lloyd\"}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to use an optimization scheme to improve the quality after sampling. Note that this is a post-processing step that does not guarantee that all properties of the sample will be conserved. Default is None." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "random-cd" }, { "__type": "Text", "__tag": 4046, "value": ": random permutations of coordinates to lower the centered discrepancy. The best sample based on the centered discrepancy is constantly updated. Centered discrepancy-based sampling shows better space-filling robustness toward 2D and 3D subprojections compared to using other discrepancy measures." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "lloyd" }, { "__type": "Text", "__tag": 4046, "value": ": Perturb samples using a modified Lloyd-Max algorithm. The process converges to equally spaced samples." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.10.0" } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rng", "annotation": "`numpy.random.Generator`, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Pseudorandom number generator state. When " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is None, a new " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is created using entropy from the operating system. Types other than " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " are passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.default_rng", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random:default_rng" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to instantiate a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 1.15.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As part of the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "SPEC-007" } ], "url": "https://scientific-python.org/specs/spec-0007/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " transition from use of " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.RandomState", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random.mtrand:RandomState" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", this keyword was changed from " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": ". For an interim period, both keywords will continue to work, although only one may be specified at a time. After the interim period, function calls using the " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " keyword will emit warnings. Following a deprecation period, the " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__type": "Text", "__tag": 4046, "value": " keyword will be removed." } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol' sequences are low-discrepancy, quasi-random numbers. Points can be drawn using two methods:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "random_base2", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ": safely draw " }, { "__type": "InlineMath", "__tag": 4057, "value": "n=2^m" }, { "__type": "Text", "__tag": 4046, "value": " points. This method guarantees the balance properties of the sequence." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "random", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "random", "version": "*", "kind": "api", "path": "random" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ": draw an arbitrary number of points from the sequence. See warning below." } ] } ] } ] } ], "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": "/scipy/stats/_qmc.py", "item_line": 1609, "item_type": "ABCMeta", "aliases": [ "scipy.stats._qmc.Sobol" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generate samples from a low discrepancy sequence of Sobol'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.stats import qmc\nsampler = qmc.Sobol(d=2, scramble=False)\nsample = sampler.random_base2(m=3)\nsample\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCompute the quality of the sample using the discrepancy criterion.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "qmc.discrepancy(sample)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nTo continue an existing design, extra points can be obtained\nby calling again `random_base2`. Alternatively, you can skip some\npoints like:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "_ = sampler.reset()\n_ = sampler.fast_forward(4)\nsample_continued = sampler.random_base2(m=2)\nsample_continued\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFinally, samples can be scaled to bounds.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "l_bounds = [0, 2]\nu_bounds = [10, 5]\nqmc.scale(sample_continued, l_bounds, u_bounds)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "d", "annotation": "int | numpy.integer", "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "scramble", "annotation": "bool", "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "bits", "annotation": "int | numpy.integer | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rng", "annotation": "int | numpy.integer | numpy.random._generator.Generator | numpy.random.mtrand.RandomState | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "optimization", "annotation": "Literal['random-cd', 'lloyd'] | None", "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "seed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": "None", "target_name": "Sobol" }, "references": [ ".. [1] I. M. Sobol', \"The distribution of points in a cube and the accurate", " evaluation of integrals.\" Zh. Vychisl. Mat. i Mat. Phys., 7:784-802,", " 1967.", ".. [2] J. Matousek, \"On the L2-discrepancy for anchored boxes.\"", " J. of Complexity 14, 527-556, 1998.", ".. [3] Art B. Owen, \"Scrambling Sobol and Niederreiter-Xing points.\"", " Journal of Complexity, 14(4):466-489, December 1998.", ".. [4] S. Joe and F. Y. Kuo, \"Constructing sobol sequences with better", " two-dimensional projections.\" SIAM Journal on Scientific Computing,", " 30(5):2635-2654, 2008.", ".. [5] Art B. Owen, \"On dropping the first Sobol' point.\"", " :arxiv:`2008.08051`, 2020." ], "qa": "scipy.stats._qmc:Sobol", "arbitrary": [], "local_refs": [ "bits", "d", "optimization", "rng", "scramble" ] }