hide long namesshow long names
hide short namesshow short names
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
    7  Accuracy
    9  Example

Purpose

nag_specfun_jacellip_complex (s21cb) evaluates the Jacobian elliptic functions snz, cnz and dnz 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 snzk, cnzk and dnzk given by
snzk = sinϕ cnzk = cosϕ dnzk = 1-k2sin2ϕ,  
where z is a complex argument, k is a real argument (the modulus) with k21 and ϕ (the amplitude of z) is defined by the integral
z=0ϕdθ 1-k2sin2θ .  
The above definitions can be extended for values of k2>1 (see Salzer (1962)) by means of the formulae
snzk = k1snkzk1 cnzk = dnkzk1 dnzk = cnkzk1,  
where k1=1/k.
Special values include
snz0 = sinz cnz0 = cosz dnz0 = 1 snz1 = tanhz cnz1 = sechz dnz1 = sechz.  
These functions are often simply written as snz, cnz and dnz, 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
cdz = cnz/dnz sdz = snz/dnz ndz = 1/dnz dcz = dnz/cnz ncz = 1/cnz scz = snz/cnz nsz = 1/snz dsz = dnz/snz csz = cnz/snz  
(see Abramowitz and Stegun (1972)).
The values of snz, cnz and dnz 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:
  • absRe(z)=λ;
  • absIm(z)λ, where λ=1/x02am.
2:     ak2 – double scalar
The value of k2.
Constraint: 0.0ak21.0.

Optional Input Parameters

None.

Output Parameters

1:     sn – complex scalar
2:     cn – complex scalar
3:     dn – complex scalar
The values of the functions snz, cnz and dnz, 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,
orak2>1.0,
orabsRez>λ,
orabsImz>λ, 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 snz, cnz and dnz are computed via the formulae
snz = snu,kdnv,k 1-dn2u,ksn2v,k + i cnu,kdnu,ksnv,kcnv,k 1-dn2u,ksn2v,k cnz = cnu,kcnv,k 1-dn2u,ksn2v,k - i snu,kdnu,ksnv,kdnv,k 1-dn2u,ksn2v,k dnz = dnu,kcnv,kdnv,k 1-dn2u,ksn2v,k - i k2snu,kcnu,ksnv,k 1-dn2u,ksn2v,k ,  
where z=u+iv and k=1-k2 (the complementary modulus).

Example

This example evaluates snz, cnz and dnz at z=-2.0+3.0i when k=0.5, and prints the results.
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

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015