Document revision date: 30 March 2001

## OpenVMS VAX RTL Mathematics (MTH$) Manual

Previous | Contents | Index

## 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 floating-point 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 floating-point 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:

>             -90 <= angle <= 90

> MTH$ATAND returns an F-floating number. MTH$DATAND returns a D-floating number. MTH$GATAND returns a G-floating 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 floating-point number that is this tangent. For MTH$ATAND, tangent specifies an F-floating number. For MTH$DATAND, tangent specifies a D-floating number. For MTH$GATAND, tangent specifies a G-floating 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 H-floating point version of this routine.

### Condition Value Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xATAND 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 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 floating-point 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 F-floating number. MTH$DATAN2 returns a D-floating number. MTH$GATAN2 returns a G-floating 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 floating-point number that is this dividend. For MTH$ATAN2, sine specifies an F-floating number. For MTH$DATAN2, sine specifies a D-floating number. For MTH$GATAN2, sine specifies a G-floating 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 floating-point number that is this divisor. For MTH$ATAN2, cosine specifies an F-floating number. For MTH$DATAN2, cosine specifies a D-floating number. For MTH$GATAN2, cosine specifies a G-floating 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 H-floating point version of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xATAN2 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 Compaq.
> MTH$_INVARGMAT | Invalid argument. Both cosine and sine are zero. LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point 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 floating-point 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 F-floating number. MTH$DATAND2 returns a D-floating number. MTH$GATAND2 returns a G-floating 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 floating-point number that is this dividend. For MTH$ATAND2, sine specifies an F-floating number. For MTH$DATAND2, sine specifies a D-floating number. For MTH$GATAND2, sine specifies a G-floating 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 floating-point number that is this divisor. For MTH$ATAND2, cosine specifies an F-floating number. For MTH$DATAND2, cosine specifies a D-floating number. For MTH$GATAND2, cosine specifies a G-floating 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 H-floating point version of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xATAND2 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 Compaq.
> MTH$_INVARGMAT | Invalid argument. Both cosine and sine are zero. LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point 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 hyperbolic-tangent

> MTH$DATANH hyperbolic-tangent

> MTH$GATANH hyperbolic-tangent

> 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 arc tangent of hyperbolic-tangent. MTH$ATANH returns an F-floating number. MTH$DATANH returns a D-floating number. MTH$GATANH returns a G-floating number.

### Argument

> #### hyperbolic-tangent

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

> Hyperbolic tangent of an angle. The hyperbolic-tangent argument is the address of a floating-point number that is this hyperbolic tangent. For MTH$ATANH, hyperbolic-tangent specifies an F-floating number. For MTH$DATANH, hyperbolic-tangent specifies a D-floating number. For MTH$GATANH, hyperbolic-tangent specifies a G-floating number.

### Description

> The hyperbolic arc tangent function is computed as follows:

> Value of x | Value Returned
> --- | ---
> |X| < 1 | zATANH(X) = zLOG((1+X)/(1-X))/2
> |X| => 1 | An invalid argument is signaled

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

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$xATANH 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 Compaq.
> MTH$_INVARGMAT | Invalid argument: |X| => 1 . LIB$SIGNAL copies the floating-point reserved operand to the mechanism argument vector CHF$L_MCH_SAVR0/R1. The result is the floating-point 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 complex-number

> MTH$CDABS complex-number

> MTH$CGABS complex-number

> Each of the above formats accepts one of the floating-point 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 F-floating number. MTH$CDABS returns a D-floating number. MTH$CGABS returns a G-floating number.

### Argument

> #### complex-number

> 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 floating-point complex values. The complex-number argument is the address of this complex number. For MTH$CABS, complex-number specifies an F-floating complex number. For MTH$CDABS, complex-number specifies a D-floating complex number. For MTH$CGABS, complex-number specifies a G-floating 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 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 Compaq.
> MTH$_FLOOVEMAT | Floating-point 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    F-floating 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 F-floating complex number for complex-number. 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 G-floating 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 G-floating complex number for complex-number. Because this example uses a G-floating number, it must be compiled as follows:

>     $ Fortran/G MTHEX.FOR

> 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 (F-Floating Value) routine returns the cosine of a complex number as an F-floating value.

### Format

> MTH$CCOS complex-number

### 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 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$CCOS, complex-number specifies an F-floating 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 G-floating point versions of this routine.

### Condition Values Signaled

> SS$_ROPRAND | Reserved operand. The MTH$CCOS 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 Compaq.
> MTH$_FLOOVEMAT | Floating-point overflow in Math Library: the absolute value of i is greater than about 88.029 for F-floating values.

### Example

    C+
    C    This Fortran example forms the complex
    C    cosine of an F-floating 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)

Previous | Next | Contents | Index

| privacy and legal statement |
6117PRO_005.HTML