naginterfaces.library.quad.md_​mcarlo

naginterfaces.library.quad.md_mcarlo(a, b, mincls, maxcls, f, eps, wrkstr, finest, data=None)

md_mcarlo returns an approximation to the integral of a function over a hyper-rectangular region, using a Monte Carlo method. An approximate relative error estimate is also returned. This function is suitable for low accuracy work.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01gbf.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 integrand evaluations to be allowed, in which case $mincls\ge 0$;

or to a negative value. In this case, the function assumes that a previous call had been made with the same arguments $\text{ndim}$, $a$ and $b$ and with either the same integrand (in which case md_mcarlo continues calculation) or a similar integrand (in which case md_mcarlo begins the calculation with the subdivision used in the last iteration of the previous call). See also $wrkstr$.

maxclsint

The maximum number of integrand evaluations to be allowed. In the continuation case this is the number of new integrand evaluations to be allowed. These counts do not include zero integrand values.

fcallable retval = f(x, data=None)

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

Parameters

xfloat, 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 accuracy required.

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

If $mincls<0$, $wrkstr$ must be unchanged from the previous call of md_mcarlo – except that for a new integrand $wrkstr[\text{lenwrk}-1]$ must be set to $0.0$. See also $mincls$.

finestfloat

Must be unchanged from a previous call to md_mcarlo.

dataarbitrary, optional

User-communication data for callback functions.

Returns

minclsint

Contains the number of integrand evaluations actually used by md_mcarlo.

accfloat

The estimated relative accuracy of $finest$.

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

Contains information about the current sub-interval structure which could be used in later calls of md_mcarlo. In particular, $wrkstr[j-1]$ gives the number of sub-intervals used along the $j$th coordinate axis.

finestfloat

The best estimate obtained for the integral.

Raises

NagValueError

(errno $1$)

On entry, $eps=⟨value⟩$.

Constraint: $eps\ge 0.0$.

(errno $1$)

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

Constraint: $maxcls\ge 4\times (\text{ndim}+1)$.

(errno $1$)

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

Constraint: $maxcls>mincls$.

(errno $1$)

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

(errno $1$)

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

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

Warns

NagAlgorithmicWarning

(errno $2$)

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

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_mcarlo uses an adaptive Monte Carlo method based on the algorithm described in Lautrup (1971). It is implemented for integrals of the form:

$${\int }_{a_1}^{b_1}{\int }_{a_2}^{b_2}\cdots {\int }_{a_n}^{b_n}f(x_1,x_2,\dots ,x_n)d{x}_n\cdots d{x}_{2}d{x}_1\text{.}$$

Upon entry, unless $\text{lenwrk}$ has been set to the minimum value $10\times \text{ndim}$, the function subdivides the integration region into a number of equal volume subregions. Inside each subregion the integral and the variance are estimated by means of pseudorandom sampling. All contributions are added together to produce an estimate for the whole integral and total variance. The variance along each coordinate axis is determined and the function uses this information to increase the density and change the widths of the sub-intervals along each axis, so as to reduce the total variance. The total number of subregions is then increased by a factor of two and the program recycles for another iteration. The program stops when a desired accuracy has been reached or too many integral evaluations are needed for the next cycle.

References

Lautrup, B, 1971, An adaptive multi-dimensional integration procedure, Proc. 2nd Coll. Advanced Methods in Theoretical Physics, Marseille