ellipj

Jacobi elliptic functions

Syntax

[SN,CN,DN] = ellipj(U,M)

[SN,CN,DN] = ellipj(U,M,tol)

Description

[SN,CN,DN] = ellipj(U,M) returns the Jacobi elliptic functions SN, CN, and DN evaluated for corresponding elements of argument U and parameter M. Inputs U and M must be the same size, or either U or M must be scalar.

[SN,CN,DN] = ellipj(U,M,tol) computes the Jacobi elliptic functions to accuracy tol. The default value of tol is eps. Increase tol for a less accurate but more quickly computed answer.

Examples

Find the Jacobi Elliptic Functions

Find the Jacobi elliptic functions for U = 0.5 and M = 0.25.

[s,c,d] = ellipj(0.5,0.25)

s = 
0.4751

c = 
0.8799

d = 
0.9714

Plot the Jacobi Elliptic Functions

Plot the Jacobi elliptic functions for -5≤U≤5 and M = 0.7.

M = 0.7;
U = -5:0.01:5;
[S,C,D] = ellipj(U,M);
plot(U,S,U,C,U,D);
legend('SN','CN','DN','Location','best')
grid on
title('Jacobi Elliptic Functions sn,cn,dn')

Generate a Surface Plot of the Jacobi Elliptic sn Function

Generate a surface plot of the Jacobi elliptic sn function for the allowed range of M and -5≤U≤5.

[M,U] = meshgrid(0:0.1:1,-5:0.1:5);
S = ellipj(U,M);
surf(U,M,S)
xlabel('U')
ylabel('M')
zlabel('sn')
title('Surface Plot of Jacobi Elliptic Function sn')

Faster Calculations of Jacobi Elliptic Integrals by Changing Tolerance

The default value of tol is eps. Find the run time with the default value for arbitrary M using tic and toc. Increase tol by a factor of 1000 and find the run time. Compare the run times.

tic
ellipj(0.253,0.937)

ans = 
0.2479

toc

Elapsed time is 0.118504 seconds.

tic
ellipj(0.253,0.937,eps*1000)

ans = 
0.2479

toc

Elapsed time is 0.012601 seconds.

ellipj runs significantly faster when tolerance is significantly increased.

Input Arguments

U — Input array

scalar | vector | matrix | multidimensional array

Input array, specified as a scalar, vector, matrix, or multidimensional array. U is limited to real values. If U is nonscalar, M must be a scalar or a nonscalar of the same size as U.

Data Types: single | double

M — Input array

scalar | vector | matrix | multidimensional array

Input array, specified as a scalar, vector, matrix, or multidimensional array. M can take values 0≤ m ≤1. If M is a nonscalar, U must be a scalar or a nonscalar of the same size as M. Map other values of M into this range using the transformations described in [1], equations 16.10 and 16.11.

Data Types: single | double

tol — Accuracy of result

eps (default) | nonnegative real number

Accuracy of result, specified as a nonnegative real number. The default value is eps.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

SN — Jacobi elliptic function sn

scalar | vector | matrix | multidimensional array

Jacobi elliptic function sn, returned as a scalar, vector, matrix, or multidimensional array.

CN — Jacobi elliptic function cn

scalar | vector | matrix | multidimensional array

Jacobi elliptic function cn, returned as a scalar, vector, matrix, or multidimensional array.

DN — Jacobi elliptic function dn

scalar | vector | matrix | multidimensional array

Jacobi elliptic function dn, returned as a scalar, vector, matrix, or multidimensional array.

More About

Jacobi Elliptic Functions

The Jacobi elliptic functions are defined in terms of the integral

$$u={\displaystyle {\int }_0^{\varphi }\frac{d\theta }{\sqrt{1-m{\sin }^2\theta }}}.$$

Then

$$sn(u)=\sin \varphi ,cn(u)=\cos \varphi ,dn(u)=\sqrt{1-m{\sin }^2\varphi }.$$

Some definitions of the elliptic functions use the elliptical modulus k or modular angle α instead of the parameter m. They are related by

$$k^2=m={\sin }^{2}a.$$

The Jacobi elliptic functions obey many mathematical identities. For a good sample, see [1].

Algorithms

ellipj computes the Jacobi elliptic functions using the method of the arithmetic-geometric mean of [1]. It starts with the triplet of numbers

$$a_0=1,b_0=\sqrt{1-m},c_0=\sqrt{m}.$$

ellipj computes successive iterations using

$$\begin{array}{l}{a}_i=\frac{1}{2}(a_{i-1}+b_{i-1})\\ b_i={(}^{a_{i-1}}\\ c_i=\frac{1}{2}(a_{i-1}-b_{i-1}).\end{array}$$

Next, it calculates the amplitudes in radians using

$$\sin (2{\varphi }_{n-1}-{\varphi }_n)=\frac{c_n}{a_n}\sin ({\varphi }_n),$$

being careful to unwrap the phases correctly. The Jacobian elliptic functions are then simply

$$\begin{array}{l}sn(u)=\sin {\varphi }_0\\ cn(u)=\cos {\varphi }_0\\ dn(u)=\sqrt{1-m\cdot sn{(u)}^2}.\end{array}$$

References

[1] Abramowitz, M. and I. A. Stegun, Handbook of Mathematical Functions, Dover Publications, 1965, 17.6.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a