OpenVMS VAX RTL Mathematics (MTH$) Manual

Updated: 12 December 1998

OpenVMS VAX RTL Mathematics (MTH$) Manual

Contents

Index

MTH$xCMPLX

The Complex Number Made from D- or G-Floating Point routines return a complex number from two D- or G-floating input values.

Format

MTH$DCMPLX complx ,real-part ,imaginary-part

MTH$GCMPLX complx ,real-part ,imaginary-part
Each of the above formats accepts one of floating-point complex types as input.

RETURNS

None.

Arguments

complx

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: write only

mechanism: by reference

The floating-point complex value of a complex number. The complex exponential functions that have D-floating complex and G-floating complex input values write the address of this floating-point complex value into complx. For MTH$DCMPLX, complx specifies a D-floating complex number. For MTH$GCMPLX, complx specifies a G-floating complex number. For MTH$CMPLX, complx is not used.
real-part

OpenVMS usage: floating_point

type: D_floating, G_floating

access: read only

mechanism: by reference

Real part of a complex number. The real-part argument is the address of a floating-point number that contains this real part, r, of (r,i). For MTH$DCMPLX, real-part specifies a D-floating number. For MTH$GCMPLX, real-part specifies a G-floating number.
imaginary-part

OpenVMS usage: floating_point

type: D_floating, G_floating

access: read only

mechanism: by reference

Imaginary part of a complex number. The imaginary-part argument is the address of a floating-point number that contains this imaginary part, i, of (r,i). For MTH$DCMPLX, imaginary-part specifies a D-floating number. For MTH$GCMPLX, imaginary-part specifies a G-floating number.

Condition Value Signaled

SS$_ROPRAND Reserved operand. The MTH$xCMPLX routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

Example


C+ C This Fortran example forms two D-floating C point complex numbers using MTH$CMPLX C and the Fortran random number generator RAN. C C Declare Z and MTH$DCMPLX as complex values, and R C and I as real values. MTH$DCMPLX takes two real C D-floating point values and returns one C COMPLEX16 number. C C- COMPLEX16 Z REAL8 R,I INTEGER M M = 1234567 R = RAN(M) I = RAN(M) CALL MTH$DCMPLX(Z,R,I) C+ C Z is a complex number (r,i) with real part "r" and imaginary C part "i". C- TYPE , ' The two input values are:',R,I TYPE *, ' The complex number z is',Z END

C+ 
C    This Fortran example forms two D-floating 
C    point complex numbers using MTH$CMPLX 
C    and the Fortran random number generator RAN. 
C 
C    Declare Z and MTH$DCMPLX as complex values, and R 
C    and I as real values.  MTH$DCMPLX takes two real 
C    D-floating point values and returns one 
C    COMPLEX*16 number. 
C 
C- 
 
        COMPLEX*16 Z 
        REAL*8 R,I 
        INTEGER M 
        M = 1234567 
        R = RAN(M) 
        I = RAN(M) 
        CALL MTH$DCMPLX(Z,R,I) 
 
C+ 
C    Z is a complex number (r,i) with real part "r" and imaginary 
C    part "i". 
C- 
 
        TYPE *, ' The two input values are:',R,I 
        TYPE *, ' The complex number z is',Z 
        END

This Fortran example demonstrates how to make a procedure call to MTH$DCMPLX. Notice the difference in the precision of the output generated.
The two input values are: 0.8535407185554504 0.2043401598930359 The complex number z is (0.8535407185554504,0.2043401598930359)

MTH$CONJG

The Conjugate of a Complex Number (F-Floating Value) routine returns the complex conjugate (r,-i) of a complex number (r,i) as an F-floating value.

Format

MTH$CONJG complex-number

RETURNS

OpenVMS usage: complex_number

type: F_floating complex

access: write only

mechanism: by value

Complex conjugate of a complex number. MTH$CONJG returns an F-floating complex number.

Argument

complex-number

OpenVMS usage: complex_number

type: F_floating complex

access: read only

mechanism: by reference

A complex number (r,i), where r and i are floating-point numbers. The complex-number argument is the address of this floating-point complex number. For MTH$CONJG, complex-number specifies an F-floating number.

