naginterfaces.library.quad.md_numth_vec¶

naginterfaces.library.quad.md_numth_vec(vecfun, vecreg, npts, vk, nrand, itrans=0, data=None)[source]¶

md_numth_vec calculates an approximation to a definite integral in up to $20$ dimensions, using the Korobov–Conroy number theoretic method. This function is designed to be particularly efficient on vector processors.

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

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

Parameters

vecfuncallable fv = vecfun(x, data=None)

$v e c f u n$ must evaluate the integrand at a specified set of points.

Parameters

xfloat, ndarray, shape $(m, ndim)$: The coordinates of the $m$ points at which the integrand must be evaluated. $x [i - 1, j - 1]$ contains the $j$ th coordinate of the $i$ th point.
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

fvfloat, array-like, shape $(m)$: $f v [i - 1]$ must contain the value of the integrand of the $i$ th point, i.e., $f v [i - 1] = f (x [i - 1, 0], x [i - 1, 1], \dots, x [i - 1, ndim - 1])$ , for $i = 1, 2, \dots, m$ .

vecregcallable (c, d) = vecreg(x, j, data=None)

$v e c r e g$ must evaluate the limits of integration in any dimension for a set of points.

Parameters

xfloat, ndarray, shape $(m, ndim)$: For $i = 1, 2, \dots, m$ , $x [i - 1, 0]$ , $x [i - 1, 1], \dots, x [i - 1, j - 2]$ contain the current values of the first $(j - 1)$ coordinates of the $i$ th point, which may be used if necessary in calculating the $m$ values of $c_{j}$ and $d_{j}$ .
jint: The index $j$ for which the limits of the range of integration are required.
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

cfloat, array-like, shape $(m)$: $c [i - 1]$ must be set to the lower limit of the range for $x [i - 1, j - 1]$ , for $i = 1, 2, \dots, m$ .
dfloat, array-like, shape $(m)$: $d [i - 1]$ must be set to the upper limit of the range for $x [i - 1, j - 1]$ , for $i = 1, 2, \dots, m$ .

nptsint

The Korobov rule to be used. There are two alternatives depending on the value of $n p t s$ .

$1 \leq n p t s \leq 6$ .

In this case one of six preset rules is chosen using $2129$ , $5003$ , $10007$ , $20011$ , $40009$ or $80021$ points depending on the respective value of $n p t s$ being $1$ , $2$ , $3$ , $4$ , $5$ or $6$ .
$n p t s > 6$ .

$n p t s$ is the number of actual points to be used with corresponding optimal coefficients supplied in the array $v k$ .

vkfloat, array-like, shape $(ndim)$

If $n p t s > 6$ , $v k$ must contain the $n$ optimal coefficients (which may be calculated using md_numth_coeff_prime() or md_numth_coeff_2prime()).

If $n p t s \leq 6$ , $v k$ need not be set.

nrandint

The number of random samples to be generated (generally a small value, say $3$ to $5$ , is sufficient). The estimate, $r e s$ , of the value of the integral returned by the function is then the average of $n r a n d$ calculations with different random origin shifts. If $n p t s > 6$ , the total number of integrand evaluations will be $n r a n d \times n p t s$ . If $1 \leq n p t s \leq 6$ , the number of integrand evaluations will be $n r a n d \times p$ , where $p$ is the number of points corresponding to the six preset rules. For reasons of efficiency, these values are calculated a number at a time in $v e c f u n$ .

itransint, optional

Indicates whether the periodising transformation is to be used.

$i t r a n s = 0$

The transformation is to be used.

$i t r a n s = 1$

The transformation is to be suppressed (to cover cases where the integrand may already be periodic or where you want to specify a particular transformation in the definition of $v e c f u n$ ).

dataarbitrary, optional

User-communication data for callback functions.

Returns

vkfloat, ndarray, shape $(ndim)$

If $n p t s > 6$ , $v k$ is unchanged.

If $n p t s \leq 6$ , $v k$ contains the $n$ optimal coefficients used by the preset rule.

resfloat

The approximation to the integral $I$ .

errfloat

The standard error as computed from $n r a n d$ sample values. If $n r a n d = 1$ , $e r r$ contains zero.

Raises

NagValueError

(errno $1$ )

On entry, $ndim = ⟨ v a l u e ⟩$ .

Constraint: $1 \leq ndim \leq 20$ .

(errno $2$ )

On entry, $n p t s = ⟨ v a l u e ⟩$ .

Constraint: $n p t s \geq 1$ .

(errno $3$ )

On entry, $n r a n d = ⟨ v a l u e ⟩$ .

Constraint: $n r a n d \geq 1$ .

Notes

