scipy.special.ellipj#

scipy.special.ellipj(u, m, out=None) = <wrapped_ufunc 'ellipj'>#

Jacobi elliptic functions.

Calculates the Jacobi elliptic functions of parameter m less than or equal to 1, and real argument u.

Parameters:

uarray_like: Argument.
marray_like: Parameter.
outtuple of ndarray, optional: Optional output arrays for the function values

Returns:

sn, cn, dn, ph4-tuple of scalar or ndarray

The returned functions:

sn(u|m), cn(u|m), dn(u|m)

The value ph is such that if u = ellipkinc(ph, m), then sn(u|m) = sin(ph) and cn(u|m) = cos(ph).

See also

ellipk: Complete elliptic integral of the first kind
ellipkinc: Incomplete elliptic integral of the first kind

Notes

Wrapper for the Cephes [1] routine ellpj.

These functions are periodic, with quarter-period on the real axis equal to the complete elliptic integral ellipk(m).

Relation to incomplete elliptic integral: If u = ellipkinc(phi,m), then sn(u|m) = sin(phi), and cn(u|m) = cos(phi). The phi is called the amplitude of u.

Computation is by means of the arithmetic-geometric mean algorithm, except when m is within 1e-9 of 0 or 1. In the latter case with m close to 1, the approximation applies only for phi < pi/2.

Array API Standard Support

ellipj 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 typically 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. ellipj 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/

Examples

The elliptic sine sn(u|m) interpolates between the sine function and the hyperbolic tangent when m changes from 0 to 1.

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> from scipy.special import ellipj
>>> u = np.linspace(0, 2*np.pi, 100)
>>> fig, ax = plt.subplots()
>>> ax.plot(u, np.sin(u), '--', label='sin(u)')
>>> for m in (0.2, 0.8, 0.99):
...     ax.plot(u, ellipj(u, m)[0], label=f'sn(u|{m})')
>>> ax.plot(u, np.tanh(u), '--', label='tanh(u)')
>>> ax.set_xlabel('u')
>>> ax.legend(loc='lower left')
>>> plt.show()

../../_images/scipy-special-ellipj-1_00_00.png

Like for sine and cosine, the squares of elliptic sine and elliptic cosine add up to one.

>>> u = np.linspace(0, 5, 11)
>>> sn, cn, _, _ = ellipj(u, 0.7)
>>> sn**2 + cn**2
array([1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.])