﻿ s21cb Method
s21cb evaluates the Jacobian elliptic functions $\mathrm{sn} z$, $\mathrm{cn} z$ and $\mathrm{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 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:
• $\mathrm{abs}\left(\mathrm{Re}\left({\mathbf{z}}\right)\right)\le =\sqrt{\lambda }$;
• $\mathrm{abs}\left(\mathrm{Im}\left({\mathbf{z}}\right)\right)\le \sqrt{\lambda }$, where $\lambda =1/{\mathbf{x02am}}$.
ak2
Type: System..::..Double
On entry: the value of ${k}^{2}$.
Constraint: $0.0\le {\mathbf{ak2}}\le 1.0$.
sn
Type: NagLibrary..::..Complex%
On exit: the values of the functions $\mathrm{sn} z$, $\mathrm{cn} z$ and $\mathrm{dn} z$, respectively.
cn
Type: NagLibrary..::..Complex%
On exit: the values of the functions $\mathrm{sn} z$, $\mathrm{cn} z$ and $\mathrm{dn} z$, respectively.
dn
Type: NagLibrary..::..Complex%
On exit: the values of the functions $\mathrm{sn} z$, $\mathrm{cn} z$ and $\mathrm{dn} z$, respectively.
ifail
Type: System..::..Int32%
On exit: ${\mathbf{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 $\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 parameter (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∣k1cnz∣k=dnkz∣k1dnz∣k=cnkz∣k1,$
where ${k}_{1}=1/k$.
Special values include
 $snz∣0=sin zcnz∣0=cos zdnz∣0=1snz∣1=tanh zcnz∣1=sech zdnz∣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 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
 $cd z=cn z/dn zsd z=sn z/dn znd z=1/dn zdc z=dn z/cn znc z=1/cn zsc z=sn z/cn zns z=1/sn zds z=dn z/sn zcs 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 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:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{ak2}}<0.0$, or ${\mathbf{ak2}}>1.0$, or $\mathrm{abs}\left(\mathrm{Re}\left({\mathbf{z}}\right)\right)>\sqrt{\lambda }$, or $\mathrm{abs}\left(\mathrm{Im}\left({\mathbf{z}}\right)\right)>\sqrt{\lambda }$, where $\lambda =1/{\mathbf{x02am}}$.
${\mathbf{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.

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′+icnu,kdnu,ksnv,k′cnv,k′1-dn2u,ksn2v,k′cn z=cnu,kcnv,k′1-dn2u,ksn2v,k′-isnu,kdnu,ksnv,k′dnv,k′1-dn2u,ksn2v,k′dn z=dnu,kcnv,k′dnv,k′1-dn2u,ksn2v,k′-ik2snu,kcnu,ksnv,k′1-dn2u,ksn2v,k′,$
where $z=u+iv$ and ${k}^{\prime }=\sqrt{1-{k}^{2}}$ (the complementary modulus).

# 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.

Example program (C#): s21cbe.cs

Example program data: s21cbe.d

Example program results: s21cbe.r