# ellipj

Jacobi elliptic functions

## Syntax

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

## 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

collapse 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.027141 seconds. ans = 0.2479 Elapsed time is 0.014472 seconds. ```

`ellipj` runs significantly faster when tolerance is significantly increased.

## Input Arguments

collapse 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

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

collapse all

### Jacobi Elliptic Functions

The Jacobi elliptic functions are defined in terms of the integral

$u={\int }_{0}^{\varphi }\frac{d\theta }{\sqrt{1-m{\mathrm{sin}}^{2}\theta }}.$

Then

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={\mathrm{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

`ellipj` computes successive iterations using

$\begin{array}{l}{a}_{i}=\frac{1}{2}\left({a}_{i-1}+{b}_{i-1}\right)\\ {b}_{i}={\left(}^{{a}_{i-1}}\\ {c}_{i}=\frac{1}{2}\left({a}_{i-1}-{b}_{i-1}\right).\end{array}$

Next, it calculates the amplitudes in radians using

$\mathrm{sin}\left(2{\varphi }_{n-1}-{\varphi }_{n}\right)=\frac{{c}_{n}}{{a}_{n}}\mathrm{sin}\left({\varphi }_{n}\right),$

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

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

## References

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