
OpenVMS VAX RTL Mathematics (MTH$) Manual
MTH$xATAND
Given the tangent of an angle, the Arc Tangent in Degrees routine
returns that angle (in degrees).
Format
MTH$ATAND tangent
MTH$DATAND tangent
MTH$GATAND tangent
Each of the above formats accepts one of the floatingpoint types as
input. Corresponding JSB Entry Points
MTH$ATAND_R4
MTH$DATAND_R7
MTH$GATAND_R7
Each of the above JSB entry points accepts one of the floatingpoint
types as input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
Angle in degrees. The angle returned will have a value in the range:
MTH$ATAND returns an Ffloating number. MTH$DATAND returns a Dfloating
number. MTH$GATAND returns a Gfloating number.
Argument
tangent
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
The tangent of the angle whose value (in degrees) is to be returned.
The tangent argument is the address of a
floatingpoint number that is this tangent. For MTH$ATAND,
tangent specifies an Ffloating number. For
MTH$DATAND, tangent specifies a Dfloating number. For
MTH$GATAND, tangent specifies a Gfloating number.
Description
The computation of the arc tangent function is based on the following
identities:

arctan(X) = (180/Pi sign)* (X  X
^{3}/3 + X
^{5}/5  X
^{7}/7 + ...)


arctan(X) = 64*X + X*Q(X
^{2}),
where Q(Y) = 180/Pi*[(1 64*Pi sign/180)]  Y/3 + Y
^{2}/5  Y
^{3}/7 + Y
^{4}/9


arctan(X) = X*P(X
^{2}),
where P(Y) = 180/Pi sign*[1  Y/3 + Y
^{2}/5  Y
^{3}/7 + Y
^{4}/9 ...]


arctan(X) = 90  arctan(1/X)


arctan(X) = arctan(A) + arctan((X  A)/(1 + A*X))

The angle in degrees whose tangent is X is computed as:
Tangent 
Angle Returned 
X
<= 3/32

64*X + X*Q(X
^{2})

3/32
< X
<= 11

ATAND(A) + V*P(V
^{2}) , where A and ATAND(A) are chosen by table lookup and V
=(X  A)/(1 + A*X)

11
< X

90  W * (P(W
^{2})), where W = 1/X

X
< 0

zATAND(X)

See MTH$HATAND for the description of the Hfloating point version of
this routine.
Condition Value Signaled
SS$_ROPRAND

Reserved operand. The MTH$xATAND routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$xATAN2
Given sine and cosine, the Arc
Tangent in Radians with Two Arguments routine returns the angle (in
radians) whose tangent is given by the quotient of
sine and cosine
(sine/cosine).
Format
MTH$ATAN2 sine ,cosine
MTH$DATAN2 sine ,cosine
MTH$GATAN2 sine ,cosine
Each of the above formats accepts one of the floatingpoint types as
input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
Angle in radians. MTH$ATAN2 returns an Ffloating number. MTH$DATAN2
returns a Dfloating number. MTH$GATAN2 returns a Gfloating number.
Arguments
sine
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
Dividend. The sine argument is the address of a
floatingpoint number that is this dividend. For MTH$ATAN2,
sine specifies an Ffloating number. For MTH$DATAN2,
sine specifies a Dfloating number. For MTH$GATAN2,
sine specifies a Gfloating number.
cosine
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
Divisor. The cosine argument is the address of a
floatingpoint number that is this divisor. For MTH$ATAN2,
cosine specifies an Ffloating number. For MTH$DATAN2,
cosine specifies a Dfloating number. For MTH$GATAN2,
cosine specifies a Gfloating number.
Description
The angle in radians whose tangent is Y/X is computed
as follows, where f is defined in the description of MTH$zCOSH.
Value of Input Arguments 
Angle Returned 
X = 0 or Y/X > 2
^{(f+1)}

Pi sign/2* (sign Y)

X > 0 and Y/X
<= 2
^{(f+1)}

zATAN(Y/X)

X
< 0 and Y/X
<= 2
^{(f+1)}

Pi sign* (sign Y) + zATAN(Y/X)

See MTH$HATAN2 for the description of the Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xATAN2 routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$_INVARGMAT

Invalid argument. Both
cosine and
sine are zero. LIB$SIGNAL copies the floatingpoint
reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1.
The result is the floatingpoint reserved operand unless you have
written a condition handler to change CHF$L_MCH_SAVR0/R1.