Description

The MTH$CONJG routine returns the complex conjugate (r,-i) of a complex number (r,i) as an F-floating value.
See MTH$xCONJG for the descriptions of the D- and G-floating point versions of this routine.

Condition Value Signaled

SS$_ROPRAND Reserved operand. The MTH$CONJG routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

MTH$xCONJG

The Conjugate of a Complex Number routine returns the complex conjugate (r,-i) of a complex number (r,i).

Format

MTH$DCONJG complex-conjugate ,complex-number

MTH$GCONJG complex-conjugate ,complex-number
Each of the above formats accepts one of the floating-point complex types as input.

RETURNS

None.

Arguments

complex-conjugate

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: write only

mechanism: by reference

The complex conjugate (r,-i) of the complex number specified by complex-number. MTH$DCONJG and MTH$GCONJG write the address of this complex conjugate into complex-conjugate. For MTH$DCONJG, the complex-conjugate argument specifies the address of a D-floating complex number. For MTH$GCONJG, the complex-conjugate argument specifies the address of a G-floating complex number.
complex-number

OpenVMS usage: complex_number

type: D_floating complex, G_floating complex

access: read only

mechanism: by reference

A complex number (r,i), where r and i are floating-point numbers. The complex-number argument is the address of this floating-point complex number. For MTH$DCONJG, complex-number specifies a D-floating number. For MTH$GCONJG, complex-number specifies a G-floating number.

Description

The MTH$xCONJG routines return the complex conjugate (r,-i) of a complex number (r,i),

Condition Value Signaled

SS$_ROPRAND Reserved operand. The MTH$xCONJG routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

Example


C+ C This Fortran example forms the complex conjugate C of a G-floating complex number using MTH$GCONJG C and the Fortran random number generator RAN. C C Declare Z, Z_NEW, and MTH$GCONJG as a complex values. C MTH$GCONJG will return the complex conjugate C value of Z: Z_NEW = MTH$GCONJG(Z). C- COMPLEX16 Z,Z_NEW,MTH$GCONJG COMPLEX16 MTH$GCMPLX REAL8 R,I,MTH$GREAL,MTH$GIMAG INTEGER M M = 1234567 C+ C Generate a random complex number with the Fortran generic CMPLX. C- R = RAN(M) I = RAN(M) Z = MTH$GCMPLX(R,I) TYPE , ' The complex number z is',z TYPE 1,MTH$GREAL(Z),MTH$GIMAG(Z) 1 FORMAT(' with real part ',F20.16,' and imaginary part',F20.16) TYPE , ' ' C+ C Compute the complex absolute value of Z. C- Z_NEW = MTH$GCONJG(Z) TYPE , ' The complex conjugate value of',z,' is',Z_NEW TYPE 1,MTH$GREAL(Z_NEW),MTH$GIMAG(Z_NEW) END

C+ 
C    This Fortran example forms the complex conjugate 
C    of a G-floating complex number using MTH$GCONJG 
C    and the Fortran random number generator RAN. 
C 
C    Declare Z, Z_NEW, and MTH$GCONJG as a complex values. 
C    MTH$GCONJG will return the complex conjugate 
C    value of Z:   Z_NEW = MTH$GCONJG(Z). 
C- 
        COMPLEX*16 Z,Z_NEW,MTH$GCONJG 
        COMPLEX*16 MTH$GCMPLX 
        REAL*8 R,I,MTH$GREAL,MTH$GIMAG 
        INTEGER M 
        M = 1234567 
C+ 
C    Generate a random complex number with the Fortran generic CMPLX. 
C- 
        R = RAN(M) 
        I = RAN(M) 
        Z = MTH$GCMPLX(R,I) 
        TYPE *, ' The complex number z is',z 
        TYPE 1,MTH$GREAL(Z),MTH$GIMAG(Z) 
   1    FORMAT(' with real part ',F20.16,' and imaginary part',F20.16) 
        TYPE *, ' ' 
