naginterfaces.library.quad.md_​adapt

naginterfaces.library.quad.md_adapt(a, b, minpts, maxpts, f, eps, data=None)

md_adapt attempts to evaluate a multidimensional integral (up to $15$ dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fcf.html

Parameters

afloat, array-like, shape $\left(\text{ndim}\right)$

The lower limits of integration, $a_i$, for $\text{i}=1,2,\dots ,n$.

bfloat, array-like, shape $\left(\text{ndim}\right)$

The upper limits of integration, $b_i$, for $\text{i}=1,2,\dots ,n$.

minptsint

Must be set to the minimum number of integrand evaluations to be allowed.

maxptsint

The maximum number of integrand evaluations to be allowed.

fcallable retval = f(z, data=None)

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

Parameters

zfloat, ndarray, shape $\left(\text{ndim}\right)$

The coordinates of the point at which the integrand $f$ must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of the integrand $f$ at the given point.

epsfloat

The relative error acceptable to you. When the solution is zero or very small relative accuracy may not be achievable but you may still set $eps$ to a reasonable value and check for the error exit $errno$ = 2.

dataarbitrary, optional

User-communication data for callback functions.

Returns

minptsint

Contains the actual number of integrand evaluations used by md_adapt.

accfloat

The estimated relative error in $finval$.

finvalfloat

The best estimate obtained for the integral.

Raises

NagValueError

(errno $1$)

On entry, $maxpts$ is too small. $maxpts=⟨value⟩$. Minimum possible dimension: $⟨value⟩$.

(errno $1$)

On entry, $eps=⟨value⟩$.

Constraint: $eps>0.0$.

(errno $1$)

On entry, $minpts=⟨value⟩$ and $maxpts=⟨value⟩$.

Constraint: $minpts\le maxpts$.

(errno $1$)

On entry, $\text{ndim}=⟨value⟩$.

Constraint: $\text{ndim}\le 15$.

(errno $1$)

On entry, $\text{ndim}=⟨value⟩$.

Constraint: $\text{ndim}\ge 2$.

Warns

NagAlgorithmicWarning

(errno $2$)

$maxpts$ too small to obtain requested accuracy $eps$: $maxpts=⟨value⟩$ and $eps=⟨value⟩$.

(errno $3$)

$\text{lenwrk}$ was too small to complete computation. $finval$ and $acc$ contain estimates of integral and relative error, but $acc$ is greater than $eps$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

md_adapt returns an estimate of a multidimensional integral over a hyper-rectangle (i.e., with constant limits), and also an estimate of the relative error. You set the relative accuracy required, return values for the integrand via a function argument $f$, and also set the minimum and maximum acceptable number of calls to $f$ (in $minpts$ and $maxpts$).

The function operates by repeated subdivision of the hyper-rectangular region into smaller hyper-rectangles. In each subregion, the integral is estimated using a seventh-degree rule, and an error estimate is obtained by comparison with a fifth-degree rule which uses a subset of the same points. The fourth differences of the integrand along each coordinate axis are evaluated, and the subregion is marked for possible future subdivision in half along that coordinate axis which has the largest absolute fourth difference.

If the estimated errors, totalled over the subregions, exceed the requested relative error (or if fewer than $minpts$ calls to $f$ have been made), further subdivision is necessary, and is performed on the subregion with the largest estimated error, that subregion being halved along the appropriate coordinate axis.

The function will fail if the requested relative error level has not been attained by the time $maxpts$ calls to $f$ have been made; or, if the amount $\text{lenwrk}$ of working storage is insufficient. A formula for the recommended value of $\text{lenwrk}$ is given in Parameters. If a smaller value is used, and is exhausted in the course of execution, the function switches to a less efficient mode of operation; only if this mode also breaks down is insufficient storage reported.

md_adapt is based on the HALF function developed by van Dooren and de Ridder (1976). It uses a different basic rule, described in Genz and Malik (1980).

References

Genz, A C and Malik, A A, 1980, An adaptive algorithm for numerical integration over an N-dimensional rectangular region, J. Comput. Appl. Math. (6), 295–302

van Dooren, P and de Ridder, L, 1976, An adaptive algorithm for numerical integration over an N-dimensional cube, J. Comput. Appl. Math. (2), 207–217