naginterfaces.library.quad.md_sphere¶

naginterfaces.library.quad.md_sphere(ndim, f, sigma, limit, region=None, r0=0.8, u=1.5, data=None)[source]¶

md_sphere 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.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d01/d01fdf.html

Parameters

ndimint

$n$ , the number of dimensions of the integral.

fcallable retval = f(x, data=None)

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

Parameters

xfloat, ndarray, shape $(ndim)$: The coordinates of the point at which the integrand $f$ must be evaluated.
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

retvalfloat: The value of $f (x)$ evaluated at $x$ .

sigmafloat

Indicates the region of integration.

$s i g m a \geq 0.0$

The integration is carried out over the $n$ -sphere of radius $s i g m a$ , centred at the origin.

$s i g m a < 0.0$

The integration is carried out over the product region described by $r e g i o n$ .

limitint

The approximate maximum number of integrand evaluations to be used.

regionNone or callable (c, d) = region(x, j, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

If $s i g m a < 0.0$ , $r e g i o n$ must evaluate the limits of integration in any dimension.

Parameters

xfloat, ndarray, shape $(ndim)$: $x [0], \dots, x [j - 2]$ contain the current values of the first $(j - 1)$ variables, which may be used if necessary in calculating $c_{j}$ and $d_{j}$ .
jint: The index $j$ for which the limits of the range of integration are required.
dataarbitrary, optional, modifiable in place: User-communication data for callback functions.

Returns

cfloat: The lower limit $c_{j}$ of the range of $x_{j}$ .
dfloat: The upper limit $d_{j}$ of the range of $x_{j}$ .

r0float, optional

The cut-off radius on the unit $n$ -sphere, which may be regarded as an adjustable parameter of the method.

ufloat, optional

Must specify an adjustable parameter of the transformation to the unit $n$ -sphere.

dataarbitrary, optional

User-communication data for callback functions.

Returns

resultfloat: The approximation to the integral $I$ .
ncallsint: The actual number of integrand evaluations used. (See also Further Comments.)

Raises

NagValueError

(errno $1$ )

On entry, $n d i m = ⟨ v a l u e ⟩$ .

Constraint: $n d i m \leq 30$ .

(errno $1$ )

On entry, $n d i m = ⟨ v a l u e ⟩$ .

Constraint: $n d i m \geq 1$ .

(errno $2$ )

On entry, $l i m i t = ⟨ v a l u e ⟩$ .

Constraint: $l i m i t \geq 100$ .

(errno $3$ )

On entry, $r 0 = ⟨ v a l u e ⟩$ .

Constraint: $r 0 < 1.0$ .

(errno $3$ )

On entry, $r 0 = ⟨ v a l u e ⟩$ .

Constraint: $r 0 > 0.0$ .

(errno $4$ )

On entry, $u = ⟨ v a l u e ⟩$ .

Constraint: $u > 0.0$ .

Notes

md_sphere calculates an approximation to

\int_{n -sphere of radius σ} f (x_{1}, x_{2}, \dots, x_{n}) d x_{1} d x_{2} \dots d x_{n}

or, more generally,

\int_{c_{1}}^{d_{1}} d x_{1} \dots \int_{c_{n}}^{d_{n}} d x_{n} f (x_{1}, \dots, x_{n})

where each $c_{i}$ and $d_{i}$ may be functions of $x_{j}$ $(j < i)$ .

The function 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 parameterised 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:

x_{i} = y_{i} \frac{σ}{r} tanh (\frac{u r}{1 - r^{2}})

where $r^{2} = \sum_{i = 1}^{n} y_{i}^{2}$ and $u$ is an adjustable parameter.

Integrals of the form (2) are first of all transformed to the $n$ -cube ${[- 1, 1]}^{n}$ by a linear change of variables

x_{i} = ((d_{i} + c_{i}) + (d_{i} - c_{i}) y_{i}) / 2

and then to the unit sphere by a further change of variables

y_{i} = tanh (\frac{u z_{i}}{1 - r})

where $r^{2} = \sum_{i = 1}^{n} z_{i}^{2}$ 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

r_{i} = \frac{h}{4} \sqrt{n + 8 (i - 1)}, i = 1, 2, 3, \dots .

The function 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 $r_{0} < 1$ . The grid-spacing $h$ is determined by $r_{0}$ and the number of layers to be used. A typical value of $r_{0}$ is $0.8$ .

Some experimentation may be required with the choice of $r_{0}$ (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 Further Comments.

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

NAG and Python

Return to Front

naginterfaces.library.quad.md_sphere¶

naginterfaces.library.quad.md_​sphere¶

naginterfaces.library.quad.md_sphere¶