MTH$xATAND2
Given sine and cosine, the Arc
Tangent in Degrees with Two Arguments routine returns the angle (in
degrees) whose tangent is given by the quotient of
sine and cosine
(sine/cosine).
Format
MTH$ATAND2 sine ,cosine
MTH$DATAND2 sine ,cosine
MTH$GATAND2 sine ,cosine
Each of the above formats accepts one of the floatingpoint types as
input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
Angle in degrees. MTH$ATAND2 returns an Ffloating number. MTH$DATAND2
returns a Dfloating number. MTH$GATAND2 returns a Gfloating number.
Arguments
sine
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
Dividend. The sine argument is the address of a
floatingpoint number that is this dividend. For MTH$ATAND2,
sine specifies an Ffloating number. For MTH$DATAND2,
sine specifies a Dfloating number. For MTH$GATAND2,
sine specifies a Gfloating number.
cosine
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
Divisor. The cosine argument is the address of a
floatingpoint number that is this divisor. For MTH$ATAND2,
cosine specifies an Ffloating number. For
MTH$DATAND2, cosine specifies a Dfloating number. For
MTH$GATAND2, cosine specifies a Gfloating number.
Description
The angle in degrees whose tangent is Y/X is computed
below and where f is defined in the description of MTH$zCOSH.
Value of Input Arguments 
Angle Returned 
X = 0 or Y/X > 2
^{(f+1)}

90* (sign Y)

X > 0 and Y/X
<= 2
^{(f+1)}

zATAND(Y/X)

X
< 0 and Y/X
<= 2
^{(f+1)}

180 * (sign Y) + zATAND(Y/X)

See MTH$HATAND2 for the description of the Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xATAND2 routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$_INVARGMAT

Invalid argument. Both
cosine and
sine are zero. LIB$SIGNAL copies the floatingpoint
reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1.
The result is the floatingpoint reserved operand unless you have
written a condition handler to change CHF$L_MCH_SAVR0/R1.

MTH$xATANH
Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent
routine returns the hyperbolic arc tangent of that angle.
Format
MTH$ATANH hyperbolictangent
MTH$DATANH hyperbolictangent
MTH$GATANH hyperbolictangent
Each of the above formats accepts one of the floatingpoint types as
input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
The hyperbolic arc tangent of hyperbolictangent.
MTH$ATANH returns an Ffloating number. MTH$DATANH returns a Dfloating
number. MTH$GATANH returns a Gfloating number.
Argument
hyperbolictangent
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
read only 
mechanism: 
by reference 
Hyperbolic tangent of an angle. The hyperbolictangent
argument is the address of a floatingpoint number that is this
hyperbolic tangent. For MTH$ATANH, hyperbolictangent
specifies an Ffloating number. For MTH$DATANH,
hyperbolictangent specifies a Dfloating number. For
MTH$GATANH, hyperbolictangent specifies a Gfloating
number.
Description
The hyperbolic arc tangent function is computed as follows:
Value of x 
Value Returned 
X
< 1

zATANH(X) = zLOG((1+X)/(1X))/2

X => 1

An invalid argument is signaled

See MTH$HATANH for the description of the Hfloating point version of
this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$xATANH routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$_INVARGMAT

Invalid argument: X => 1 . LIB$SIGNAL copies the floatingpoint
reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1.
The result is the floatingpoint reserved operand unless you have
written a condition handler to change CHF$L_MCH_SAVR0/R1.

MTH$CxABS
The Complex Absolute Value routine returns the absolute value of a
complex number (r,i).
Format
MTH$CABS complexnumber
MTH$CDABS complexnumber
MTH$CGABS complexnumber
Each of the above formats accepts one of the floatingpoint complex
types as input.
RETURNS
OpenVMS usage: 
floating_point 
type: 
F_floating, D_floating, G_floating 
access: 
write only 
mechanism: 
by value 
The absolute value of a complex number. MTH$CABS returns an Ffloating
number. MTH$CDABS returns a Dfloating number. MTH$CGABS returns a
Gfloating number.
Argument
complexnumber
OpenVMS usage: 
complex_number 
type: 
F_floating complex, D_floating complex, G_floating
complex 
access: 
read only 
mechanism: 
by reference 
A complex number (r,i), where r and i are both floatingpoint complex
values. The complexnumber argument is the address of
this complex number. For MTH$CABS, complexnumber
specifies an Ffloating complex number. For MTH$CDABS,
complexnumber specifies a Dfloating complex number.
For MTH$CGABS, complexnumber specifies a Gfloating
complex number.
Description
The complex absolute value is computed as follows, where MAX
is the larger of r and i, and MIN is the smaller of r
and i: result = MAX * SQRT((MIN/MAX)^{2} + 1)
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$CxABS routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library when both
r and
i are large.

