Bug
Links
def tanhsinh(f, a, b, *, args=(), log=False, maxlevel=None, minlevel=2, atol=None, rtol=None, preserve_shape=False, callback=None)
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
----------
f : callable
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, b : float array_like
Real lower and upper limits of integration. Must be broadcastable with one
another and with arrays in `args`. Elements may be infinite.
args : tuple 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``.
log : bool, 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 π.
maxlevel : int, 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.
minlevel : int, 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, rtol : float, 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_shape : bool, 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.
callback : callable, 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.)
success : bool array
``True`` when the algorithm terminated successfully (status ``0``).
``False`` otherwise.
status : int 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).
integral : float array
An estimate of the integral.
error : float array
An estimate of the error. Only available if level two or higher
has been completed; otherwise NaN.
maxlevel : int array
The maximum refinement level used.
nfev : int 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] 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.
Améliorations / Corrections
Vous avez des améliorations (ou des corrections) à proposer pour ce document : je vous remerçie par avance de m'en faire part, cela m'aide à améliorer le site.
Emplacement :
Description des améliorations :