{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Implements the algorithm as described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " with minor adaptations for finite-precision arithmetic, including some described by " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": ". The tanh-sinh scheme was originally introduced in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Two error estimation schemes are described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " Section 5: one attempts to detect and exploit quadratic convergence; the other simply compares the integral estimates at successive levels. While neither is theoretically rigorous or conservative, both work well in practice. Our error estimate uses the minimum of these two schemes with a lower bound of " }, { "__type": "InlineCode", "__tag": 4051, "value": "eps * res.integral" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Due to floating-point error in the abscissae, the function may be evaluated at the endpoints of the interval during iterations, but the values returned by the function at the endpoints will be ignored." } ] }, { "__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": "tanhsinh", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._tanhsinh:tanhsinh" }, "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 ⛔ ⛔ \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": "res", "annotation": "_RichResult", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An object similar to an instance of " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.optimize.OptimizeResult", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.optimize._optimize:OptimizeResult" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " with the following attributes. (The descriptions are written as though the values will be scalars; however, if " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " returns an array, the outputs will be arrays of the same shape.)" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "success" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "success" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "status" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "status" } ] } ] }, { "__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": "error" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "error" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "maxlevel" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "maxlevel" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nfev" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "nfev" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Evaluate a convergent integral numerically using tanh-sinh 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": "f", "annotation": "callable", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The function to be integrated. The signature must be " } ] }, { "__type": "Code", "__tag": 4050, "value": "f(xi: ndarray, *argsi) -> ndarray", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where each element of " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " is a finite real number and " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": " is a tuple, which may contain an arbitrary number of arrays that are broadcastable with " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must be an elementwise function: see documentation of parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "preserve_shape" }, { "__type": "Text", "__tag": 4046, "value": " for details. It must not mutate the array " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " or the arrays in " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": " returns a value with complex dtype when evaluated at either endpoint, subsequent arguments " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " will have complex dtype (but zero imaginary part)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "a, b", "annotation": "float array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Real lower and upper limits of integration. Must be broadcastable with one another and with arrays in " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": ". Elements may be infinite." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "args", "annotation": "tuple of array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Additional positional array arguments to be passed to " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ". Arrays must be broadcastable with one another and the arrays of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": ". If the callable for which the root is desired requires arguments that are not broadcastable with " }, { "__type": "InlineRole", "__tag": 4003, "value": "x", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", wrap that callable with " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " such that " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " accepts only " }, { "__type": "InlineRole", "__tag": 4003, "value": "x", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and broadcastable " }, { "__type": "InlineCode", "__tag": 4051, "value": "*args" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "log", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Setting to True indicates that " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " returns the log of the integrand and that " }, { "__type": "ParamRef", "__tag": 4071, "name": "atol" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "rtol" }, { "__type": "Text", "__tag": 4046, "value": " are expressed as the logs of the absolute and relative errors. In this case, the result object will contain the log of the integral and error. This is useful for integrands for which numerical underflow or overflow would lead to inaccuracies. When " }, { "__type": "InlineCode", "__tag": 4051, "value": "log=True" }, { "__type": "Text", "__tag": 4046, "value": ", the integrand (the exponential of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ") must be real, but it may be negative, in which case the log of the integrand is a complex number with an imaginary part that is an odd multiple of π." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxlevel", "annotation": "int, default: 10", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum refinement level of the algorithm." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "At the zeroth level, " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is called once, performing 16 function evaluations. At each subsequent level, " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is called once more, approximately doubling the number of function evaluations that have been performed. Accordingly, for many integrands, each successive level will double the number of accurate digits in the result (up to the limits of floating point precision)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The algorithm will terminate after completing level " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxlevel" }, { "__type": "Text", "__tag": 4046, "value": " or after another termination condition is satisfied, whichever comes first." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "minlevel", "annotation": "int, default: 2", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The level at which to begin iteration (default: 2). This does not change the total number of function evaluations or the abscissae at which the function is evaluated; it changes only the " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "number of times" } ] }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " is called. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "minlevel=k" }, { "__type": "Text", "__tag": 4046, "value": ", then the integrand is evaluated at all abscissae from levels " }, { "__type": "InlineCode", "__tag": 4051, "value": "0" }, { "__type": "Text", "__tag": 4046, "value": " through " }, { "__type": "InlineCode", "__tag": 4051, "value": "k" }, { "__type": "Text", "__tag": 4046, "value": " in a single call. Note that if " }, { "__type": "ParamRef", "__tag": 4071, "name": "minlevel" }, { "__type": "Text", "__tag": 4046, "value": " exceeds " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxlevel" }, { "__type": "Text", "__tag": 4046, "value": ", the provided " }, { "__type": "ParamRef", "__tag": 4071, "name": "minlevel" }, { "__type": "Text", "__tag": 4046, "value": " is ignored, and " }, { "__type": "ParamRef", "__tag": 4071, "name": "minlevel" }, { "__type": "Text", "__tag": 4046, "value": " is set equal to " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxlevel" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "atol, rtol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Absolute termination tolerance (default: 0) and relative termination tolerance (default: " }, { "__type": "InlineCode", "__tag": 4051, "value": "eps**0.75" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "eps" }, { "__type": "Text", "__tag": 4046, "value": " is the precision of the result dtype), respectively. Must be non-negative and finite if " }, { "__type": "ParamRef", "__tag": 4071, "name": "log" }, { "__type": "Text", "__tag": 4046, "value": " is False, and must be expressed as the log of a non-negative and finite number if " }, { "__type": "ParamRef", "__tag": 4071, "name": "log" }, { "__type": "Text", "__tag": 4046, "value": " is True. Iteration will stop when " }, { "__type": "InlineCode", "__tag": 4051, "value": "res.error < atol" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "res.error < res.integral * rtol" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "preserve_shape", "annotation": "bool, default: False", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the following, \"arguments of " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": "\" refers to the array " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " and any arrays within " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": ". Let " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape" }, { "__type": "Text", "__tag": 4046, "value": " be the broadcasted shape of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": ", and all elements of " }, { "__type": "ParamRef", "__tag": 4071, "name": "args" }, { "__type": "Text", "__tag": 4046, "value": " (which is conceptually distinct from " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "argsi" }, { "__type": "Text", "__tag": 4046, "value": " passed into " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_shape=False" }, { "__type": "Text", "__tag": 4046, "value": " (default), " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must accept arguments of " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "any" } ] }, { "__type": "Text", "__tag": 4046, "value": " broadcastable shapes." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "preserve_shape=True" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must accept arguments of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape" }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "or" } ] }, { "__type": "Text", "__tag": 4046, "value": " " }, { "__type": "InlineCode", "__tag": 4051, "value": "shape + (n,)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "(n,)" }, { "__type": "Text", "__tag": 4046, "value": " is the number of abscissae at which the function is being evaluated." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In either case, for each scalar element " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi[j]" }, { "__type": "Text", "__tag": 4046, "value": " within " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": ", the array returned by " }, { "__type": "ParamRef", "__tag": 4071, "name": "f" }, { "__type": "Text", "__tag": 4046, "value": " must include the scalar " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(xi[j])" }, { "__type": "Text", "__tag": 4046, "value": " at the same index. Consequently, the shape of the output is always the shape of the input " }, { "__type": "InlineCode", "__tag": 4051, "value": "xi" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See Examples." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "callback", "annotation": "callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An optional user-supplied function to be called before the first iteration and after each iteration. Called as " }, { "__type": "InlineCode", "__tag": 4051, "value": "callback(res)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "res" }, { "__type": "Text", "__tag": 4046, "value": " is a " }, { "__type": "InlineCode", "__tag": 4051, "value": "_RichResult" }, { "__type": "Text", "__tag": 4046, "value": " similar to that returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "tanhsinh", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._tanhsinh:tanhsinh" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " (but containing the current iterate's values of all variables). If " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " raises a " }, { "__type": "InlineCode", "__tag": 4051, "value": "StopIteration" }, { "__type": "Text", "__tag": 4046, "value": ", the algorithm will terminate immediately and " }, { "__type": "CrossRef", "__tag": 4002, "value": "tanhsinh", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._tanhsinh:tanhsinh" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " will return a result object. " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " must not mutate " }, { "__type": "CrossRef", "__tag": 4002, "value": "res", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "res" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " or its attributes." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In practice, tanh-sinh quadrature achieves quadratic convergence for many integrands: the number of accurate " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "digits" } ] }, { "__type": "Text", "__tag": 4046, "value": " scales roughly linearly with the number of function evaluations " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Either or both of the limits of integration may be infinite, and singularities at the endpoints are acceptable. Divergent integrals and integrands with non-finite derivatives or singularities within an interval are out of scope, but the latter may be evaluated be calling " }, { "__type": "CrossRef", "__tag": 4002, "value": "tanhsinh", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._tanhsinh:tanhsinh" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " on each sub-interval separately." } ] } ], "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/_tanhsinh.py", "item_line": 30, "item_type": "function", "aliases": [ "scipy.integrate.tanhsinh" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Evaluate the Gaussian integral:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.integrate import tanhsinh\ndef f(x):\n return np.exp(-x**2)\nres = tanhsinh(f, -np.inf, np.inf)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.integral # true value is np.sqrt(np.pi), 1.7724538509055159\nres.error # actual error is 0\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe value of the Gaussian function (bell curve) is nearly zero for\narguments sufficiently far from zero, so the value of the integral\nover a finite interval is nearly the same.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "tanhsinh(f, -20, 20).integral\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nHowever, with unfavorable integration limits, the integration scheme\nmay not be able to find the important region.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "tanhsinh(f, -np.inf, 1000).integral\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nIn such cases, or when there are singularities within the interval,\nbreak the integral into parts with endpoints at the important points.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "tanhsinh(f, -np.inf, 0).integral + tanhsinh(f, 0, 1000).integral\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFor integration involving very large or very small magnitudes, use\nlog-integration. (For illustrative purposes, the following example shows a\ncase in which both regular and log-integration work, but for more extreme\nlimits of integration, log-integration would avoid the underflow\nexperienced when evaluating the integral normally.)\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res = tanhsinh(f, 20, 30, rtol=1e-10)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "res.integral, res.error\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "def log_f(x):\n return -x**2\nres = tanhsinh(log_f, 20, 30, log=True, rtol=np.log(1e-10))\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "np.exp(res.integral), np.exp(res.error)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe limits of integration and elements of `args` may be broadcastable\narrays, and integration is performed elementwise.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy import stats\ndist = stats.gausshyper(13.8, 3.12, 2.51, 5.18)\na, b = dist.support()\nx = np.linspace(a, b, 100)\nres = tanhsinh(dist.pdf, a, x)\nref = dist.cdf(x)\nnp.allclose(res.integral, ref)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nBy default, `preserve_shape` is False, and therefore the callable\n`f` may be called with arrays of any broadcastable shapes.\nFor example:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "shapes = []\ndef f(x, c):\n shape = np.broadcast_shapes(x.shape, c.shape)\n shapes.append(shape)\n return np.sin(c*x)\nc = [1, 10, 30, 100]\nres = tanhsinh(f, 0, 1, args=(c,), minlevel=1)\nshapes\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nTo understand where these shapes are coming from - and to better\nunderstand how `tanhsinh` computes accurate results - note that\nhigher values of ``c`` correspond with higher frequency sinusoids.\nThe higher frequency sinusoids make the integrand more complicated,\nso more function evaluations are required to achieve the target\naccuracy:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "res.nfev\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe initial ``shape``, ``(4,)``, corresponds with evaluating the\nintegrand at a single abscissa and all four frequencies; this is used\nfor input validation and to determine the size and dtype of the arrays\nthat store results. The next shape corresponds with evaluating the\nintegrand at an initial grid of abscissae and all four frequencies.\nSuccessive calls to the function double the total number of abscissae at\nwhich the function has been evaluated. However, in later function\nevaluations, the integrand is evaluated at fewer frequencies because\nthe corresponding integral has already converged to the required\ntolerance. This saves function evaluations to improve performance, but\nit requires the function to accept arguments of any shape.\n\n\"Vector-valued\" integrands, such as those written for use with\n`scipy.integrate.quad_vec`, are unlikely to satisfy this requirement.\nFor example, consider\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def f(x):\n return [x, np.sin(10*x), np.cos(30*x), x*np.sin(100*x)**2]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThis integrand is not compatible with `tanhsinh` as written; for instance,\nthe shape of the output will not be the same as the shape of ``x``. Such a\nfunction *could* be converted to a compatible form with the introduction of\nadditional parameters, but this would be inconvenient. In such cases,\na simpler solution would be to use `preserve_shape`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "shapes = []\ndef f(x):\n shapes.append(x.shape)\n x0, x1, x2, x3 = x\n return [x0, np.sin(10*x1), np.cos(30*x2), x3*np.sin(100*x3)]\na = np.zeros(4)\nres = tanhsinh(f, a, 1, preserve_shape=True)\nshapes\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHere, the broadcasted shape of `a` and `b` is ``(4,)``. With\n``preserve_shape=True``, the function may be called with argument\n``x`` of shape ``(4,)`` or ``(4, n)``, and this is what we observe." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "quad", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.integrate._quadpack_py:quad" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "f", "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": "args", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "()" }, { "__type": "SigParam", "__tag": 4030, "name": "log", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "maxlevel", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "minlevel", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "2" }, { "__type": "SigParam", "__tag": 4030, "name": "atol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "preserve_shape", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "callback", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "tanhsinh" }, "references": [ ".. [1] Bailey, David H., Karthik Jeyabalan, and Xiaoye S. Li. \"A comparison of", " three high-precision quadrature schemes.\" Experimental Mathematics 14.3", " (2005): 317-329.", ".. [2] Vanherck, Joren, Bart Sorée, and Wim Magnus. \"Tanh-sinh quadrature for", " single and multiple integration using floating-point arithmetic.\"", " arXiv preprint arXiv:2007.15057 (2020).", ".. [3] van Engelen, Robert A. \"Improving the Double Exponential Quadrature", " Tanh-Sinh, Sinh-Sinh and Exp-Sinh Formulas.\"", " https://www.genivia.com/files/qthsh.pdf", ".. [4] Takahasi, Hidetosi, and Masatake Mori. \"Double exponential formulas for", " numerical integration.\" Publications of the Research Institute for", " Mathematical Sciences 9.3 (1974): 721-741." ], "qa": "scipy.integrate._tanhsinh:tanhsinh", "arbitrary": [], "local_refs": [ "a", "args", "atol", "b", "callback", "f", "log", "maxlevel", "minlevel", "preserve_shape", "res", "rtol" ] }