scipy.integrate.

tanhsinh#

scipy.integrate.tanhsinh(f, a, b, *, args=(), log=False, maxlevel=None, minlevel=2, atol=None, rtol=None, preserve_shape=False, callback=None)[source]#

Evaluate a convergent integral numerically using tanh-sinh quadrature.

In practice, tanh-sinh quadrature achieves quadratic convergence for many integrands: the number of accurate digits scales roughly linearly with the number of function evaluations [1].

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 tanhsinh on each sub-interval separately.

Parameters:

fcallable

The function to be integrated. The signature must be:

f(xi: ndarray, *argsi) -> ndarray

where each element of xi is a finite real number and argsi is a tuple, which may contain an arbitrary number of arrays that are broadcastable with xi. f must be an elementwise function: see documentation of parameter preserve_shape for details. It must not mutate the array xi or the arrays in argsi. If f returns a value with complex dtype when evaluated at either endpoint, subsequent arguments x will have complex dtype (but zero imaginary part).

a, bfloat array_like

Real lower and upper limits of integration. Must be broadcastable with one another and with arrays in args. Elements may be infinite.

argstuple of array_like, optional

Additional positional array arguments to be passed to f. Arrays must be broadcastable with one another and the arrays of a and b. If the callable for which the root is desired requires arguments that are not broadcastable with x, wrap that callable with f such that f accepts only x and broadcastable *args.

logbool, default: False

Setting to True indicates that f returns the log of the integrand and that atol and rtol 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 log=True, the integrand (the exponential of f) 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 π.

maxlevelint, default: 10

The maximum refinement level of the algorithm.

At the zeroth level, f is called once, performing 16 function evaluations. At each subsequent level, f 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).

The algorithm will terminate after completing level maxlevel or after another termination condition is satisfied, whichever comes first.

minlevelint, default: 2

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 number of times f is called. If minlevel=k, then the integrand is evaluated at all abscissae from levels 0 through k in a single call. Note that if minlevel exceeds maxlevel, the provided minlevel is ignored, and minlevel is set equal to maxlevel.

atol, rtolfloat, optional

Absolute termination tolerance (default: 0) and relative termination tolerance (default: eps**0.75, where eps is the precision of the result dtype), respectively. Iteration will stop when res.error < atol + rtol * abs(res.df). The error estimate is as described in [1] Section 5. While not theoretically rigorous or conservative, it is said to work well in practice. Must be non-negative and finite if log is False, and must be expressed as the log of a non-negative and finite number if log is True.

preserve_shapebool, default: False

