naginterfaces.library.quad.md_​sphere_​bad

naginterfaces.library.quad.md_sphere_bad(f, ndim, radius, epsa, epsr, icoord, method=0, data=None)

md_sphere_bad 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 function can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.

For full information please refer to the NAG Library document for d01ja

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/d01/d01jaf.html

Parameters

fcallable retval = f(x, data=None)

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

Parameters

xfloat, ndarray, shape $\left(\text{ndim}\right)$

The coordinates of the point at which the integrand $f$ must be evaluated. These coordinates are given in Cartesian or spherical polar form according to the value of $icoord$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $f\left(x\right)$ evaluated at $x$.

ndimint

$n$, the dimension of the sphere.

radiusfloat

$\alpha$, the radius of the sphere.

epsafloat

The requested absolute tolerance. If $epsa<0.0$, its absolute value is used. See Accuracy.

epsrfloat

The requested relative tolerance.

$epsr<0.0$

Its absolute value is used.

$epsr<10\times \left(\text{machine precision}\right)$

The latter value is used as $epsr$ by the function. See Accuracy.

icoordint

Must specify which kind of coordinates are used in $f$.

$icoord=0$

Cartesian coordinates $x_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

$icoord=1$

Spherical coordinates (see Further Comments): $x\left[0\right]=\rho$; $x[\text{i}-1]={\theta }_{\text{i}-1}$, for $\text{i}=2,3,\dots ,n$.

$icoord=2$,

Special spherical polar coordinates (see Machine Dependencies), with the additional transformation $\rho =\alpha -\lambda$: $x\left[0\right]=\lambda =\alpha -\rho$; $x[\text{i}-1]={\theta }_{\text{i}-1}$, for $\text{i}=2,3,\dots ,n$.

methodint, optional

Must specify the transformation to be used by the function. 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 $icoord=2$, and the function defined in special spherical coordinates).

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

$method=2$ if $epsr\le {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.

dataarbitrary, optional

User-communication data for callback functions.

Returns

resultfloat

The approximation to the integral $I$.

esterrfloat

An estimate of the modulus of the absolute error.

nevalsint

The number of function evaluations used.

Raises

NagValueError

(errno $4$)

On entry, $radius=⟨value⟩$.

Constraint: $radius\ge 0.0$.

(errno $4$)

On entry, $method=4$ and $icoord=⟨value⟩$.

Constraint: when $method=4$, $icoord=2$.

(errno $4$)

On entry, $method=3$ and $icoord=⟨value⟩$.

Constraint: when $method=3$, $icoord=2$.

(errno $4$)

On entry, $icoord=2$ and $method=⟨value⟩$.

Constraint: when $icoord=2$, $method=3$ or $4$.

(errno $4$)

On entry, $ndim=⟨value⟩$.

Constraint: $ndim\ge 2$.

(errno $4$)

On entry, $ndim=⟨value⟩$.

Constraint: $ndim\le 4$.

Warns

NagAlgorithmicWarning

(errno $1$)

The required accuracy could not be achieved.

(errno $2$)

The required accuracy could not be achieved.

(errno $3$)

The required accuracy could not be achieved.

If $method=0$, $1$ or $2$, setting $method=3$ or $4$ may help.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

md_sphere_bad calculates an approximation to the $n$-dimensional integral

$$I=\int \cdots {\int }_{S}F(x_1,\dots ,x_n)d{x}_1\cdots d{x}_n\text{,}2\le n\le 4\text{,}$$

where $S$ is the hypersphere

$$\sqrt{(x_1^2+\cdots +x_n^2)}\le \alpha <\infty$$

(the integrand function may also be defined in spherical coordinates). 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 function 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 $\approx 2^n$). This introduces the restriction $n\le 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).

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