NAG Library Function Document

nag_multid_quad_monte_carlo_1 (d01xbc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{ndim}$ – IntegerInput

On entry: the number of dimensions of the integral, $n$.

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

2:    $\mathbf{f}$ – function, supplied by the userExternal 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:    $\mathbf{ndim}$ – IntegerInput

On entry: the number of dimensions of the integral.

2:    $\mathbf{x}\left[\mathbf{ndim}\right]$ – const doubleInput

On entry: the coordinates of the point at which the integrand must be evaluated.

3:    $\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:

p – Pointer 

On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$ 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 nag_multid_quad_monte_carlo_1 (d01xbc). If your code inadvertently does return any NaNs or infinities, nag_multid_quad_monte_carlo_1 (d01xbc) is likely to produce unexpected results.

3:    $\mathbf{method}$ – Nag_MCMethodInput

On entry: the method to be used.

$\mathbf{method}=\mathrm{Nag\_OneIteration}$

The function uses only one iteration of a crude Monte–Carlo method with maxcls sample points.

$\mathbf{method}=\mathrm{Nag\_ManyIterations}$

The function subdivides the integration region into a number of equal volume subregions.

Constraint: $\mathbf{method}=\mathrm{Nag\_OneIteration}$ or $\mathrm{Nag\_ManyIterations}$.

4:    $\mathbf{cont}$ – Nag_StartInput

On entry: the continuation state of the evaluation of the integrand.

$\mathbf{cont}=\mathrm{Nag\_Cold}$

Indicates that this is the first call to the function with the current integrand and arguments ndim, a and b.

$\mathbf{cont}=\mathrm{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.

$\mathbf{cont}=\mathrm{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: $\mathbf{cont}=\mathrm{Nag\_Cold}$, $\mathrm{Nag\_Warm}$ or $\mathrm{Nag\_Hot}$.

5:    $\mathbf{a}\left[\mathbf{ndim}\right]$ – const doubleInput

On entry: the lower limits of integration, $a_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.

6:    $\mathbf{b}\left[\mathbf{ndim}\right]$ – const doubleInput

On entry: the upper limits of integration, $b_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.

7:    $\mathbf{mincls}$ – Integer *Input/Output

On entry: mincls must be set to the minimum number of integrand evaluations to be allowed.

Constraint: $0\le \mathbf{mincls}<\mathbf{maxcls}$.

On exit: mincls contains the total number of integrand evaluations actually used by nag_multid_quad_monte_carlo_1 (d01xbc).

8:    $\mathbf{maxcls}$ – IntegerInput

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:

• $\mathbf{maxcls}>\mathbf{mincls}$;
• $\mathbf{maxcls}\ge 4\times \left(\mathbf{ndim}+1\right)$.

9:    $\mathbf{eps}$ – doubleInput

On entry: the relative accuracy required.

Constraint: $\mathbf{eps}\ge 0.0$.

10:  $\mathbf{finest}$ – double *Output

On exit: the best estimate obtained for the integral.

11:  $\mathbf{acc}$ – double *Output

On exit: the estimated relative accuracy of finest.

12:  $\mathbf{comm\_arr}$ – double **Input/Output

On entry: if $\mathbf{cont}=\mathrm{Nag\_Warm}$ or $\mathrm{Nag\_Hot}$, the memory pointed to and allocated by a previous call of nag_multid_quad_monte_carlo_1 (d01xbc) must be unchanged.

If $\mathbf{cont}=\mathrm{Nag\_Cold}$ then appropriate memory is allocated internally by nag_multid_quad_monte_carlo_1 (d01xbc).

On exit: comm_arr contains information about the current sub-interval structure which could be used in later calls of nag_multid_quad_monte_carlo_1 (d01xbc). In particular, $\mathbf{comm\_arr}\left[j-1\right]$ 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 nag_multid_quad_monte_carlo_1 (d01xbc) with $\mathbf{cont}=\mathrm{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:  $\mathbf{comm}$ – Nag_User *

Pointer to a structure of type Nag_User with the following member:

p – Pointer 

On entry/exit: the pointer $\mathbf{comm}\mathbf{\to }\mathbf{p}$, 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 $\mathbf{comm}\mathbf{\to }\mathbf{p}$ by means of a cast to Pointer in the calling program, e.g., comm.p = (Pointer)&s. The type Pointer is void *.

14:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_2_INT_ARG_GE

On entry, $\mathbf{mincls}=〈\mathit{\text{value}}〉$ while $\mathbf{maxcls}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{mincls}<\mathbf{maxcls}$.

NE_2_INT_ARG_LT

On entry, $\mathbf{maxcls}=〈\mathit{\text{value}}〉$ while $\mathbf{ndim}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{maxcls}\ge 4\times \left(\mathbf{ndim}+1\right)$.

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, $\mathbf{mincls}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mincls}>0$.

NE_INT_ARG_LT

On entry, $\mathbf{ndim}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ndim}\ge 1$.

NE_QUAD_MAX_INTEGRAND_EVAL

maxcls was too small to obtain the required accuracy.
In this case nag_multid_quad_monte_carlo_1 (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: $\mathbf{eps}=〈\mathit{\text{value}}〉$.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

9.1

Additional Information

void g05cbc(Integer seed)

void g05ccc()

10

Example

10.1

Program Text

Program Text (d01xbce.c)

10.2

Program Data

10.3

Program Results

Program Results (d01xbce.r)