Integer type: int32 int64 nag_int show int32 show int32 show int64 show int64 show nag_int show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox

NAG Toolbox: nag_specfun_jacellip_complex (s21cb)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

Purpose

nag_specfun_jacellip_complex (s21cb) evaluates the Jacobian elliptic functions

sn z

cn z

and

dn z

for a complex argument

z

Syntax

[sn, cn, dn, ifail] = s21cb(z, ak2)

[sn, cn, dn, ifail] = nag_specfun_jacellip_complex(z, ak2)

Description

nag_specfun_jacellip_complex (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 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{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 argument

k

. They can also be expressed in terms of Jacobian theta functions (see nag_specfun_jactheta_real (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 nag_specfun_jacellip_real (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

Parameters

Compulsory Input Parameters

1: $z$ – complex scalar

The argument

z

of the functions.

Constraints:

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

2: $ak2$ – double scalar

The value of

k^{2}

Constraint:

0.0 \leq ak2 \leq 1.0

Optional Input Parameters

None.

Output Parameters

1: $sn$ – complex scalar
2: $cn$ – complex scalar
3: $dn$ – complex scalar: The values of the functions $sn z$ , $cn z$ and $dn z$ , respectively.
4: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$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 = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

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.

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.

Open in the MATLAB editor: s21cb_example

function s21cb_example


fprintf('s21cb example results\n\n');

z = -2 +3i;
k = 0.25;

[sn, cn, dn, ifail] = s21cb(z,k);

fprintf(' z = %8.4f%+8.4fi,  k = %7.4f\n\n',real(z), imag(z), k);
fprintf('%16s%23s%23s\n', 'sn(z|k)', 'cn(z|k)', 'dn(z|k)');
fprintf('%10.4f%+10.4fi  %10.4f%+10.4fi  %10.4f%+10.4fi\n', ...
        real(sn), imag(sn), real(cn), imag(cn), real(dn), imag(dn));

s21cb example results

 z =  -2.0000 +3.0000i,  k =  0.2500

         sn(z|k)                cn(z|k)                dn(z|k)
   -1.5865   +0.2456i      0.3125   +1.2468i     -0.6395   -0.1523i

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox