NAG FL Interface
d01fdf (md_​sphere)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{ndim}$ – Integer Input

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

Constraint: $1\le \mathbf{ndim}\le 30$.

2: $\mathbf{f}$ – real (Kind=nag_wp) 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:

Fortran Interface copy

Function f ( ndim, x) Real (Kind=nag_wp) :: f Integer, Intent (In) :: ndim Real (Kind=nag_wp), Intent (In) :: x(ndim)

C Header Interface copy

double  f (const Integer *ndim, const double x[])

C++ Header Interface copy

#include <nag.h> extern "C" { double  f (const Integer &ndim, const double x[]) }

1: $\mathbf{ndim}$ – Integer Input

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

2: $\mathbf{x}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) array Input

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

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

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

3: $\mathbf{sigma}$ – Real (Kind=nag_wp) Input

On entry: indicates the region of integration.

$\mathbf{sigma}\ge 0.0$

The integration is carried out over the $n$-sphere of radius sigma, centred at the origin.

$\mathbf{sigma}<0.0$

The integration is carried out over the product region described by region.

4: $\mathbf{region}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

If $\mathbf{sigma}<0.0$, region must evaluate the limits of integration in any dimension.

The specification of region is:

Fortran Interface copy

Subroutine region ( ndim, x, j, c, d) Integer, Intent (In) :: ndim, j Real (Kind=nag_wp), Intent (In) :: x(ndim) Real (Kind=nag_wp), Intent (Out) :: c, d

C Header Interface copy

void  region (const Integer *ndim, const double x[], const Integer *j, double *c, double *d)

C++ Header Interface copy

#include <nag.h> extern "C" { void  region (const Integer &ndim, const double x[], const Integer &j, double &c, double &d) }

1: $\mathbf{ndim}$ – Integer Input

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

2: $\mathbf{x}\left(\mathbf{ndim}\right)$ – Real (Kind=nag_wp) array Input

On entry: $\mathbf{x}\left(1\right),\dots ,\mathbf{x}\left(j-1\right)$ contain the current values of the first $(j-1)$ variables, which may be used if necessary in calculating $c_j$ and $d_j$.

3: $\mathbf{j}$ – Integer Input

On entry: the index $j$ for which the limits of the range of integration are required.

4: $\mathbf{c}$ – Real (Kind=nag_wp) Output

On exit: the lower limit $c_j$ of the range of $x_j$.

5: $\mathbf{d}$ – Real (Kind=nag_wp) Output

On exit: the upper limit $d_j$ of the range of $x_j$.

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

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

If $\mathbf{sigma}\ge 0.0$, region is not called by d01fdf, but a dummy routine must be supplied (d01fdv may be used).

5: $\mathbf{limit}$ – Integer Input

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

Constraint: $\mathbf{limit}\ge 100$.

6: $\mathbf{r0}$ – Real (Kind=nag_wp) Input

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 $\mathbf{r0}=0.8$. (See also Section 9.)

Constraint: $0.0<\mathbf{r0}<1.0$.

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

On entry: must specify an adjustable parameter of the transformation to the unit $n$-sphere.

Suggested value: a typical value is $\mathbf{u}=1.5$. (See also Section 9.)

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

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

On exit: the approximation to the integral $I$.

9: $\mathbf{ncalls}$ – Integer Output

On exit: the actual number of integrand evaluations used. (See also Section 9.)

10: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{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}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ndim}\le 30$.

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

$\mathbf{ifail}=2$

On entry, $\mathbf{limit}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{limit}\ge 100$.

$\mathbf{ifail}=3$

On entry, $\mathbf{r0}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{r0}<1.0$.

On entry, $\mathbf{r0}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{r0}>0.0$.

$\mathbf{ifail}=4$

On entry, $\mathbf{u}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{u}>0.0$.

$\mathbf{ifail}=-99$

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

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

1. (a)Choice of $r_0$ and $u$
   If the chosen combination of $r_0$ 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 $r_0<1$). To be specific, the combination of $r_0$ and $u$ is too large if

   $$\frac{u{r}_0}{1-r_0^2}>0.3465(t-1)\text{, \hspace{1em} if }\mathbf{sigma}\ge 0.0\text{,}$$

   or

   $$\frac{u{r}_0}{1-r_0}>0.3465(t-1)\text{, \hspace{1em} if }\mathbf{sigma}<0.0\text{,}$$

   where $t$ is the number of bits in the mantissa of a real 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.
2. (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 $r_0$ 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:

   $$\begin{array}{lr}n=1:& 56\\ n=2:& 1252\\ n=3:& 23690\\ n=4:& 394528\\ n=5:& 5956906\end{array}$$

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results