s Chapter Contents
s Chapter Introduction
NAG 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-k2sin2⁡ϕ,$
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-k2sin2⁡θ .$
The above definitions can be extended for values of ${k}^{2}>1$ (see Salzer (1962)) by means of the formulae
 $snz∣k = k1snkz∣k1 cnz∣k = dnkz∣k1 dnz∣k = cnkz∣k1,$
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)).
The values of $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$ are obtained by calls to nag_real_jacobian_elliptic (s21cac). Further details can be found in Section 9.

## 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:    $\mathbf{z}$ComplexInput
On entry: the argument $z$ of the functions.
Constraints:
• $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{re}\right)\le =\sqrt{\lambda }$;
• $\mathrm{abs}\left({\mathbf{z}}\mathbf{.}\mathbf{im}\right)\le \sqrt{\lambda }$, where $\lambda =1/{\mathbf{nag_real_safe_small_number}}$.
2:    $\mathbf{ak2}$doubleInput
On entry: the value of ${k}^{2}$.
Constraint: $0.0\le {\mathbf{ak2}}\le 1.0$.
3:    $\mathbf{sn}$Complex *Output
4:    $\mathbf{cn}$Complex *Output
5:    $\mathbf{dn}$Complex *Output
On exit: the values of the functions $\mathrm{sn}z$, $\mathrm{cn}z$ and $\mathrm{dn}z$, respectively.
6:    $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_COMPLEX
On entry, $\left|{\mathbf{z}}\mathbf{.}\mathbf{im}\right|$ is too large: $\left|{\mathbf{z}}\mathbf{.}\mathbf{im}\right|=〈\mathit{\text{value}}〉$. It must be less than $〈\mathit{\text{value}}〉$.
On entry, $\left|{\mathbf{z}}\mathbf{.}\mathbf{re}\right|$ is too large: $\left|{\mathbf{z}}\mathbf{.}\mathbf{re}\right|=〈\mathit{\text{value}}〉$. It must be less than $〈\mathit{\text{value}}〉$.
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.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
NE_REAL
On entry, ${\mathbf{ak2}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ak2}}\le 1.0$.
On entry, ${\mathbf{ak2}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ak2}}\ge 0.0$.

## 7  Accuracy

In principle the function is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as SIN and COS.

## 8  Parallelism and Performance

nag_jacobian_elliptic (s21cbc) is not threaded in any implementation.

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

## 10  Example

This example 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.

### 10.1  Program Text

Program Text (s21cbce.c)

### 10.2  Program Data

Program Data (s21cbce.d)

### 10.3  Program Results

Program Results (s21cbce.r)