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 support for Python Array API Standard compatible backends in addition to NumPy. 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

For the NumPy backend, this function supports all NumPy ufunc keyword arguments. Other backends may support out, but none of the other ufunc kwargs. out is typically supported for CuPy and PyTorch, but not currently in cases where SciPy relies on a generic Array API implementation or, for PyTorch on CPU, falls back to the NumPy backend. out is never supported for JAX because JAX arrays are immutable. ellipkm1 does not currently support out for the PyTorch backend.

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.