ellipj

Jacobi elliptic functions

Syntax

Description

example

[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.

example

[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

expand all

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)
toc
tic
ellipj(0.253,0.937,eps*1000)
toc
ans =

    0.2479

Elapsed time is 0.032640 seconds.

ans =

    0.2479

Elapsed time is 0.009130 seconds.

ellipj runs significantly faster when tolerance is significantly increased.

Input Arguments

expand all

U — Floating-point inputnumber | vector | matrix | multidimensional array

Floating-point input, specified as a floating-point number, 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 — Floating-point inputnumber | vector | matrix | multidimensional array

Floating-point input, specified as a floating-point number, 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 resulteps (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 | function_handle

Output Arguments

expand all

SN — Jacobi elliptic function snfloating-point number | floating-point vector | floating-point matrix | floating-point multidimensional array

Jacobi elliptic function sn, returned as a floating-point number, vector, matrix, or multidimensional array.

CN — Jacobi elliptic function cnfloating-point number | floating-point vector | floating-point matrix | floating-point multidimensional array

Jacobi elliptic function cn, returned as a floating-point number, vector, matrix, or multidimensional array.

DN — Jacobi elliptic function dnfloating-point number | floating-point vector | floating-point matrix | floating-point multidimensional array

Jacobi elliptic function dn, returned as a floating-point number, vector, matrix, or multidimensional array.

More About

expand all

Jacobi Elliptic Functions

The Jacobi elliptic functions are defined in terms of the integral

u=0ϕdθ1msin2θ.

Then

sn(u)=sinϕ, cn(u)=cosϕ, dn(u)=1msin2ϕ.

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

k2=m=sin2a.

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

a0=1, b0=1m, c0=m.

ellipj computes successive iterations using

ai=12(ai1+bi1)bi=(ai1bi1)12ci=12(ai1bi1).

Next, it calculates the amplitudes in radians using

sin(2ϕn1ϕn)=cnansin(ϕn),

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

sn(u)=sinϕ0cn(u)=cosϕ0dn(u)=1msn(u)2.

References

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

See Also

Was this topic helpful?