Examples
#1 
C+
C This Fortran example forms the absolute value of an
C Ffloating complex number using MTH$CABS and the
C Fortran random number generator RAN.
C
C Declare Z as a complex value and MTH$CABS as a REAL*4 value.
C MTH$CABS will return the absolute value of Z: Z_NEW = MTH$CABS(Z).
C
COMPLEX Z
COMPLEX CMPLX
REAL*4 Z_NEW,MTH$CABS
INTEGER M
M = 1234567
C+
C Generate a random complex number with the Fortran generic CMPLX.
C
Z = CMPLX(RAN(M),RAN(M))
C+
C Z is a complex number (r,i) with real part "r" and
C imaginary part "i".
C
TYPE *, ' The complex number z is',z
TYPE *, ' It has real part',REAL(Z),'and imaginary part',AIMAG(Z)
TYPE *, ' '
C+
C Compute the complex absolute value of Z.
C
Z_NEW = MTH$CABS(Z)
TYPE *, ' The complex absolute value of',z,' is',Z_NEW
END

This example uses an Ffloating complex number for
complexnumber. The output of this Fortran example is
as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407 and imaginary part 0.2043402
The complex absolute value of (0.8535407,0.2043402) is 0.8776597

#2 
C+
C This Fortran example forms the absolute
C value of a Gfloating complex number using
C MTH$CGABS and the Fortran random number
C generator RAN.
C
C Declare Z as a complex value and MTH$CGABS as a
C REAL*8 value. MTH$CGABS will return the absolute
C value of Z: Z_NEW = MTH$CGABS(Z).
C
COMPLEX*16 Z
REAL*8 Z_NEW,MTH$CGABS
C+
C Generate a random complex number with the Fortran
C generic CMPLX.
C
Z = (12.34567890123,45.536376385345)
TYPE *, ' The complex number z is',z
TYPE *, ' '
C+
C Compute the complex absolute value of Z.
C
Z_NEW = MTH$CGABS(Z)
TYPE *, ' The complex absolute value of',z,' is',Z_NEW
END

This Fortran example uses a Gfloating complex number for
complexnumber. Because this example uses a Gfloating
number, it must be compiled as follows:
Notice the difference in the precision of the output generated:
The complex number z is (12.3456789012300,45.5363763853450)
The complex absolute value of (12.3456789012300,45.5363763853450) is
47.1802645376230

MTH$CCOS
The Cosine of a Complex Number (FFloating Value) routine returns the
cosine of a complex number as an Ffloating value.
Format
MTH$CCOS complexnumber
RETURNS
OpenVMS usage: 
complex_number 
type: 
F_floating complex 
access: 
write only 
mechanism: 
by value 
The complex cosine of the complex input number. MTH$CCOS returns an
Ffloating complex number.
Argument
complexnumber
OpenVMS usage: 
complex_number 
type: 
F_floating complex 
access: 
read only 
mechanism: 
by reference 
A complex number (r,i) where r and i are floatingpoint numbers. The
complexnumber argument is the address of this complex
number. For MTH$CCOS, complexnumber specifies an
Ffloating complex number.
Description
The complex cosine is calculated as follows: result = (COS(r) *
COSH(i), SIN(r) * SINH(i))
See MTH$CxCOS for the descriptions of the D and Gfloating point
versions of this routine.
Condition Values Signaled
SS$_ROPRAND

Reserved operand. The MTH$CCOS routine encountered a floatingpoint
reserved operand due to incorrect user input. A floatingpoint reserved
operand is a floatingpoint datum with a sign bit of 1 and a biased
exponent of 0. Floatingpoint reserved operands are reserved for future
use by Compaq.

MTH$_FLOOVEMAT

Floatingpoint overflow in Math Library: the absolute value of
i is greater than about 88.029 for Ffloating values.

Example

C+
C This Fortran example forms the complex
C cosine of an Ffloating complex number using
C MTH$CCOS and the Fortran random number
C generator RAN.
C
C Declare Z and MTH$CCOS as complex values.
C MTH$CCOS will return the cosine value of
C Z: Z_NEW = MTH$CCOS(Z)
C
COMPLEX Z,Z_NEW,MTH$CCOS
COMPLEX CMPLX
INTEGER M
M = 1234567
C+
C Generate a random complex number with the
C Fortran generic CMPLX.
C
Z = CMPLX(RAN(M),RAN(M))
C+
C Z is a complex number (r,i) with real part "r" and
C imaginary part "i".
C
TYPE *, ' The complex number z is',z
TYPE *, ' It has real part',REAL(Z),'and imaginary part',AIMAG(Z)
TYPE *, ' '
C+
C Compute the complex cosine value of Z.
C
Z_NEW = MTH$CCOS(Z)
TYPE *, ' The complex cosine value of',z,' is',Z_NEW
END

This Fortran example demonstrates the use of MTH$CCOS, using the
MTH$CCOS entry point. The output of this program is as follows:
The complex number z is (0.8535407,0.2043402)
It has real part 0.8535407 and imaginary part 0.2043402
The complex cosine value of (0.8535407,0.2043402) is (0.6710899,0.1550672)

