scipy.special.ellipkm1#

scipy.special.ellipkm1(p, out=None) = <ufunc 'ellipkm1'>#

Complete elliptic integral of the first kind around m = 1.

This function is defined as

\[K(p) = \int_0^{\pi/2} [1 - m \sin(t)^2]^{-1/2} dt\]

where m = 1 - p.

Parameters:

parray_like: Defines the parameter of the elliptic integral as m = 1 - p.
outndarray, optional: Optional output array for the function values

Returns:

Kscalar or ndarray: Value of the elliptic integral.

See also

ellipk: Complete elliptic integral of the first kind
ellipkinc: Incomplete elliptic integral of the first kind
ellipe: Complete elliptic integral of the second kind
ellipeinc: Incomplete elliptic integral of the second kind
elliprf: Completely-symmetric elliptic integral of the first kind.

Notes

Wrapper for the Cephes [1] routine ellpk.

For p <= 1, computation uses the approximation,

\[K(p) \approx P(p) - \log(p) Q(p)\]

where \(P\) and \(Q\) are tenth-order polynomials. The argument p is used internally rather than m so that the logarithmic singularity at m = 1 will be shifted to the origin; this preserves maximum accuracy. For p > 1, the identity

\[K(p) = K(1/p)/\sqrt{p}\]

is used.

Array API Standard Support

ellipkm1 has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable SCIPY_ARRAY_API=1 and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported.

Library	CPU	GPU
NumPy	✅	n/a
CuPy	n/a	✅
PyTorch	✅	⛔
JAX	✅	⛔
Dask	✅	n/a

See Support for the array API standard for more information.

References

[1]

Cephes Mathematical Functions Library, http://www.netlib.org/cephes/

[2]

NIST Digital Library of Mathematical Functions, Eq. 19.12.1. https://dlmf.nist.gov/19.12.E1

Examples

>>> from scipy.special import ellipk, ellipkm1
>>> p = 1e-10
>>> m = 1-p
>>> ellipk(m), ellipkm1(p)
(np.float64(12.899219785017415), np.float64(12.8992198263876))

In order to decide which one of the two results is closer to the correct one, one can use the asymptotic expansion including the next-to-leading order [2].

>>> from math import log, sqrt
>>> log(4/sqrt(p)) + 0.25*p*(log(4/sqrt(p))-1)
12.8992198263876

We can conclude that for such small values of \(p\), ellipkm1 yields the better result. For even smaller values of \(p\), the difference becomes more apparent.

>>> p = 1e-15
>>> m = 1-p
>>> ellipk(m), ellipkm1(p)
(np.float64(18.656082357290334), np.float64(18.655682558575236))
>>> log(4/sqrt(p)) + 0.25*p*(log(4/sqrt(p))-1)
18.655682558575236

For even smaller values of \(p\), the finite spacing between float numbers becomes relevant. Then ellipkm1 needs to be used in any case.