C+ 
C    Compute the complex absolute value of Z. 
C- 
        Z_NEW = MTH$GCONJG(Z) 
        TYPE *, ' The complex conjugate value of',z,' is',Z_NEW 
        TYPE 1,MTH$GREAL(Z_NEW),MTH$GIMAG(Z_NEW) 
        END

This Fortran example demonstrates how to make a function call to MTH$GCONJG. Because G-floating numbers are used, the examples must be compiled with the statement "Fortran/G filename".
The output generated by this program is as follows:
The complex number z is (0.853540718555450,0.204340159893036) with real part 0.8535407185554504 and imaginary part 0.2043401598930359 The complex conjugate value of (0.853540718555450,0.204340159893036) is (0.853540718555450,-0.204340159893036) with real part 0.8535407185554504 and imaginary part -0.2043401598930359

MTH$xCOS

The Cosine of Angle Expressed in Radians routine returns the cosine of a given angle (in radians).

Format

MTH$COS angle-in-radians

MTH$DCOS angle-in-radians

MTH$GCOS angle-in-radians
Each of the above formats accepts one of the floating-point types as input.
Corresponding JSB Entry Points

MTH$COS_R4

MTH$DCOS_R7

MTH$GCOS_R7
Each of the above JSB entry points accepts one of the floating-point types as input.

RETURNS

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: write only

mechanism: by value

Cosine of the angle. MTH$COS returns an F-floating number. MTH$DCOS returns a D-floating number. MTH$GCOS returns a G-floating number.

Argument

angle-in-radians

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: read only

mechanism: by reference

The angle in radians. The angle-in-radians argument is the address of a floating-point number. For MTH$COS, angle-in-radians is an F-floating number. For MTH$DCOS, angle-in-radians specifies a D-floating number. For MTH$GCOS, angle-in-radians specifies a G-floating number.

Description

See MTH$xSINCOS for the algorithm used to compute the cosine.
See MTH$HCOS for the description of the H-floating point version of this routine.

Condition Value Signaled

SS$_ROPRAND Reserved operand. The MTH$xCOS routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

MTH$xCOSD

The Cosine of Angle Expressed in Degrees routine returns the cosine of a given angle (in degrees).

Format

MTH$COSD angle-in-degrees

MTH$DCOSD angle-in-degrees

MTH$GCOSD angle-in-degrees
Each of the above formats accepts one of the floating-point types as input.
Corresponding JSB Entry Points

MTH$COSD_R4

MTH$DCOSD_R7

MTH$GCOSD_R7
Each of the above JSB entry points accepts one of the floating-point types as input.

RETURNS

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: write only

mechanism: by value

Cosine of the angle. MTH$COSD returns an F-floating number. MTH$DCOSD returns a D-floating number. MTH$GCOSD returns a G-floating number.

Argument

angle-in-degrees

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: read only

mechanism: by reference

Angle (in degrees). The angle-in-degrees argument is the address of a floating-point number. For MTH$COSD, angle-in-degrees specifies an F-floating number. For MTH$DCOSD, angle-in-degrees specifies a D-floating number. For MTH$GCOSD, angle-in-degrees specifies a G-floating number.

Description

See MTH$xSINCOS for the algorithm used to compute the cosine.
See MTH$HCOSD for the description of the H-floating point version of this routine.

Condition Value Signaled

SS$_ROPRAND Reserved operand. The MTH$xCOSD routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

MTH$xCOSH

The Hyperbolic Cosine routine returns the hyperbolic cosine of the input value.

Format

MTH$COSH floating-point-input-value

MTH$DCOSH floating-point-input-value

MTH$GCOSH floating-point-input-value
Each of the above formats accepts one of the floating-point types as input.

RETURNS

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: write only

mechanism: by value

The hyperbolic cosine of the input value floating-point-input-value. MTH$COSH returns an F-floating number. MTH$DCOSH returns a D-floating number. MTH$GCOSH returns a G-floating number.

Argument

floating-point-input-value

OpenVMS usage: floating_point

type: F_floating, D_floating, G_floating

access: read only

mechanism: by reference

