s Chapter Contents
s Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_jacobian_elliptic (s21cbc)

## 1  Purpose

nag_jacobian_elliptic (s21cbc) evaluates the Jacobian elliptic functions $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$ for a complex argument $z$.

## 2  Specification

 #include #include
 void nag_jacobian_elliptic (Complex z, double ak2, Complex *sn, Complex *cn, Complex *dn, NagError *fail)

## 3  Description

nag_jacobian_elliptic (s21cbc) evaluates the Jacobian elliptic functions $\mathrm{sn}\left(z\mid k\right)$, $\mathrm{cn}\left(z\mid k\right)$ and $\mathrm{dn}\left(z\mid k\right)$ given by
 $snz∣k = sin⁡ϕ cnz∣k = cos⁡ϕ dnz∣k = 1 - k 2 sin 2 ⁡ϕ ,$
where $z$ is a complex argument, $k$ is a real argument (the modulus) with ${k}^{2}\le 1$ and $\varphi$ (the amplitude of $z$) is defined by the integral
 $z = ∫ 0 ϕ dθ 1 - k 2 sin 2 ⁡θ .$
The above definitions can be extended for values of ${k}^{2}>1$ (see Salzer (1962)) by means of the formulae
 $snz∣k = k 1 sn kz ∣ k 1 cnz∣k = dn kz ∣ k 1 dnz∣k = cn kz ∣ k 1$
where ${k}_{1}=1/k$.
Special values include
 $snz∣0 = sin⁡z cnz∣0 = cos⁡z dnz∣0 = 1 snz∣1 = tanh⁡z cnz∣1 = sech⁡z dnz∣1 = sech⁡z .$
These functions are often simply written as $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$, thereby avoiding explicit reference to the argument $k$. They can also be expressed in terms of Jacobian theta functions (see nag_jacobian_theta (s21ccc)).
Another nine elliptic functions may be computed via the formulae
 $cd⁡z = cn⁡z / dn⁡z sd⁡z = sn⁡z / dn⁡z nd⁡z = 1 / dn⁡z$
 $dc⁡z = dn⁡z / cn⁡z nc⁡z = 1 / cn⁡z sc⁡z = sn⁡z / cn⁡z ns⁡z = 1 / sn⁡z ds⁡z = dn⁡z / sn⁡z cs⁡z = cn⁡z / sn⁡z$
(see Abramowitz and Stegun (1972)).

## 4  References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Salzer H E (1962) Quick calculation of Jacobian elliptic functions Comm. ACM 5 399

## 5  Arguments

1:     zComplexInput
On entry: the argument $z$ of the functions.
Constraints:
• $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{re}\right)\le \sqrt{\lambda }$;
• if $\lambda =1/{\mathbf{nag_real_safe_small_number}}$, $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{im}\right)\le \sqrt{\lambda }$.
2:     ak2doubleInput
On entry: the value of ${k}^{2}$.
Constraint: $0.0\le {\mathbf{ak2}}\le 1.0$.
3:     snComplex *Output
4:     cnComplex *Output
5:     dnComplex *Output
On exit: the values of the functions $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$, respectively.
6:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_COMPLEX
On entry, ${\mathbf{z}}=\left(〈\mathit{\text{value}}〉,〈\mathit{\text{value}}〉\right)$.
Constraint: $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{re}\right)\le \lambda$ and $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{im}\right)\le \lambda$, where $\lambda =\frac{1}{\sqrt{{\mathbf{nag_real_safe_small_number}}}}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_REAL
On entry, ${\mathbf{ak2}}=〈\mathit{\text{value}}〉$.
Constraint: $0.0\le {\mathbf{ak2}}\le 1.0$.

## 7  Accuracy

In principle nag_jacobian_elliptic (s21cbc) is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the C standard library elementary functions such as sin and cos.

The values of $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$ are computed via the formulae
 $sn⁡z = snu,k dnv, k ′ 1 - dn 2 u,k sn 2 v, k ′ + i cnu,k dnu,k snv, k ′ cnv, k ′ 1 - dn 2 u,k sn 2 v, k ′ cn⁡z = cnu,k cnv, k ′ 1 - dn 2 u,k sn 2 v, k ′ - i snu,k dnu,k snv, k ′ dnv, k ′ 1 - dn 2 u,k sn 2 v, k ′ dn⁡z = dnu,k cnv, k ′ dnv, k ′ 1 - dn 2 u,k sn 2 v, k ′ - i k 2 snu,k cnu,k snv, k ′ 1 - dn 2 u,k sn 2 v, k ′ ,$
where $z=u+iv$ and ${k}^{\prime }=\sqrt{1-{k}^{2}}$ (the complementary modulus).

## 9  Example

The example program evaluates $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$ at $z=-2.0+3.0i$ when $k=0.5$, and prints the results.

### 9.1  Program Text

Program Text (s21cbce.c)

### 9.2  Program Data

Program Data (s21cbce.d)

### 9.3  Program Results

Program Results (s21cbce.r)