NAG Library Routine Document
D01JAF
1 Purpose
D01JAF attempts to evaluate an integral over an n-dimensional sphere (n=2, 3, or 4), to a user-specified absolute or relative accuracy, by means of a modified Sag–Szekeres method. The routine can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.
2 Specification
| SUBROUTINE D01JAF ( | F, NDIM, RADIUS, EPSA, EPSR, METHOD, ICOORD, RESULT, ESTERR, NEVALS, IFAIL) |
| INTEGER | NDIM, METHOD, ICOORD, NEVALS, IFAIL |
| double precision | F, RADIUS, EPSA, EPSR, RESULT, ESTERR |
| EXTERNAL | F |
3 Description
D01JAF calculates an approximation to the
n-dimensional integral
where
S is the hypersphere
(the integrand function may also be defined in spherical co-ordinates). The algorithm is based on the Sag–Szekeres method (see
Sag and Szekeres (1964)), applying the product trapezoidal formula after a suitable radial transformation. An improved transformation technique is developed: depending on the behaviour of the function and on the required accuracy, different transformations can be used, some of which are ‘double exponential’, as defined by
Takahasi and Mori (1974). The resulting technique allows the routine to deal with integrand singularities on the surface or at the centre of the sphere. When the estimated error of the approximation with mesh size
h is larger than the tolerated error, the trapezoidal formula with mesh size
h/2 is calculated. A drawback of this method is the exponential growth of the number of function evaluations in the successive approximations (this number grows with a factor
≈2n). This introduces the restriction
n≤4. Because the convergence rate of the successive approximations is normally better than linear, the error estimate is based on the linear extrapolation of the difference between the successive approximations (see
Robinson and de Doncker (1981) and
Roose and de Doncker (1981)). For further details of the algorithm, see
Roose and de Doncker (1981).
4 References
Robinson I and de Doncker E (1981) Automatic computation of improper integrals over a bounded or unbounded planar region
Computing 27 89–284
Roose D and de Doncker E (1981) Automatic integration over a sphere
J. Comput. Appl. Math. 7 203–224
Sag T W and Szekeres G (1964) Numerical evaluation of high-dimensional integrals
Math. Comput. 18 245–253
Takahasi H and Mori M (1974)
Double Exponential Formulas for Numerical Integration 9 Publ. RIMS, Kyoto University 721–741
5 Parameters
- 1: 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. These co-ordinates are given in Cartesian or spherical polar form according to the value of
ICOORD.
F must be declared as EXTERNAL in the (sub)program from which D01JAF is called. Parameters denoted as
Input must
not be changed by this procedure.
- 2: NDIM – INTEGERInput
On entry: n, the dimension of the sphere.
Constraint:
2≤NDIM≤4.
- 3: RADIUS – double precisionInput
On entry: α, the radius of the sphere.
Constraint:
RADIUS≥0.0.
- 4: EPSA – double precisionInput
On entry: the requested absolute tolerance. If
EPSA<0.0, its absolute value is used. See
Section 7.
- 5: EPSR – double precisionInput
On entry: the requested relative tolerance.
- EPSR<0.0
- Its absolute value is used.
- EPSR<10×machine precision
- The latter value is used as EPSR by the routine. See Section 7.
- 6: METHOD – INTEGERInput
On entry: must specify the transformation to be used by the routine. The choice depends on the behaviour of the integrand and on the required accuracy.
For well-behaved functions and functions with mild singularities on the surface of the sphere only:
- METHOD=1
- Low accuracy required.
- METHOD=2
- High accuracy required.
For functions with severe singularities on the surface of the sphere only:
- METHOD=3
- Low accuracy required.
- METHOD=4
- High accuracy required.
(in this case
ICOORD must be set to
2, and the function defined in special spherical co-ordinates).
For functions with a singularity at the centre of the sphere (and possibly with singularities on the surface as well):
- METHOD=5
- Low accuracy required.
- METHOD=6
- High accuracy required.
METHOD=0 can be used as a default value and is equivalent to
METHOD=1 if
EPSR>10-6, and to
METHOD=2 if
EPSR≤10-6.
The distinction between low and high required accuracies, as mentioned above, depends also on the behaviour of the function. Roughly one may assume the critical value of
EPSA and
EPSR to be
10-6, but the critical value will be smaller for a well-behaved integrand and larger for an integrand with severe singularities.
Suggested value:
METHOD=0.
Constraint:
METHOD=0,
1,
2,
3,
4,
5 or
6.
If ICOORD=2, METHOD=3 or 4
- 7: ICOORD – INTEGERInput
On entry: must specify which kind of co-ordinates are used in
F.
- ICOORD=0
- Cartesian co-ordinates xi, for i=1,2,…,n.
- ICOORD=1
- Spherical co-ordinates (see Section 8.2): X1=ρ; Xi=θi-1, for i=2,3,…,n.
- ICOORD=2,
- Special spherical polar co-ordinates (see Section 8.3), with the additional transformation ρ=α-λ: X1=λ=α-ρ; Xi=θi-1, for i=2,3,…,n.
Constraint:
ICOORD=0,
1 or
2.
If METHOD=3 or 4, ICOORD=2
- 8: RESULT – double precisionOutput
On exit: the approximation to the integral I.
- 9: ESTERR – double precisionOutput
On exit: an estimate of the modulus of the absolute error.
- 10: NEVALS – INTEGEROutput
On exit: the number of function evaluations used.
- 11: 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: D01JAF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
- IFAIL=1
-
The required accuracy cannot be achieved within a limiting number of function evaluations (which is set by the routine).
- IFAIL=2
-
The required accuracy cannot be achieved because of round-off error.
- IFAIL=3
-
The required accuracy cannot be achieved because the maximum accuracy with respect to the machine constants
X02AJF and
X02AMF has been attained. If this maximum accuracy is rather low (compared with
X02AJF), the cause of the problem is a severe singularity on the boundary or at the centre of the sphere. If
METHOD=0,
1 or
2, then setting
METHOD=3 or
4 may help.
- IFAIL=4
-
| On entry, | NDIM<2 or NDIM>4, |
| or | RADIUS<0.0, |
| or | METHOD≠0, 1, 2, 3, 4, 5 or 6, |
| or | ICOORD≠0, 1 or 2, |
| or | ICOORD=2 and METHOD≠3 or 4, |
| or | METHOD=3 or 4 and ICOORD≠2. |
No calculations have been performed.
RESULT and
ESTERR are set to
0.0.
7 Accuracy
You can specify an absolute and/or a relative tolerance, setting
EPSA and
EPSR. The routine attempts to calculate an approximation
RESULT such that
If
0≤IFAIL≤3,
ESTERR returns an estimate of, but not necessarily a bound for,
I-RESULT.
8 Further Comments
8.1 Timing
Timing depends on the integrand and the accuracy required.
8.2 Spherical Polar Co-ordinates
Cartesian co-ordinates are related to the spherical polar co-ordinates by:
where
0<θi<π, for
i=1,2,…,n-2 and
0<θn-1<2π.
8.3 Machine Dependencies
As a consequence of the transformation technique, the severity of the singularities which can be handled by D01JAF depends on the precision and range of real numbers on the machine. METHOD=3 or 4 must be used when the singularity on the surface is ‘severe’ in view of the requested accuracy and machine precision. In practice one has to set METHOD=3 or 4 if D01JAF terminates with IFAIL=3 when called with METHOD=0, 1 or 2.
When integrating a function with a severe singular behaviour on the surface of the sphere, the additional transformation ρ=α-λ helps to avoid the loss of significant figures due to round-off error in the calculation of the integration nodes which are very close to the surface. For these points, the value of λ can be computed more accurately than the value of ρ. Naturally, care must be taken that the function subprogram does not contain expressions of the form α-λ, which could cause a large round-off error in the calculation of the integrand at the boundary of the sphere.
Care should be taken to avoid underflow and/or overflow problems in the function subprogram, because some of the integration nodes used by D01JAF may be very close to the surface or to the centre of the sphere.
Example:
Note that D01JAF ensures that λ=X1>X02AMF, but underflow could occur in the computation of λ2.
9 Example
This example evaluates the integrals
where
ρ=∑i=1nxi2, and
S is the unit sphere of dimension
n=2 or 4.
The exact values (to 12 decimal places) are 6.28318530718 and 13.1594725348.
9.1 Program Text
Program Text (d01jafe.f)
9.2 Program Data
None.
9.3 Program Results
Program Results (d01jafe.r)