The input value. The floating-point-input-value argument is the address of this input value. For MTH$COSH, floating-point-input-value specifies an F-floating number. For MTH$DCOSH, floating-point-input-value specifies a D-floating number. For MTH$GCOSH, floating-point-input-value specifies a G-floating number.

Description

Computation of the hyperbolic cosine depends on the magnitude of the input argument. The range of the function is partitioned using four data-type-dependent constants: a(z), b(z), and c(z). The subscript z indicates the data type. The constants depend on the number of exponent bits (e) and the number of fraction bits (f) associated with the data type (z).
The values of e and f are:

z e f

F 8 24

D 8 56

G 11 53

The values of the constants in terms of e and f are:

Variable Value

a(z) 2 ^(-f/2)

b(z) CEILING[ (f+1)/2*ln(2) ]

c(z) (2 ^e-1)*ln(2)

Based on the above definitions, zCOSH(X) is computed as follows:

Value of X Value Returned

|X| < a(z) 1

a(z) <= |X| < .25 Computed using a power series expansion in |X| ²

.25 <= |X| < b(z) (zEXP(|X|) + 1/zEXP(|X|))/2

b(z) <= |X| < c(z) zEXP(|X|)/2

c(z) <= |x| Overflow occurs

See MTH$HCOSH for the description of the H-floating point version of this routine.

z	e	f
F	8	24
D	8	56
G	11	53

Variable	Value
a(z)	2 ^(-f/2)
b(z)	CEILING[ (f+1)/2*ln(2) ]
c(z)	(2 ^e-1)*ln(2)

Value of X	Value Returned
\|X\| < a(z)	1
a(z) <= \|X\| < .25	Computed using a power series expansion in \|X\| ²
.25 <= \|X\| < b(z)	(zEXP(\|X\|) + 1/zEXP(\|X\|))/2
b(z) <= \|X\| < c(z)	zEXP(\|X\|)/2
c(z) <= \|x\|	Overflow occurs

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$xCOSH routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

MTH$_FLOOVEMAT Floating-point overflow in Math Library: the absolute value of floating-point-input-value is greater than about yyy; LIB$SIGNAL copies the reserved operand to the signal mechanism vector. The result is the reserved operand -0.0 unless a condition handler changes the signal mechanism vector.
The values of yyy are:

MTH$COSH---88.722
MTH$DCOSH---88.722
MTH$GCOSH---709.782

MTH$CSIN

The Sine of a Complex Number (F-Floating Value) routine returns the sine of a complex number (r,i) as an F-floating value.

Format

MTH$CSIN complex-number

RETURNS

OpenVMS usage: complex_number

type: F_floating complex

access: write only

mechanism: by value

Complex sine of the complex number. MTH$CSIN returns an F-floating complex number.

Argument

complex-number

OpenVMS usage: complex_number

type: F_floating complex

access: read only

mechanism: by reference

A complex number (r,i), where r and i are floating-point numbers. The complex-number argument is the address of this complex number. For MTH$CSIN, complex-number specifies an F-floating complex number.

Description

The complex sine is computed as follows:
complex-sine = (SIN(r) * COSH(i), COS(r) * SINH(i))

See MTH$CxSIN for the descriptions of the D- and G-floating point versions of this routine.

Condition Values Signaled

SS$_ROPRAND Reserved operand. The MTH$CSIN routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.

MTH$_FLOOVEMAT Floating-point overflow in Math Library: the absolute value of i is greater than about 88.029 for F-floating values.

Contents

Index

Legal

 
6117PRO_007.HTML

OpenVMS usage:	complex_number
type:	D_floating complex, G_floating complex
access:	write only
mechanism:	by reference

OpenVMS usage:	floating_point
type:	D_floating, G_floating
access:	read only
mechanism:	by reference

SS$_ROPRAND	Reserved operand. The MTH$CSIN routine encountered a floating-point reserved operand due to incorrect user input. A floating-point reserved operand is a floating-point datum with a sign bit of 1 and a biased exponent of 0. Floating-point reserved operands are reserved for future use by Digital.
MTH$_FLOOVEMAT	Floating-point overflow in Math Library: the absolute value of i is greater than about 88.029 for F-floating values.