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 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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/d01/d01gdf.html

Parameters
vecfuncallable fv = vecfun(x, data=None)

must evaluate the integrand at a specified set of points.

Parameters
xfloat, ndarray, shape

The coordinates of the points at which the integrand must be evaluated. contains the th coordinate of the th point.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fvfloat, array-like, shape

must contain the value of the integrand of the th point, i.e., , for .

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

must evaluate the limits of integration in any dimension for a set of points.

Parameters
xfloat, ndarray, shape

For , , contain the current values of the first coordinates of the th point, which may be used if necessary in calculating the values of and .

jint

The index 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

must be set to the lower limit of the range for , for .

dfloat, array-like, shape

must be set to the upper limit of the range for , for .

nptsint

The Korobov rule to be used. There are two alternatives depending on the value of .

1. .

In this case one of six preset rules is chosen using , , , , or points depending on the respective value of being , , , , or .

2. .

is the number of actual points to be used with corresponding optimal coefficients supplied in the array .

vkfloat, array-like, shape

If , must contain the optimal coefficients (which may be calculated using md_numth_coeff_prime() or md_numth_coeff_2prime()).

If , need not be set.

nrandint

The number of random samples to be generated (generally a small value, say to , is sufficient). The estimate, , of the value of the integral returned by the function is then the average of calculations with different random origin shifts. If , the total number of integrand evaluations will be . If , the number of integrand evaluations will be , where 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 .

itransint, optional

Indicates whether the periodising transformation is to be used.

The transformation is to be used.

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 ).

dataarbitrary, optional

User-communication data for callback functions.

Returns
vkfloat, ndarray, shape

If , is unchanged.

If , contains the optimal coefficients used by the preset rule.

resfloat

The approximation to the integral .

errfloat

The standard error as computed from sample values. If , contains zero.

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

Notes

md_numth_vec calculates an approximation to the integral

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 and may be functions of , for , with and constants. The integral is first of all transformed to an integral over the -cube by the change of variables

The method then uses as its basis the number theoretic formula for the -cube, :

where denotes the fractional part of , are the so-called optimal coefficients, is the error, and is a prime integer. (It is strictly only necessary that be relatively prime to all 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 which is assumed to have some degree of periodicity. Depending on the choice of the contributions from certain groups of Fourier coefficients are eliminated from the error, . Korobov shows that can be chosen so that the error satisfies

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

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

In this function the periodisation is achieved by the simple transformation

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 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), is replaced by , for , where each , is uniformly distributed over . 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 . 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 is a prime number or 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 and 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