md_numth_vec calculates an approximation to the integral

I = \int_{c_{1}}^{d_{1}} \dots \int_{c_{n}}^{d_{n}} f (x_{1}, \dots, x_{n}) d x_{n} \dots d x_{1}

using the Korobov–Conroy number theoretic method (see Korobov (1957), Korobov (1963) and Conroy (1967)). The region of integration defined in (1) is such that generally $c_{i}$ and $d_{i}$ may be functions of $x_{1}, x_{2}, \dots, x_{i - 1}$ , for $i = 2, 3, \dots, n$ , with $c_{1}$ and $d_{1}$ constants. The integral is first of all transformed to an integral over the $n$ -cube ${[0, 1]}^{n}$ by the change of variables

x_{i} = c_{i} + (d_{i} - c_{i}) y_{i}, i = 1, 2, \dots, n .

The method then uses as its basis the number theoretic formula for the $n$ -cube, ${[0, 1]}^{n}$ :

\int_{0}^{1} \dots \int_{0}^{1} g (x_{1}, \dots, x_{n}) d x_{n} \dots d x_{1} = \frac{1}{p} p \sum k = 1 g ({k \frac{a_{1}}{p}}, \dots, {k \frac{a_{n}}{p}}) - E

where ${x}$ denotes the fractional part of $x$ , $a_{1}, \dots, a_{n}$ are the so-called optimal coefficients, $E$ is the error, and $p$ is a prime integer. (It is strictly only necessary that $p$ be relatively prime to all $a_{1}, \dots, a_{n}$ and is in fact chosen to be even for some cases in Conroy (1967).) The method makes use of properties of the Fourier expansion of $g (x_{1}, \dots, x_{n})$ which is assumed to have some degree of periodicity. Depending on the choice of $a_{1}, \dots, a_{n}$ the contributions from certain groups of Fourier coefficients are eliminated from the error, $E$ . Korobov shows that $a_{1}, \dots, a_{n}$ can be chosen so that the error satisfies

E \leq C K p^{- α} {l n}^{α β} (p)

where $α$ and $C$ are real numbers depending on the convergence rate of the Fourier series, $β$ is a constant depending on $n$ , and $K$ is a constant depending on $α$ and $n$ . There are a number of procedures for calculating these optimal coefficients. Korobov imposes the constraint that

a_{1} = 1 and a_{i} = a^{i - 1} (m o d p)

and gives a procedure for calculating the argument, $a$ , to satisfy the optimal conditions.

In this function the periodisation is achieved by the simple transformation

x_{i} = y_{i}^{2} (3 - 2 y_{i}), i = 1, 2, \dots, n .

More sophisticated periodisation procedures are available but in practice the degree of periodisation does not appear to be a critical requirement of the method.

An easily calculable error estimate is not available apart from repetition with an increasing sequence of values of $p$ which can yield erratic results. The difficulties have been studied by Cranley and Patterson (1976) who have proposed a Monte Carlo error estimate arising from converting (2) into a stochastic integration rule by the inclusion of a random origin shift which leaves the form of the error (3) unchanged; i.e., in the formula (2), ${k \frac{a_{i}}{p}}$ is replaced by ${α_{i} + k \frac{a_{i}}{p}}$ , for $i = 1, 2, \dots, n$ , where each $α_{i}$ , is uniformly distributed over $[0, 1]$ . Computing the integral for each of a sequence of random vectors $α$ allows a ‘standard error’ to be estimated.

This function provides built-in sets of optimal coefficients, corresponding to six different values of $p$ . Alternatively, the optimal coefficients may be supplied by you. Functions md_numth_coeff_prime() and md_numth_coeff_2prime() compute the optimal coefficients for the cases where $p$ is a prime number or $p$ is a product of two primes, respectively.

This function is designed to be particularly efficient on vector processors, although it is very important that you also code $v e c f u n$ and $v e c r e g$ efficiently.

References

Conroy, H, 1967, Molecular Shroedinger equation VIII. A new method for evaluting multi-dimensional integrals, J. Chem. Phys. (47), 5307–5318

Cranley, R and Patterson, T N L, 1976, Randomisation of number theoretic methods for mulitple integration, SIAM J. Numer. Anal. (13), 904–914

Korobov, N M, 1957, The approximate calculation of multiple integrals using number theoretic methods, Dokl. Acad. Nauk SSSR (115), 1062–1065

Korobov, N M, 1963, Number Theoretic Methods in Approximate Analysis, Fizmatgiz, Moscow

NAG and Python

Return to Front

naginterfaces.library.quad.md_numth_vec¶

naginterfaces.library.quad.md_​numth_​vec¶

naginterfaces.library.quad.md_numth_vec¶