naginterfaces.library.quad.md_​adapt_​multi

naginterfaces.library.quad.md_adapt_multi(a, b, mincls, maxcls, nfun, funsub, absreq, relreq, wrkstr, data=None)

md_adapt_multi computes approximations to the integrals of a vector of similar functions, each defined over the same multidimensional hyper-rectangular region. The function uses an adaptive subdivision strategy, and also computes absolute error estimates.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/d01/d01eaf.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$.

minclsint

Must be set either to the minimum number of $funsub$ calls to be allowed, in which case $mincls\ge 0$ or to a negative value. In this case, the function continues the calculation started in a previous call with the same integrands and integration limits: no arguments other than $mincls$, $maxcls$, $absreq$ or $relreq$ must be changed between the calls.

maxclsint

The maximum number of $funsub$ calls to be allowed. In the continuation case this is the number of new $funsub$ calls to be allowed.

nfunint

$m$, the number of integrands.

funsubcallable f = funsub(z, nfun, data=None)

$funsub$ must evaluate the integrands $f_i$ at a given point.

Parameters

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

The coordinates of the point at which the integrands must be evaluated.

nfunint

$m$, the number of integrands.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

ffloat, array-like, shape $\left(nfun\right)$

The value of the $i$th integrand at the given point.

absreqfloat

The absolute accuracy required by you.

relreqfloat

The relative accuracy required by you.

wrkstrfloat, array-like, shape $\left(\text{lenwrk}\right)$

If $mincls<0$, $wrkstr$ must be unchanged from the previous call of md_adapt_multi.

dataarbitrary, optional

User-communication data for callback functions.

Returns

minclsint

Gives the number of $funsub$ calls actually used by md_adapt_multi. For the continuation case ($mincls<0$ on entry) this is the number of new $funsub$ calls on the current call to md_adapt_multi.

wrkstrfloat, ndarray, shape $\left(\text{lenwrk}\right)$

Contains information about the current subdivision which could be used in a continuation call.

finestfloat, ndarray, shape $\left(nfun\right)$

$finest[\text{i}-1]$ specifies the best estimate obtained from the $\text{i}$th integral, for $\text{i}=1,2,\dots ,m$.

absestfloat, ndarray, shape $\left(nfun\right)$

$absest[\text{i}-1]$ specifies the estimated absolute accuracy of $finest[\text{i}-1]$, for $\text{i}=1,2,\dots ,m$.

Raises

NagValueError

(errno $4$)

On entry, $maxcls=⟨value⟩$ and $R=⟨value⟩$.

Constraint: $maxcls\ge R=1+\text{ndim}\times (4\times {\text{ndim}}^2-6\times \text{ndim}+14)/3$.

(errno $4$)

On entry, $maxcls=⟨value⟩$ and $R=⟨value⟩$.

Constraint: $maxcls\ge R=2^{\text{ndim}}+2\times {\text{ndim}}^2+2\times \text{ndim}+1$.

(errno $4$)

On entry, $\text{lenwrk}$ is too small. $\text{lenwrk}=⟨value⟩$. Minimum possible dimension: $⟨value⟩$.

(errno $4$)

On entry, $maxcls=⟨value⟩$ and $mincls=⟨value⟩$.

Constraint: $maxcls\ge mincls$.

(errno $4$)

On entry, $nfun=⟨value⟩$.

Constraint: $nfun\ge 1$.

(errno $4$)

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

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

Warns

NagAlgorithmicWarning

(errno $1$)

$maxcls$ too small to obtain required accuracy. $maxcls=⟨value⟩$.

(errno $2$)

$\text{lenwrk}$ too small for the function to continue. $\text{lenwrk}=⟨value⟩$.

(errno $3$)

$maxcls$ too small to make any progress. $maxcls=⟨value⟩$.

Notes

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

md_adapt_multi uses a globally adaptive method based on the algorithm described by van Dooren and de Ridder (1976) and Genz and Malik (1980). It is implemented for integrals in the form:

$${\int }_{a_1}^{b_1}{\int }_{a_2}^{b_2}\dots {\int }_{a_n}^{b_n}(f_1,f_2,\dots ,f_m)d{x}_n\dots d{x}_{2}d{x}_1\text{,}$$

where $f_i=f_i(x_1,x_2,\dots ,x_n)$, for $i=1,2,\dots ,m$.

Upon entry, unless $mincls$ has been set to a value less than or equal to $0$, md_adapt_multi divides the integration region into a number of subregions with randomly selected volumes. Inside each subregion the integrals and their errors are estimated. The initial number of subregions is chosen to be as large as possible without using more than $mincls$ calls to $funsub$. The results are stored in a partially ordered list (a heap). The function then proceeds in stages. At each stage the subregion with the largest error (measured using the maximum norm) is halved along the coordinate axis where the integrands have largest absolute fourth differences. The basic rule is applied to each half of this subregion and the results are stored in the list. The results from the two halves are used to update the global integral and error estimates ($finest$ and $absest$) and the function continues unless $\parallel absest\parallel \le max(absreq,\parallel finest\parallel \times relreq)$ where the norm $\parallel .\parallel$ is the maximum norm, or further subdivision would use more than $maxcls$ calls to $funsub$. If at some stage there is insufficient working storage to keep the results for the next subdivision, the function switches to a less efficient mode; only if this mode of operation breaks down is insufficient storage reported.

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