s21cb evaluates the Jacobian elliptic functions

sn z

cn z

and

dn z

for a complex argument

z

Syntax

C#
public static void s21cb( Complex z, double ak2, out Complex sn, out Complex cn, out Complex dn, out int ifail )

Visual Basic
Public Shared Sub s21cb ( _ z As Complex, _ ak2 As Double, _ <OutAttribute> ByRef sn As Complex, _ <OutAttribute> ByRef cn As Complex, _ <OutAttribute> ByRef dn As Complex, _ <OutAttribute> ByRef ifail As Integer _ )

Visual Basic

Public Shared Sub s21cb ( _
	z As Complex, _
	ak2 As Double, _
	<OutAttribute> ByRef sn As Complex, _
	<OutAttribute> ByRef cn As Complex, _
	<OutAttribute> ByRef dn As Complex, _
	<OutAttribute> ByRef ifail As Integer _
)

Visual C++
public: static void s21cb( Complex z, double ak2, [OutAttribute] Complex% sn, [OutAttribute] Complex% cn, [OutAttribute] Complex% dn, [OutAttribute] int% ifail )

F#
static member s21cb : z : Complex * ak2 : float * sn : Complex byref * cn : Complex byref * dn : Complex byref * ifail : int byref -> unit

Parameters

z

Type: NagLibrary..::..Complex

On entry: the argument

z

of the functions.

Constraints:

$abs (Re (z)) \leq = \sqrt{λ}$ ;
$abs (Im (z)) \leq \sqrt{λ}$ , where $λ = 1 / x02am$ .

ak2: Type: System..::..Double
On entry: the value of $k^{2}$ .

Constraint: $0.0 \leq ak2 \leq 1.0$ .

sn: Type: NagLibrary..::..Complex%
On exit: the values of the functions $sn z$ , $cn z$ and $dn z$ , respectively.

cn: Type: NagLibrary..::..Complex%
On exit: the values of the functions $sn z$ , $cn z$ and $dn z$ , respectively.

dn: Type: NagLibrary..::..Complex%
On exit: the values of the functions $sn z$ , $cn z$ and $dn z$ , respectively.

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s21cb evaluates the Jacobian elliptic functions

sn (z ∣ k)

cn (z ∣ k)

and

dn (z ∣ k)

given by

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

where

z

is a complex argument,

k

is a real parameter (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{array}{lcl} 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{array}

where

k_{1} = 1 / k

Special values include

\begin{array}{lcl} 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{array}

These functions are often simply written as

sn z

cn z

and

dn z

, thereby avoiding explicit reference to the parameter

k

. They can also be expressed in terms of Jacobian theta functions (see s21cc).

Another nine elliptic functions may be computed via the formulae

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

(see Abramowitz and Stegun (1972)).

The values of

sn z

cn z

and

dn z

are obtained by calls to s21ca. Further details can be found in [Further Comments].

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

Error Indicators and Warnings

Errors or warnings detected by the method:

$ifail = 1$

On entry,	$ak2 < 0.0$ ,
or	$ak2 > 1.0$ ,
or	$abs (Re (z)) > \sqrt{λ}$ ,
or	$abs (Im (z)) > \sqrt{λ}$ , where $λ = 1 / x02am$ .

$ifail = -9000$: An error occured, see message report.

Accuracy

In principle the method 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.

Parallelism and Performance

None.

Further Comments

The values of

sn z

cn z

and

dn z

are computed via the formulae

\begin{array}{lcccl} 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{array}

where

z = u + i v

and

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

(the complementary modulus).

Example

This example evaluates

sn z

cn z

and

dn z

z = - 2.0 + 3.0 i

when

k = 0.5

, and prints the results.

Example program (C#): s21cbe.cs

Example program data: s21cbe.d

Example program results: s21cbe.r

Syntax

Parameters

Description

References

Error Indicators and Warnings

Accuracy

Parallelism and Performance

Further Comments

Example

See Also