{ "__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": "tutorial:stats:quasi_monte_carlo", "arbitrary": [ { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Before talking about Quasi-Monte Carlo (QMC), a quick introduction about Monte Carlo (MC). MC methods, or MC experiments, are a broad class of computational algorithms that rely on repeated random sampling to obtain numerical results. The underlying concept is to use randomness to solve problems that might be deterministic in principle. They are often used in physical and mathematical problems and are most useful when it is difficult or impossible to use other approaches. MC methods are mainly used in three problem classes: optimization, numerical integration, and generating draws from a probability distribution." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generating random numbers with specific properties is a more complex problem than it sounds. Simple MC methods are designed to sample points to be independent and identically distributed (IID). But generating multiple sets of random points can produce radically different results." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In both cases in the plot above, points are generated randomly without any knowledge about previously drawn points. It is clear that some regions of the space are left unexplored - which can cause problems in simulations as a particular set of points might trigger a totally different behaviour." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A great benefit of MC is that it has known convergence properties. Let's look at the mean of the squared sum in 5 dimensions:" } ] }, { "__type": "Math", "__tag": 4058, "value": "f(\\mathbf{x}) = \\left( \\sum_{j=1}^{5}x_j \\right)^2," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with " }, { "__type": "InlineMath", "__tag": 4057, "value": "x_j \\sim \\mathcal{U}(0,1)" }, { "__type": "Text", "__tag": 4046, "value": ". It has a known mean value, " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\mu = 5/3+5(5-1)/4" }, { "__type": "Text", "__tag": 4046, "value": ". Using MC sampling, we can compute that mean numerically, and the approximation error follows a theoretical rate of " }, { "__type": "InlineMath", "__tag": 4057, "value": "O(n^{-1/2})" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Although the convergence is ensured, practitioners tend to want to have an exploration process which is more deterministic. With normal MC, a seed can be used to have a repeatable process. But fixing the seed would break the convergence property: a given seed could work for a given class of problem and break for another one." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "What is commonly done to walk through the space in a deterministic manner, is to use a regular grid spanning all parameter dimensions, also called a saturated design. Let’s consider the unit-hypercube, with all bounds ranging from 0 to 1. Now, having a distance of 0.1 between points, the number of points required to fill the unit interval would be 10. In a 2-dimensional hypercube the same spacing would require 100, and in 3 dimensions 1,000 points. As the number of dimensions grows, the number of experiments which is required to fill the space rises exponentially as the dimensionality of the space increases. This exponential growth is called \"the curse of dimensionality\"." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> disc = 10\n>>> x1 = np.linspace(0, 1, disc)\n>>> x2 = np.linspace(0, 1, disc)\n>>> x3 = np.linspace(0, 1, disc)\n>>> x1, x2, x3 = np.meshgrid(x1, x2, x3)", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To mitigate this issue, QMC methods have been designed. They are deterministic, have a good coverage of the space and some of them can be continued and retain good properties. The main difference with MC methods is that the points are not IID but they know about previous points. Hence, some methods are also referred to as sequences." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This figure presents 2 sets of 256 points. The design of the left is a plain MC whereas the design of the right is a QMC design using the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol'" } ] }, { "__type": "Text", "__tag": 4046, "value": " method. We clearly see that the QMC version is more uniform. The points sample better near the boundaries and there are less clusters or gaps." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One way to assess the uniformity is to use a measure called the discrepancy. Here the discrepancy of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol'" } ] }, { "__type": "Text", "__tag": 4046, "value": " points is better than crude MC." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Coming back to the computation of the mean, QMC methods also have better rates of convergence for the error. They can achieve " }, { "__type": "InlineMath", "__tag": 4057, "value": "O(n^{-1})" }, { "__type": "Text", "__tag": 4046, "value": " for this function, and even better rates on very smooth functions. This figure shows that the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol'" } ] }, { "__type": "Text", "__tag": 4046, "value": " method has a rate of " }, { "__type": "InlineMath", "__tag": 4057, "value": "O(n^{-1})" }, { "__type": "Text", "__tag": 4046, "value": ":" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "We refer to the documentation of " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats.qmc" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for more mathematical details." } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Quasi-Monte Carlo" } ], "level": 0, "target": "quasi-monte-carlo" }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Let's consider two sets of points. From the figure below, it is clear that the design on the left covers more of the space than the design on the right. This can be quantified using a " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.discrepancy", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:discrepancy" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " measure. The lower the discrepancy, the more uniform a sample is." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> from scipy.stats import qmc\n>>> space_1 = np.array([[1, 3], [2, 6], [3, 2], [4, 5], [5, 1], [6, 4]])\n>>> space_2 = np.array([[1, 5], [2, 4], [3, 3], [4, 2], [5, 1], [6, 6]])\n>>> l_bounds = [0.5, 0.5]\n>>> u_bounds = [6.5, 6.5]\n>>> space_1 = qmc.scale(space_1, l_bounds, u_bounds, reverse=True)\n>>> space_2 = qmc.scale(space_2, l_bounds, u_bounds, reverse=True)\n>>> qmc.discrepancy(space_1)\n0.008142039609053464\n>>> qmc.discrepancy(space_2)\n0.010456854423869011", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Calculate the discrepancy" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Several QMC samplers/engines are implemented. Here we look at two of the most used QMC methods: " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Sobol", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Sobol" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Halton", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Halton" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " sequences." } ] }, { "__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": "QMC methods require particular care and the user must read the documentation to avoid common pitfalls. " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol'" } ] }, { "__type": "Text", "__tag": 4046, "value": " for instance requires a number of points following a power of 2. Also, thinning, burning or other point selection can break the properties of the sequence and result in a set of points which would not be better than MC." } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "QMC engines are state-aware. Meaning that you can continue the sequence, skip some points, or reset it. Let's take 5 points from " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Halton", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Halton" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". And then ask for a second set of 5 points:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> from scipy.stats import qmc\n>>> engine = qmc.Halton(d=2)\n>>> engine.random(5)\narray([[0.22166437, 0.07980522], # random\n [0.72166437, 0.93165708],\n [0.47166437, 0.41313856],\n [0.97166437, 0.19091633],\n [0.01853937, 0.74647189]])\n>>> engine.random(5)\narray([[0.51853937, 0.52424967], # random\n [0.26853937, 0.30202745],\n [0.76853937, 0.857583 ],\n [0.14353937, 0.63536078],\n [0.64353937, 0.01807683]])", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Now we reset the sequence. Asking for 5 points leads to the same first 5 points:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> engine.reset()\n>>> engine.random(5)\narray([[0.22166437, 0.07980522], # random\n [0.72166437, 0.93165708],\n [0.47166437, 0.41313856],\n [0.97166437, 0.19091633],\n [0.01853937, 0.74647189]])", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "And here we advance the sequence to get the same second set of 5 points:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> engine.reset()\n>>> engine.fast_forward(5)\n>>> engine.random(5)\narray([[0.51853937, 0.52424967], # random\n [0.26853937, 0.30202745],\n [0.76853937, 0.857583 ],\n [0.14353937, 0.63536078],\n [0.64353937, 0.01807683]])", "execution_status": null } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "note", "base_type": "note", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "note By default, both :class:`scipy.stats.qmc.Sobol` and" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Halton", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Halton" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " are scrambled. The convergence properties are better, and it prevents the appearance of fringes or noticeable patterns of points in high dimensions. There should be no practical reason not to use the scrambled version." } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Using a QMC engine" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To make your own " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.QMCEngine", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:QMCEngine" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", a few methods have to be defined. Following is an example wrapping " }, { "__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": "." } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> from scipy.stats import qmc\n>>> class RandomEngine(qmc.QMCEngine):\n... def __init__(self, d, seed=None):\n... super().__init__(d=d, seed=seed)\n... self.rng = np.random.default_rng(self.rng_seed)\n...\n...\n... def _random(self, n=1, *, workers=1):\n... return self.rng.random((n, self.d))\n...\n...\n... def reset(self):\n... self.rng = np.random.default_rng(self.rng_seed)\n... self.num_generated = 0\n... return self\n...\n...\n... def fast_forward(self, n):\n... self.random(n)\n... return self", "execution_status": null } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Then we use it as any other QMC engine:" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Code", "__tag": 4050, "value": ">>> engine = RandomEngine(2)\n>>> engine.random(5)\narray([[0.22733602, 0.31675834], # random\n [0.79736546, 0.67625467],\n [0.39110955, 0.33281393],\n [0.59830875, 0.18673419],\n [0.67275604, 0.94180287]])\n>>> engine.reset()\n>>> engine.random(5)\narray([[0.22733602, 0.31675834], # random\n [0.79736546, 0.67625467],\n [0.39110955, 0.33281393],\n [0.59830875, 0.18673419],\n [0.67275604, 0.94180287]])", "execution_status": null } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Making a QMC engine, i.e., subclassing " }, { "__type": "InlineCode", "__tag": 4051, "value": "QMCEngine" } ], "level": 1, "target": null }, { "__type": "Section", "__tag": 4015, "children": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "QMC has rules! Be sure to read the documentation or you might have no benefit over MC." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Use " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Sobol", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Sobol" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " if you need " }, { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "exactly" } ] }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "InlineMath", "__tag": 4057, "value": "2^m" }, { "__type": "Text", "__tag": 4046, "value": " points." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "scipy.stats.qmc.Halton", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.stats._qmc:Halton" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " allows to sample, or skip, an arbitrary number of points. This is at the cost of a slower rate of convergence than " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sobol'" } ] }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Never remove the first points of the sequence. It will destroy the properties." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Scrambling is always better." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If you use LHS based methods, you cannot add points without losing the LHS properties. (There are some methods to do so, but this is not implemented.)" } ] } ] } ] } ], "title": [ { "__type": "Text", "__tag": 4046, "value": "Guidelines on using QMC" } ], "level": 1, "target": null } ], "local_refs": [] }