naginterfaces.library.specfun.ellipint_​symm_​1

naginterfaces.library.specfun.ellipint_symm_1(x, y, z)

ellipint_symm_1 returns a value of the symmetrised elliptic integral of the first kind.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/s/s21bbf.html

Parameters

xfloat

The arguments $x$, $y$ and $z$ of the function.

yfloat

The arguments $x$, $y$ and $z$ of the function.

zfloat

The arguments $x$, $y$ and $z$ of the function.

Returns

rffloat

The value of the symmetrised elliptic integral of the first kind.

Raises

NagValueError

(errno $1$)

On entry, $x=⟨value⟩$, $y=⟨value⟩$ and $z=⟨value⟩$.

Constraint: $x\ge 0.0$ and $y\ge 0.0$ and $z\ge 0.0$.

The function is undefined.

(errno $2$)

On entry, $x=⟨value⟩$, $y=⟨value⟩$ and $z=⟨value⟩$.

Constraint: at most one of $x$, $y$ and $z$ is $0.0$.

The function is undefined and returns zero.

Notes

ellipint_symm_1 calculates an approximation to the integral

$$R_F(x,y,z)=\frac{1}{2}{\int }_0^{\infty }\frac{dt}{\sqrt{(t+x)(t+y)(t+z)}}$$

where $x$, $y$, $z\ge 0$ and at most one is zero.

The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:

$x_0=min(x,y,z)$, $z_0=max(x,y,z)$,

$y_0=$ remaining third intermediate value argument.

(This ordering, which is possible because of the symmetry of the function, is done for technical reasons related to the avoidance of overflow and underflow.)

$$\begin{array}{c}\begin{array}{ccc}{\mu }_n& =& (x_n+y_n+z_n)/3\\ X_n& =& (1-x_n)/{\mu }_n\\ Y_n& =& (1-y_n)/{\mu }_n\\ Z_n& =& (1-z_n)/{\mu }_n\\ {\lambda }_n& =& \sqrt{x_n{y}_n}+\sqrt{y_n{z}_n}+\sqrt{z_n{x}_n}\\ x_{n+1}& =& (x_n+{\lambda }_n)/4\\ y_{n+1}& =& (y_n+{\lambda }_n)/4\\ z_{n+1}& =& (z_n+{\lambda }_n)/4\end{array}\end{array}$$

${ϵ}_n=max(\left|X_n\right|,\left|Y_n\right|,\left|Z_n\right|)$ and the function may be approximated adequately by a fifth order power series:

$$R_F(x,y,z)=\frac{1}{\sqrt{{\mu }_n}}(1-\frac{E_2}{10}+\frac{E_2^2}{24}-\frac{3E_2{E}_3}{44}+\frac{E_3}{14})$$

where $E_2=X_n{Y}_n+Y_n{Z}_n+Z_n{X}_n$, $E_3=X_n{Y}_n{Z}_n$.

The truncation error involved in using this approximation is bounded by ${ϵ}_n^6/4(1-{ϵ}_n)$ and the recursive process is stopped when this truncation error is negligible compared with the machine precision.

Within the domain of definition, the function value is itself representable for all representable values of its arguments. However, for values of the arguments near the extremes the above algorithm must be modified so as to avoid causing underflows or overflows in intermediate steps. In extreme regions arguments are prescaled away from the extremes and compensating scaling of the result is done before returning to the calling program.

References

NIST Digital Library of Mathematical Functions

Carlson, B C, 1979, Computing elliptic integrals by duplication, Numerische Mathematik (33), 1–16

Carlson, B C, 1988, A table of elliptic integrals of the third kind, Math. Comput. (51), 267–280