NAG Library Routine Document

d01fcf  (md_adapt)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{ndim}$ – IntegerInput

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

Constraint: $2\le \mathbf{ndim}\le 15$.

2:     $\mathbf{a}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

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

3:     $\mathbf{b}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

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

4:     $\mathbf{minpts}$ – IntegerInput/Output

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

On exit: contains the actual number of integrand evaluations used by d01fcf.

5:     $\mathbf{maxpts}$ – IntegerInput

On entry: the maximum number of integrand evaluations to be allowed.

Constraints:

• $\mathbf{maxpts}\ge \mathbf{minpts}$;
• $\mathbf{maxpts}\ge \alpha$, where $\alpha =2^{\mathbf{ndim}}+2\times {\mathbf{ndim}}^2+2\times \mathbf{ndim}+1$.

6:     $\mathbf{functn}$ – real (Kind=nag_wp) Function, supplied by the user.External Procedure

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

The specification of functn is:

Fortran Interface

Function functn ( ndim, z) Real (Kind=nag_wp) :: functn Integer, Intent (In) :: ndim Real (Kind=nag_wp), Intent (In) :: z(ndim)

C Header Interface

#include nagmk26.h double  functn ( const Integer *ndim, const double z[])

1:     $\mathbf{ndim}$ – IntegerInput

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

2:     $\mathbf{z}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) arrayInput

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

functn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d01fcf is called. Arguments denoted as Input must not be changed by this procedure.

Note: functn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d01fcf. If your code inadvertently does return any NaNs or infinities, d01fcf is likely to produce unexpected results.

7:     $\mathbf{eps}$ – Real (Kind=nag_wp)Input

On entry: the relative error acceptable to you. When the solution is zero or very small relative accuracy may not be achievable but you may still set eps to a reasonable value and check for the error exit $\mathbf{ifail}=\mathbf{2}$.

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

8:     $\mathbf{acc}$ – Real (Kind=nag_wp)Output

On exit: the estimated relative error in finval.

9:     $\mathbf{lenwrk}$ – IntegerInput

On entry: the dimension of the array wrkstr as declared in the (sub)program from which d01fcf is called.

Suggested value: for maximum efficiency, $\mathbf{lenwrk}\ge \left(\mathbf{ndim}+2\right)\times \left(1+\mathbf{maxpts}/\alpha \right)$ (see argument maxpts for $\alpha$).

If lenwrk is less than this, d01fcf will usually run less efficiently and may fail.

Constraint: $\mathbf{lenwrk}\ge 2\times \mathbf{ndim}+4$.

10:   $\mathbf{wrkstr}\left(\mathbf{lenwrk}\right)$ – Real (Kind=nag_wp) arrayWorkspace

11:   $\mathbf{finval}$ – Real (Kind=nag_wp)Output

On exit: the best estimate obtained for the integral.

12:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if $\mathbf{ifail}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6

Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry,	$\mathbf{ndim}<2$,
or	$\mathbf{ndim}>15$,
or	maxpts is too small,
or	$\mathbf{lenwrk}<2\times \mathbf{ndim}+4$,
or	$\mathbf{eps}\le 0.0$.

$\mathbf{ifail}=2$

maxpts was too small to obtain the required relative accuracy eps. On soft failure, finval and acc contain estimates of the integral and the relative error, but acc will be greater than eps.

$\mathbf{ifail}=3$

lenwrk was too small. On soft failure, finval and acc contain estimates of the integral and the relative error, but acc will be greater than eps.

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (d01fcfe.f90)

10.2

Program Data

10.3

Program Results

Program Results (d01fcfe.r)