NAG Library Routine Document
D01FDF
1 Purpose
D01FDF calculates an approximation to a definite integral in up to
30 dimensions, using the method of Sag and Szekeres (see
Sag and Szekeres (1964)). The region of integration is an
n-sphere, or by built-in transformation via the unit
n-cube, any product region.
2 Specification
| SUBROUTINE D01FDF ( | NDIM, F, SIGMA, REGION, LIMIT, R0, U, RESULT, NCALLS, IFAIL) |
| INTEGER | NDIM, LIMIT, NCALLS, IFAIL |
| double precision | F, SIGMA, R0, U, RESULT |
| EXTERNAL | F, REGION |
3 Description
D01FDF calculates an approximation to
or, more generally,
where each
ci and
di may be functions of
xj j<i.
The routine uses the method of
Sag and Szekeres (1964), which exploits a property of the shifted
p-point trapezoidal rule, namely, that it integrates exactly all polynomials of degree
<p (see
Krylov (1962)). An attempt is made to induce periodicity in the integrand by making a parameterized transformation to the unit
n-sphere. The Jacobian of the transformation and all its direct derivatives vanish rapidly towards the surface of the unit
n-sphere, so that, except for functions which have strong singularities on the boundary, the resulting integrand will be pseudo-periodic. In addition, the variation in the integrand can be considerably reduced, causing the trapezoidal rule to perform well.
Integrals of the form
(1) are transformed to the unit
n-sphere by the change of variables:
where
r2=∑i=1nyi2 and
u is an adjustable parameter.
Integrals of the form
(2) are first of all transformed to the
n-cube
-1,1n by a linear change of variables
and then to the unit sphere by a further change of variables
where
r2=∑i=1nzi2 and
u is again an adjustable parameter.
The parameter u in these transformations determines how the transformed integrand is distributed between the origin and the surface of the unit n-sphere. A typical value of u is 1.5. For larger u, the integrand is concentrated toward the centre of the unit n-sphere, while for smaller u it is concentrated toward the perimeter.
In performing the integration over the unit
n-sphere by the trapezoidal rule, a displaced equidistant grid of size
h is constructed. The points of the mesh lie on concentric layers of radius
The routine requires you to specify an approximate maximum number of points to be used, and then computes the largest number of whole layers to be used, subject to an upper limit of
400 layers.
In practice, the rapidly-decreasing Jacobian makes it unnecessary to include the whole unit n-sphere and the integration region is limited by a user-specified cut-off radius r0<1. The grid-spacing h is determined by r0 and the number of layers to be used. A typical value of r0 is 0.8.
Some experimentation may be required with the choice of
r0 (which determines how much of the unit
n-sphere is included) and
u (which determines how the transformed integrand is distributed between the origin and surface of the unit
n-sphere), to obtain best results for particular families of integrals. This matter is discussed further in
Section 8.
4 References
Krylov V I (1962)
Approximate Calculation of Integrals (trans A H Stroud) Macmillan
Sag T W and Szekeres G (1964) Numerical evaluation of high-dimensional integrals
Math. Comput. 18 245–253
5 Parameters
- 1: NDIM – INTEGERInput
On entry: n, the number of dimensions of the integral.
Constraint:
1≤NDIM≤30.
- 2: F – double precision FUNCTION, supplied by the user.External Procedure
F must return the value of the integrand
f at a given point.
The specification of
F is:
| double precision FUNCTION F ( | NDIM, X) |
| INTEGER | NDIM |
| double precision | X(NDIM) |
- 1: NDIM – INTEGERInput
On entry: n, the number of dimensions of the integral.
- 2: X(NDIM) – double precision arrayInput
On entry: the co-ordinates of the point at which the integrand f must be evaluated.
F must be declared as EXTERNAL in the (sub)program from which D01FDF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 3: SIGMA – double precisionInput
On entry: indicates the region of integration.
- SIGMA≥0.0
- The integration is carried out over the n-sphere of radius SIGMA, centred at the origin.
- SIGMA<0.0
- The integration is carried out over the product region described by REGION.
- 4: REGION – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
If
SIGMA<0.0,
REGION must evaluate the limits of integration in any dimension.
The specification of
REGION is:
| SUBROUTINE REGION ( | NDIM, X, J, C, D) |
| INTEGER | NDIM, J |
| double precision | X(NDIM), C, D |
- 1: NDIM – INTEGERInput
On entry: n, the number of dimensions of the integral.
- 2: X(NDIM) – double precision arrayInput
On entry: X1,…,Xj-1 contain the current values of the first j-1 variables, which may be used if necessary in calculating cj and dj.
- 3: J – INTEGERInput
On entry: the index j for which the limits of the range of integration are required.
- 4: C – double precisionOutput
On exit: the lower limit cj of the range of xj.
- 5: D – double precisionOutput
On exit: the upper limit dj of the range of xj.
REGION must be declared as EXTERNAL in the (sub)program from which D01FDF is called. Parameters denoted as
Input must
not be changed by this procedure.
If
SIGMA≥0.0,
REGION is not called by D01FDF, but a dummy routine must be supplied (D01FDV may be used).
- 5: LIMIT – INTEGERInput
On entry: the approximate maximum number of integrand evaluations to be used.
Constraint:
LIMIT≥100.
- 6: R0 – double precisionInput
On entry: the cut-off radius on the unit n-sphere, which may be regarded as an adjustable parameter of the method.
Suggested value:
a typical value is
R0=0.8. (See also
Section 8.)
Constraint:
0.0<R0<1.0.
- 7: U – double precisionInput
On entry: must specify an adjustable parameter of the transformation to the unit n-sphere.
Suggested value:
a typical value is
U=1.5. (See also
Section 8.)
Constraint:
U>0.0.
- 8: RESULT – double precisionOutput
On exit: the approximation to the integral I.
- 9: NCALLS – INTEGEROutput
On exit: the actual number of integrand evaluations used. (See also
Section 8.)
- 10: 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, if you are not familiar with this parameter, the recommended value is
0.
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).
Errors or warnings detected by the routine:
- IFAIL=1
-
| On entry, | NDIM<1, |
| or | NDIM>30. |
- IFAIL=2
-
- IFAIL=3
-
| On entry, | R0≤0.0, |
| or | R0≥1.0. |
- IFAIL=4
-
7 Accuracy
No error estimate is returned, but results may be verified by repeating with an increased value of
LIMIT (provided that this causes an increase in the returned value of
NCALLS).
8 Further Comments
The time taken by D01FDF will be approximately proportional to the returned value of
NCALLS, which, except in the circumstances outlined in
(b) below, will be close to the given value of
LIMIT.
| (a) |
Choice of R0 and U
If the chosen combination of r0 and u is too large in relation to the machine accuracy it is possible that some of the points generated in the original region of integration may transform into points in the unit n-sphere which lie too close to the boundary surface to be distinguished from it to machine accuracy (despite the fact that r0<1). To be specific, the combination of r0 and u is too large if
or
where t is the number of bits in the mantissa of a double precision number. The contribution of such points to the integral is neglected. This may be justified by appeal to the fact that the Jacobian of the transformation rapidly approaches zero towards the surface. Neglect of these points avoids the occurrence of overflow with integrands which are infinite on the boundary. |
| (b) |
Values of LIMIT and NCALLS
LIMIT is an approximate upper limit to the number of integrand evaluations, and may not be chosen less than 100. There are two circumstances when the returned value of NCALLS (the actual number of evaluations used) may be significantly less than LIMIT.
Firstly, as explained in (a), an unsuitably large combination of R0 and U may result in some of the points being unusable. Such points are not included in the returned value of NCALLS. Secondly, no more than 400 layers will ever be used, no matter how high LIMIT is set. This places an effective upper limit on NCALLS as follows:
|
9 Example
This example calculates the integral
where
s is the
3-sphere of radius
σ,
r2=x12+x22+x32 and
σ=1.5. Both sphere-to-sphere and general product region transformations are used. For the former, we use
r0=0.9 and
u=1.5; for the latter,
r0=0.8 and
u=1.5.
9.1 Program Text
Program Text (d01fdfe.f)
9.2 Program Data
None.
9.3 Program Results
Program Results (d01fdfe.r)