NAG CL Interface
d01xbc (multid_​quad_​monte_​carlo_​1)

Settings help

CL Name Style:


1 Purpose

d01xbc evaluates 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.

2 Specification

#include <nag.h>
void  d01xbc (Integer ndim,
double (*f)(Integer ndim, const double x[], Nag_User *comm),
Nag_MCMethod method, Nag_Start cont, const double a[], const double b[], Integer *mincls, Integer maxcls, double eps, double *finest, double *acc, double **comm_arr, Nag_User *comm, NagError *fail)
The function may be called by the names: d01xbc, nag_quad_multid_quad_monte_carlo_1 or nag_multid_quad_monte_carlo_1.

3 Description

d01xbc uses an adaptive Monte–Carlo method based on the algorithm described by Lautrup (1971). It is implemented for integrals of the form:
a 1 b 1 a 2 b 2 a n b n f ( x 1 , x 2 ,, x n ) dxn dx2 dx1 .  
Upon entry, unless the argument method=Nag_OneIteration, 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.

4 References

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

5 Arguments

1: ndim Integer Input
On entry: the number of dimensions of the integral, n .
Constraint: ndim1 .
2: f function, supplied by the user External Function
f must return the value of the integrand f at a given point.
The specification of f is:
double  f (Integer ndim, const double x[], Nag_User *comm)
1: ndim Integer Input
On entry: the number of dimensions of the integral.
2: x[ndim] const double Input
On entry: the coordinates of the point at which the integrand must be evaluated.
3: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type. (See the argument comm below.)
Note: f should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d01xbc. If your code inadvertently does return any NaNs or infinities, d01xbc is likely to produce unexpected results.
3: method Nag_MCMethod Input
On entry: the method to be used.
method=Nag_OneIteration
The function uses only one iteration of a crude Monte–Carlo method with maxcls sample points.
method=Nag_ManyIterations
The function subdivides the integration region into a number of equal volume subregions.
Constraint: method=Nag_OneIteration or Nag_ManyIterations.
4: cont Nag_Start Input
On entry: the continuation state of the evaluation of the integrand.
cont=Nag_Cold
Indicates that this is the first call to the function with the current integrand and arguments ndim, a and b.
cont=Nag_Hot
Indicates that a previous call has been made with the same arguments ndim, a and b with the same integrand. Please note that method must not be changed.
cont=Nag_Warm
Indicates that a previous call has been made with the same arguments ndim, a and b but that the integrand is new. Please note that method must not be changed.
Constraint: cont=Nag_Cold, Nag_Warm or Nag_Hot.
5: a[ndim] const double Input
On entry: the lower limits of integration, a i , for i=1,2,,n.
6: b[ndim] const double Input
On entry: the upper limits of integration, b i , for i=1,2,,n.
7: mincls Integer * Input/Output
On entry: mincls must be set to the minimum number of integrand evaluations to be allowed.
Constraint: 0 mincls < maxcls .
On exit: mincls contains the total number of integrand evaluations actually used by d01xbc.
8: maxcls Integer Input
On entry: 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.
Constraints:
  • maxcls>mincls ;
  • maxcls 4 × (ndim+1) .
9: eps double Input
On entry: the relative accuracy required.
Constraint: eps0.0 .
10: finest double * Output
On exit: the best estimate obtained for the integral.
11: acc double * Output
On exit: the estimated relative accuracy of finest.
12: comm_arr double ** Input/Output
On entry: if cont=Nag_Warm or Nag_Hot, the memory pointed to and allocated by a previous call of d01xbc must be unchanged.
If cont=Nag_Cold then appropriate memory is allocated internally by d01xbc.
On exit: comm_arr contains information about the current sub-interval structure which could be used in later calls of d01xbc. In particular, comm_arr[j-1] gives the number of sub-intervals used along the j th coordinate axis.
When this information is no longer useful, or before a subsequent call to d01xbc with cont=Nag_Cold is made, you should free the storage contained in this pointer using the NAG macro NAG_FREE. Note this memory will have been allocated and needs to be freed only if the error exit NE_NOERROR or NE_QUAD_MAX_INTEGRAND_EVAL occurs. Otherwise, no memory needs to be freed.
13: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp, of type Pointer, allows you to communicate information to and from f(). An object of the required type should be declared, e.g., a structure, and its address assigned to the pointer commp by means of a cast to Pointer in the calling program, e.g., comm.p = (Pointer)&s. The type Pointer is void *.
14: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_2_INT_ARG_GE
On entry, mincls=value while maxcls=value . These arguments must satisfy mincls<maxcls .
NE_2_INT_ARG_LT
On entry, maxcls=value while ndim=value . These arguments must satisfy maxcls 4 × (ndim+1) .
NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_BAD_PARAM
On entry, argument cont had an illegal value.
On entry, argument method had an illegal value.
NE_INT_ARG_LE
On entry, mincls=value.
Constraint: mincls>0.
NE_INT_ARG_LT
On entry, ndim=value.
Constraint: ndim1.
NE_QUAD_MAX_INTEGRAND_EVAL
maxcls was too small to obtain the required accuracy.
In this case d01xbc returns a value of finest with estimated relative error acc, but acc will be greater than eps. This error exit may be taken before maxcls nonzero integrand evaluations have actually occurred, if the function calculates that the current estimates could not be improved before maxcls was exceeded.
NE_REAL_ARG_LT
On entry, eps must not be less than 0.0: eps=value .

7 Accuracy

A relative error estimate is output through the argument acc. The confidence factor is set so that the actual error should be less than acc 90% of the time. If you desire a higher confidence level then a smaller value of eps should be used.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.
d01xbc is not threaded in any implementation.

9 Further Comments

The running time for d01xbc will usually be dominated by the time used to evaluate the integrand f, so the maximum time that could be used is approximately proportional to maxcls.
For some integrands, particularly those that are poorly behaved in a small part of the integration region, this function may terminate with a value of acc which is significantly smaller than the actual relative error. This should be suspected if the returned value of mincls is small relative to the expected difficulty of the integral. Where this occurs, d01xbc should be called again, but with a higher entry value of mincls (e.g., twice the returned value) and the results compared with those from the previous call.

9.1 Additional Information

The exact values of finest and acc on return will depend (within statistical limits) on the sequence of random numbers generated within this function.
If desired, you may ensure the identity or difference between runs of the results returned by this function by calling g05cbc or g05ccc immediately prior to calling this function.
g05cbc has the prototype
void g05cbc(Integer seed)
where seed is a scalar value used to initialize the underlying random number generator. Using the same value for seed will ensure that the same sequence of random values are generated and hence that the same result from this function will be obtained.
g05ccc has the prototype
void g05ccc()
Each time g05ccc is called the underlying random number generator will be reinitialized using a random seed, ensuring a different sequence of values being used. Consequently this function may return different numerical results.

10 Example

This example calculates the integral
0 1 0 1 0 1 0 1 4 x 1 x 3 2 exp(2 x 1 x 3 ) (1+ x 2 + x 4 ) 2 dx1 dx2 dx3 dx4 = 0.575364 .  

10.1 Program Text

Program Text (d01xbce.c)

10.2 Program Data

None.

10.3 Program Results

Program Results (d01xbce.r)