In the following, “arguments of f” refers to the array xi and any arrays within argsi. Let shape be the broadcasted shape of a, b, and all elements of args (which is conceptually distinct from xi` and ``argsi passed into f).

When preserve_shape=False (default), f must accept arguments of any broadcastable shapes.
When preserve_shape=True, f must accept arguments of shape shape or shape + (n,), where (n,) is the number of abscissae at which the function is being evaluated.

In either case, for each scalar element xi[j] within xi, the array returned by f must include the scalar f(xi[j]) at the same index. Consequently, the shape of the output is always the shape of the input xi.

See Examples.

callbackcallable, optional

An optional user-supplied function to be called before the first iteration and after each iteration. Called as callback(res), where res is a _RichResult similar to that returned by _differentiate (but containing the current iterate’s values of all variables). If callback raises a StopIteration, the algorithm will terminate immediately and tanhsinh will return a result object. callback must not mutate res or its attributes.

Returns:

res_RichResult

An object similar to an instance of scipy.optimize.OptimizeResult with the following attributes. (The descriptions are written as though the values will be scalars; however, if f returns an array, the outputs will be arrays of the same shape.)

successbool array

True when the algorithm terminated successfully (status 0). False otherwise.

statusint array

An integer representing the exit status of the algorithm.

0 : The algorithm converged to the specified tolerances. -1 : (unused) -2 : The maximum number of iterations was reached. -3 : A non-finite value was encountered. -4 : Iteration was terminated by callback. 1 : The algorithm is proceeding normally (in callback only).

integralfloat array

An estimate of the integral.

errorfloat array

An estimate of the error. Only available if level two or higher has been completed; otherwise NaN.

maxlevelint array

The maximum refinement level used.

nfevint array

The number of points at which f was evaluated.

See also

quad

Notes

Implements the algorithm as described in [1] with minor adaptations for finite-precision arithmetic, including some described by [2] and [3]. The tanh-sinh scheme was originally introduced in [4].

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.

References

[1] (1,2,3)

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.

Examples

Evaluate the Gaussian integral:

>>> import numpy as np
>>> from scipy.integrate import tanhsinh
>>> def f(x):
...     return np.exp(-x**2)
>>> res = tanhsinh(f, -np.inf, np.inf)
>>> res.integral  # true value is np.sqrt(np.pi), 1.7724538509055159
1.7724538509055159
>>> res.error  # actual error is 0
4.0007963937534104e-16

The value of the Gaussian function (bell curve) is nearly zero for arguments sufficiently far from zero, so the value of the integral over a finite interval is nearly the same.

>>> tanhsinh(f, -20, 20).integral
1.772453850905518

However, with unfavorable integration limits, the integration scheme may not be able to find the important region.

>>> tanhsinh(f, -np.inf, 1000).integral
4.500490856616431

In such cases, or when there are singularities within the interval, break the integral into parts with endpoints at the important points.

>>> tanhsinh(f, -np.inf, 0).integral + tanhsinh(f, 0, 1000).integral
1.772453850905404

For integration involving very large or very small magnitudes, use log-integration. (For illustrative purposes, the following example shows a case in which both regular and log-integration work, but for more extreme limits of integration, log-integration would avoid the underflow experienced when evaluating the integral normally.)

>>> res = tanhsinh(f, 20, 30, rtol=1e-10)
>>> res.integral, res.error
(4.7819613911309014e-176, 4.670364401645202e-187)
>>> def log_f(x):
...     return -x**2
>>> res = tanhsinh(log_f, 20, 30, log=True, rtol=np.log(1e-10))
>>> np.exp(res.integral), np.exp(res.error)
(4.7819613911306924e-176, 4.670364401645093e-187)

The limits of integration and elements of args may be broadcastable arrays, and integration is performed elementwise.

>>> from scipy import stats
>>> dist = stats.gausshyper(13.8, 3.12, 2.51, 5.18)
>>> a, b = dist.support()
>>> x = np.linspace(a, b, 100)
>>> res = tanhsinh(dist.pdf, a, x)
>>> ref = dist.cdf(x)
>>> np.allclose(res.integral, ref)
True

By default, preserve_shape is False, and therefore the callable f may be called with arrays of any broadcastable shapes. For example:

>>> shapes = []
>>> def f(x, c):
...    shape = np.broadcast_shapes(x.shape, c.shape)
...    shapes.append(shape)
...    return np.sin(c*x)
>>>
>>> c = [1, 10, 30, 100]
>>> res = tanhsinh(f, 0, 1, args=(c,), minlevel=1)
>>> shapes
[(4,), (4, 34), (4, 32), (3, 64), (2, 128), (1, 256)]

To understand where these shapes are coming from - and to better understand how tanhsinh computes accurate results - note that higher values of c correspond with higher frequency sinusoids. The higher frequency sinusoids make the integrand more complicated, so more function evaluations are required to achieve the target accuracy:

>>> res.nfev
array([ 67, 131, 259, 515], dtype=int32)

The initial shape, (4,), corresponds with evaluating the integrand at a single abscissa and all four frequencies; this is used for input validation and to determine the size and dtype of the arrays that store results. The next shape corresponds with evaluating the integrand at an initial grid of abscissae and all four frequencies. Successive calls to the function double the total number of abscissae at which the function has been evaluated. However, in later function evaluations, the integrand is evaluated at fewer frequencies because the corresponding integral has already converged to the required tolerance. This saves function evaluations to improve performance, but it requires the function to accept arguments of any shape.

“Vector-valued” integrands, such as those written for use with scipy.integrate.quad_vec, are unlikely to satisfy this requirement. For example, consider

>>> def f(x):
...    return [x, np.sin(10*x), np.cos(30*x), x*np.sin(100*x)**2]

This integrand is not compatible with tanhsinh as written; for instance, the shape of the output will not be the same as the shape of x. Such a function could be converted to a compatible form with the introduction of additional parameters, but this would be inconvenient. In such cases, a simpler solution would be to use preserve_shape.

>>> shapes = []
>>> def f(x):
...     shapes.append(x.shape)
...     x0, x1, x2, x3 = x
...     return [x0, np.sin(10*x1), np.cos(30*x2), x3*np.sin(100*x3)]
>>>
>>> a = np.zeros(4)
>>> res = tanhsinh(f, a, 1, preserve_shape=True)
>>> shapes
[(4,), (4, 66), (4, 64), (4, 128), (4, 256)]

Here, the broadcasted shape of a and b is (4,). With preserve_shape=True, the function may be called with argument x of shape (4,) or (4, n), and this is what we observe.