{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Values of the integrand at each of the " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_points" }, { "__type": "Text", "__tag": 4046, "value": " points of a QMC sample are used to produce an estimate of the integral. This estimate is drawn from a population of possible estimates of the integral, the value of which we obtain depends on the particular points at which the integral was evaluated. We perform this process " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_estimates" }, { "__type": "Text", "__tag": 4046, "value": " times, each time evaluating the integrand at different scrambled QMC points, effectively drawing i.i.d. random samples from the population of integral estimates. The sample mean " }, { "__type": "InlineMath", "__tag": 4057, "value": "m" }, { "__type": "Text", "__tag": 4046, "value": " of these integral estimates is an unbiased estimator of the true value of the integral, and the standard error of the mean " }, { "__type": "InlineMath", "__tag": 4057, "value": "s" }, { "__type": "Text", "__tag": 4046, "value": " of these estimates may be used to generate confidence intervals using the t distribution with " }, { "__type": "InlineCode", "__tag": 4051, "value": "n_estimates - 1" }, { "__type": "Text", "__tag": 4046, "value": " degrees of freedom. Perhaps counter-intuitively, increasing " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_points" }, { "__type": "Text", "__tag": 4046, "value": " while keeping the total number of function evaluation points " }, { "__type": "InlineCode", "__tag": 4051, "value": "n_points * n_estimates" }, { "__type": "Text", "__tag": 4046, "value": " fixed tends to reduce the actual error, whereas increasing " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_estimates" }, { "__type": "Text", "__tag": 4046, "value": " tends to decrease the error estimate." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "qmc_quad", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._quadrature:qmc_quad" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ✅ \nPyTorch ✅ ✅ \nJAX ⚠️ no JIT ⚠️ no JIT \nDask ⛔ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "result", "annotation": "object", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A result object with attributes:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "integral" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "integral" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "standard_error :" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The error estimate. See Notes for interpretation." } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute an integral in N-dimensions using Quasi-Monte Carlo quadrature." } ] } ], "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": "func", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The integrand. Must accept a single argument " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ", an array which specifies the point(s) at which to evaluate the scalar-valued integrand, and return the value(s) of the integrand. For efficiency, the function should be vectorized to accept an array of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(d, n_points)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " is the number of variables (i.e. the dimensionality of the function domain) and " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_points" }, { "__type": "Text", "__tag": 4046, "value": " is the number of quadrature points, and return an array of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(n_points,)" }, { "__type": "Text", "__tag": 4046, "value": ", the integrand at each quadrature point." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "a, b", "annotation": "array-like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One-dimensional arrays specifying the lower and upper integration limits, respectively, of each of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " variables." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n_estimates, n_points", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "ParamRef", "__tag": 4071, "name": "n_estimates" }, { "__type": "Text", "__tag": 4046, "value": " (default: 8) statistically independent QMC samples, each of " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_points" }, { "__type": "Text", "__tag": 4046, "value": " (default: 1024) points, will be generated by " }, { "__type": "ParamRef", "__tag": 4071, "name": "qrng" }, { "__type": "Text", "__tag": 4046, "value": ". The total number of points at which the integrand " }, { "__type": "ParamRef", "__tag": 4071, "name": "func" }, { "__type": "Text", "__tag": 4046, "value": " will be evaluated is " }, { "__type": "InlineCode", "__tag": 4051, "value": "n_points * n_estimates" }, { "__type": "Text", "__tag": 4046, "value": ". See Notes for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "qrng", "annotation": "`~scipy.stats.qmc.QMCEngine`, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An instance of the QMCEngine from which to sample QMC points. The QMCEngine must be initialized to a number of dimensions " }, { "__type": "InlineCode", "__tag": 4051, "value": "d" }, { "__type": "Text", "__tag": 4046, "value": " corresponding with the number of variables " }, { "__type": "InlineCode", "__tag": 4051, "value": "x1, ..., xd" }, { "__type": "Text", "__tag": 4046, "value": " passed to " }, { "__type": "ParamRef", "__tag": 4071, "name": "func" }, { "__type": "Text", "__tag": 4046, "value": ". The provided QMCEngine is used to produce the first integral estimate. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "n_estimates" }, { "__type": "Text", "__tag": 4046, "value": " is greater than one, additional QMCEngines are spawned from the first (with scrambling enabled, if it is an option.) If a QMCEngine is not provided, the default " }, { "__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": " will be initialized with the number of dimensions determine from the length of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "log", "annotation": "boolean, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When set to True, " }, { "__type": "ParamRef", "__tag": 4071, "name": "func" }, { "__type": "Text", "__tag": 4046, "value": " returns the log of the integrand, and the result object contains the log of the integral." } ] } ] } ] } ], "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": "/scipy/integrate/_quadrature.py", "item_line": 1182, "item_type": "function", "aliases": [ "scipy.integrate.qmc_quad" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "QMC quadrature is particularly useful for computing integrals in higher\ndimensions. An example integrand is the probability density function\nof a multivariate normal distribution.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import stats\ndim = 8\nmean = np.zeros(dim)\ncov = np.eye(dim)\ndef func(x):\n # `multivariate_normal` expects the _last_ axis to correspond with\n # the dimensionality of the space, so `x` must be transposed\n return stats.multivariate_normal.pdf(x.T, mean, cov)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nTo compute the integral over the unit hypercube:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.integrate import qmc_quad\na = np.zeros(dim)\nb = np.ones(dim)\nrng = np.random.default_rng()\nqrng = stats.qmc.Halton(d=dim, seed=rng)\nn_estimates = 8\nres = qmc_quad(func, a, b, n_estimates=n_estimates, qrng=qrng)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.integral, res.standard_error\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nA two-sided, 99% confidence interval for the integral may be estimated\nas:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "t = stats.t(df=n_estimates-1, loc=res.integral,\n scale=res.standard_error)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "t.interval(0.99)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIndeed, the value reported by `scipy.stats.multivariate_normal` is\nwithin this range.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "stats.multivariate_normal.cdf(b, mean, cov, lower_limit=a)\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "func", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "n_estimates", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "8" }, { "__type": "SigParam", "__tag": 4030, "name": "n_points", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "1024" }, { "__type": "SigParam", "__tag": 4030, "name": "qrng", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "log", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "qmc_quad" }, "references": null, "qa": "scipy.integrate._quadrature:qmc_quad", "arbitrary": [], "local_refs": [ "a", "b", "func", "log", "n_estimates", "n_points", "qrng", "result" ] }