NAG Library Routine Document
D01FCF
1 Purpose
D01FCF attempts to evaluate a multi-dimensional integral (up to 15 dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.
2 Specification
| SUBROUTINE D01FCF ( | NDIM, A, B, MINPTS, MAXPTS, FUNCTN, EPS, ACC, LENWRK, WRKSTR, FINVAL, IFAIL) |
| INTEGER | NDIM, MINPTS, MAXPTS, LENWRK, IFAIL |
| double precision | A(NDIM), B(NDIM), FUNCTN, EPS, ACC, WRKSTR(LENWRK), FINVAL |
| EXTERNAL | FUNCTN |
3 Description
D01FCF returns an estimate of a multi-dimensional integral over a hyper-rectangle (i.e., with constant limits), and also an estimate of the relative error. You set the relative accuracy required, return values for the integrand via a routine argument
FUNCTN, and also set the minimum and maximum acceptable number of calls to
FUNCTN (in
MINPTS and
MAXPTS).
The routine operates by repeated subdivision of the hyper-rectangular region into smaller hyper-rectangles. In each subregion, the integral is estimated using a seventh-degree rule, and an error estimate is obtained by comparison with a fifth-degree rule which uses a subset of the same points. The fourth differences of the integrand along each co-ordinate axis are evaluated, and the subregion is marked for possible future subdivision in half along that co-ordinate axis which has the largest absolute fourth difference.
If the estimated errors, totalled over the subregions, exceed the requested relative error (or if fewer than
MINPTS calls to
FUNCTN have been made), further subdivision is necessary, and is performed on the subregion with the largest estimated error, that subregion being halved along the appropriate co-ordinate axis.
The routine will fail if the requested relative error level has not been attained by the time
MAXPTS calls to
FUNCTN have been made; or, if the amount
LENWRK of working storage is insufficient. A formula for the recommended value of
LENWRK is given in
Section 5. If a smaller value is used, and is exhausted in the course of execution, the routine switches to a less efficient mode of operation; only if this mode also breaks down is insufficient storage reported.
D01FCF is based on the HALF subroutine developed by
van Dooren and de Ridder (1976). It uses a different basic rule, described in
Genz and Malik (1980).
4 References
Genz A C and Malik A A (1980) An Adaptive Algorithm for Numerical Integration over an N-dimensional Rectangular Region
J. Comput. Appl. Math. 6 295–302
van Dooren P and de Ridder L (1976) An adaptive algorithm for numerical integration over an N-dimensional cube
J. Comput. Appl. Math. 2 207–217
5 Parameters
- 1: NDIM – INTEGERInput
On entry:
n, the number of dimensions of the integral.
Constraint:
2≤NDIM≤15.
- 2: A(NDIM) – double precision arrayInput
On entry: the lower limits of integration, ai, for i=1,2,…,n.
- 3: B(NDIM) – double precision arrayInput
On entry: the upper limits of integration, bi, for i=1,2,…,n.
- 4: 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: MAXPTS – INTEGERInput
On entry: the maximum number of integrand evaluations to be allowed.
Constraints:
- MAXPTS≥MINPTS;
- MAXPTS≥α,
where α=2NDIM+2×NDIM2+2×NDIM+1.
- 6: FUNCTN – double precision 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:
| double precision FUNCTION FUNCTN ( | NDIM, Z) |
| INTEGER | NDIM |
| double precision | Z(NDIM) |
- 1: NDIM – INTEGERInput
On entry: n, the number of dimensions of the integral.
- 2: Z(NDIM) – double precision arrayInput
On entry: the co-ordinates of the point at which the integrand f must be evaluated.
FUNCTN must be declared as EXTERNAL in the (sub)program from which D01FCF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 7: EPS – double precisionInput
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
IFAIL=2.
Constraint:
EPS>0.0.
- 8: ACC – double precisionOutput
On exit: the estimated relative error in
FINVAL.
- 9: 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,
LENWRK≥NDIM+2×1+MAXPTS/α (see parameter
MAXPTS for
α).
If
LENWRK is less than this, D01FCF will usually run less efficiently and may fail.
Constraint:
LENWRK≥2×NDIM+4.
- 10: WRKSTR(LENWRK) – double precision arrayWorkspace
- 11: FINVAL – double precisionOutput
On exit: the best estimate obtained for the integral.
- 12: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 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 parameters may be useful even if
IFAIL≠0 on exit, the recommended value is
-1.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
6 Error Indicators and Warnings
If on entry
IFAIL=0 or
-1, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Note: D01FCF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
- IFAIL=1
-
| On entry, | NDIM<2, |
| or | NDIM>15, |
| or | MAXPTS is too small, |
| or | LENWRK<2×NDIM+4, |
| or | EPS≤0.0. |
- 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.
- 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.
7 Accuracy
A relative error estimate is output through the parameter
ACC.
8 Further Comments
Execution time will usually be dominated by the time taken to evaluate
FUNCTN, and hence the maximum time that could be taken will be proportional to
MAXPTS.
9 Example
This example estimates the integral
The accuracy requested is one part in 10000.
9.1 Program Text
Program Text (d01fcfe.f)
9.2 Program Data
None.
9.3 Program Results
Program Results (d01fcfe.r)