naginterfaces.library.quad.dim1_​indef

naginterfaces.library.quad.dim1_indef(a, b, f, relacc, absacc, maxrul, iparm, alpha, data=None)

dim1_indef computes definite and indefinite integrals over a finite range to a specified relative or absolute accuracy, using the method described in Patterson (1968).

For full information please refer to the NAG Library document for d01ar

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/d01/d01arf.html

Parameters

afloat

$a$, the lower limit of integration.

bfloat

$b$, the upper limit of integration. It is not necessary that $a<b$.

fcallable retval = f(x, data=None)

$f$ must return the value of the integrand at a given point.

Parameters

xfloat

The point in $[a,b]$ at which the integrand $f$ must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $f\left(x\right)$ evaluated at $x$.

relaccfloat

The relative accuracy required. If convergence according to absolute accuracy is required, $relacc$ should be set to zero (but see also Accuracy). If $relacc<0.0$, its absolute value is used.

If $iparm=2$, $relacc$ is not used.

absaccfloat

The absolute accuracy required. If convergence according to relative accuracy is required, $absacc$ should be set to zero (but see also Accuracy). If $absacc<0.0$, its absolute value is used.

If $iparm=2$, $absacc$ is not used.

maxrulint

The maximum number of successive rules that may be used.

iparmint

Indicates the task to be performed by the function.

$iparm=0$

Only the definite integral over $[a,b]$ is evaluated.

$iparm=1$

As well as the definite integral, the expansion of the integrand in Legendre polynomials over $[a,b]$ is calculated, using the same values of the integrand as used to compute the integral. The expansion coefficients, and some other quantities, are returned in $alpha$ for later use in computing indefinite integrals.

$iparm=2$

$f\left(t\right)$ is integrated analytically over $[a,b]$ using the previously computed expansion, stored in $alpha$. No further evaluations of the integrand are required. The function must previously have been called with $iparm=1$ and the interval $[a,b]$ must lie within that specified for the previous call. In this case only the arguments $a$, $b$, $iparm$, $ans$ and $alpha$ are used.

alphafloat, array-like, shape $\left(390\right)$

If $iparm=2$, $alpha$ must contain the coefficients of the Legendre expansions of the integrand, as returned by a previous call of dim1_indef with $iparm=1$ and a range containing the present range.

If $iparm=0$ or $1$, $alpha$ need not be set on entry.

dataarbitrary, optional

User-communication data for callback functions.

Returns

accfloat

If $iparm=0$ or $1$, $acc$ contains the absolute value of the difference between the last two successive estimates of the integral. This may be used as a measure of the accuracy actually achieved.

If $iparm=2$, $acc$ is not used.

ansfloat

The estimated value of the integral.

nint

When $iparm=0$ or $1$, $n$ contains the number of integrand evaluations used in the calculation of the integral.

If $iparm=2$, $n$ is not used.

alphafloat, ndarray, shape $\left(390\right)$

If $iparm=1$, the first $m$ elements of $alpha$ hold the coefficients of the Legendre expansion of the integrand, and the value of $m$ is stored in $alpha\left[389\right]$. $alpha$ must not be changed between a call with $iparm=1$ and subsequent calls with $iparm=2$.

If $iparm=2$, the first $m$ elements of $alpha$ are unchanged on exit.

Raises

NagValueError

(errno $2$)

On entry, $iparm=⟨value⟩$.

Constraint: $iparm=0$, $1$ or $2$.

(errno $3$)

The function was called with $iparm=2$, but a previous call with $iparm=1$ has been omitted, or made with zero integration interval.

(errno $4$)

The function was called with $iparm=2$, but the interval for indefinite integration is not contained within the interval specified in the previous call with $iparm=1$.

Warns

NagAlgorithmicWarning

(errno $1$)

All $maxrul$ rules have been used but the integral has not converged to the accuracy requested. $maxrul=⟨value⟩$.

(errno $1$)

Failure in convergence during the run with $iparm=1$ in which the Legendre expansion was created.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

dim1_indef evaluates definite and indefinite integrals of the form:

$${\int }_a^{b}f\left(t\right)dt$$

using the method described in Patterson (1968).

Definite Integrals

In this case dim1_indef must be called with $iparm=0$. By linear transformation the integral is changed to

$$I={\int }_{-1}^{+1}F\left(x\right)dx$$

where

$$F\left(x\right)=\frac{b-a}{2}f\left(\frac{b+a+(b-a)x}{2}\right)$$

and is then approximated by an $n$-point quadrature rule

$$I=\sum _{k=1}^n{w}_{k}F\left(x_k\right)$$

where $w_k$ are the weights and $x_k$ are the abscissae.

The function uses a family of nine interlacing rules based on the optimal extension of the three-point Gauss rule. These rules use $1$, $3$, $7$, $15$, $31$, $63$, $127$, $255$ and $511$ points and have respective polynomial integrating degrees $1$, $5$, $11$, $23$, $47$, $95$, $191$, $383$ and $767$. Each rule has the property that the next in sequence includes all the points of its predecessor and has the greatest possible increase in integrating degree.

The integration method is based on the successive application of these rules until the absolute value of the difference of two successive results differs by not more than $absacc$, or relatively by not more than $relacc$. The result of the last rule used is taken as the value of the integral ($ans$), and the absolute difference of the results of the last two rules used is taken as an estimate of the absolute error ($acc$). Due to their interlacing form no integrand evaluations are wasted in passing from one rule to the next.

Indefinite Integrals

Suppose the value of the integral

$${\int }_c^{d}f\left(t\right)dt$$

is required for a number of sub-intervals $[c,d]$, all of which lie in an interval $[a,b]$.

In this case dim1_indef should first be called with the argument $iparm=1$ and the interval set to $[a,b]$. The function then calculates the integral over $[a,b]$ and the Legendre expansion of the integrand, using the same integrand values. If the function is subsequently called with $iparm=2$ and the interval set to $[c,d]$, the integral over $[c,d]$ is calculated by analytical integration of the Legendre expansion, without further evaluations of the integrand.

For the interval $[-1,1]$ the expansion takes the form

$$F\left(x\right)=\sum _{i=0}^{\infty }{\alpha }_i{P}_i\left(x\right)$$

where $P_i\left(x\right)$ is the order $i$ Legendre polynomial. Assuming that the integral over the full range $[-1,1]$ was evaluated to the required accuracy using an $n$-point rule, then the coefficients

$${\alpha }_i=\frac{1}{2}(2i-1){\int }_{-1}^{+1}{P}_i\left(x\right)F\left(x\right)dx\text{,}i=0,1,\dots ,m$$

are evaluated by that same rule, up to

$$m=(3n-1)/4\text{.}$$

The accuracy for indefinite integration should be of the same order as that obtained for the definite integral over the full range. The indefinite integrals will be exact when $F\left(x\right)$ is a polynomial of degree $\le m$.

References

Patterson, T N L, 1968, The Optimum addition of points to quadrature formulae, Math. Comput. (22), 847–856