NAG Library Function Document

nag_jacobian_elliptic (s21cbc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

nag_jacobian_elliptic (s21cbc) evaluates the Jacobian elliptic functions

sn z

cn z

and

dn z

for a complex argument

z

2 Specification

#include <nag.h>

#include <nags.h>

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

sn (z ∣ k)

cn (z ∣ k)

and

dn (z ∣ k)

given by

\begin{aligned} sn (z ∣ k) & = \sin ϕ \\ cn (z ∣ k) & = \cos ϕ \\ dn (z ∣ k) & = \sqrt{1 - k^{2} \sin^{2} ϕ}, \end{aligned}

where

z

is a complex argument,

k

is a real argument (the modulus) with

k^{2} \leq 1

and

ϕ

(the amplitude of

z

) is defined by the integral

z = \int_{0}^{ϕ} \frac{d θ}{\sqrt{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

\begin{aligned} sn (z ∣ k) & = k_{1} sn (k z ∣ k_{1}) \\ cn (z ∣ k) & = dn (k z ∣ k_{1}) \\ dn (z ∣ k) & = cn (k z ∣ k_{1}) \end{aligned}

where

k_{1} = 1 / k

Special values include

\begin{aligned} sn (z ∣ 0) & = \sin z \\ cn (z ∣ 0) & = \cos z \\ dn (z ∣ 0) & = 1 \\ sn (z ∣ 1) & = \tanh z \\ cn (z ∣ 1) & = sech z \\ dn (z ∣ 1) & = sech z . \end{aligned}

These functions are often simply written as

sn z

cn z

and

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

\begin{aligned} cd z & = cn z / dn z \\ sd z & = sn z / dn z \\ nd z & = 1 / dn z \end{aligned}

\begin{aligned} 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 \end{aligned}

(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: z – ComplexInput

On entry: the argument

z

of the functions.

Constraints:

$abs (z . re) \leq \sqrt{λ}$ ;
if $λ = 1 / nag_real_safe_small_number$ , $abs (z . im) \leq \sqrt{λ}$ .

2: ak2 – doubleInput

On entry: the value of

k^{2}

Constraint:

0.0 \leq ak2 \leq 1.0

3: sn – Complex *Output

4: cn – Complex *Output

5: dn – Complex *Output

On exit: the values of the functions

sn z

cn z

and

dn z

, respectively.

6: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_COMPLEX: On entry, $z = (〈value〉, 〈value〉)$ .
Constraint: $abs (z . re) \leq λ$ and $abs (z . im) \leq λ$ , where $λ = \frac{1}{\sqrt{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, $ak2 = 〈value〉$ .
Constraint: $0.0 \leq ak2 \leq 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.

8 Further Comments

The values of

sn z

cn z

and

dn z

are computed via the formulae

\begin{aligned} sn z & = \frac{sn (u, k) dn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})} + i \frac{cn (u, k) dn (u, k) sn (v, k^{'}) cn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})} \\ cn z & = \frac{cn (u, k) cn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})} - i \frac{sn (u, k) dn (u, k) sn (v, k^{'}) dn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})} \\ dn z & = \frac{dn (u, k) cn (v, k^{'}) dn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})} - i \frac{k^{2} sn (u, k) cn (u, k) sn (v, k^{'})}{1 - {dn}^{2} (u, k) {sn}^{2} (v, k^{'})}, \end{aligned}

where

z = u + i v

and

k^{'} = \sqrt{1 - k^{2}}

(the complementary modulus).

9 Example

The example program evaluates

sn z

cn z

and

dn z

z = - 2.0 + 3.0 i

when

k = 0.5

, and prints the results.

NAG Library Function Documentnag_jacobian_elliptic (s21cbc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_jacobian_elliptic (s21cbc)