To: J3                                                     J3/19-204
From: Tom Knox
Subject: IEEE Circular trigonometric functions (US05)
Date: 2019-August-06
Reference:  19-157r1, 18-007r1

1 Introduction

Addition of the circular trigonometric functions was given specifications
in m218, during which 19-157r1 was passed.  This paper makes minor
corrections and proposes edits.

2 Specifications

These elemental intrinsics are generic and not specific.
All would be similar to their radian counterparts except that the
argument(s) or return values would be half-revolutions.

3 Syntax

    ACOSPI (X)
    Description: Inverse circular cosine function.
    Class: Elemental function.
    Argument: X shall be of type real with a value that satisfies the
              inequality |X| <= 1.
    Result Characteristics: Same as X.
    Result Value: The result has a value equal to a processor-dependent
    approximation to arccos(X)/pi. It is expressed in
    half-revolutions and lies in the range of 0 to 1.

    ASINPI (X)
    Description: Inverse circular sine function.
    Class: Elemental function.
    Argument: X shall be of type real with a value that satisfies the
              inequality |X| <= 1.
    Result Characteristics: Same as X.
    Result Value: The result has a value equal to a processor-dependent
    approximation to arcsin(X)/pi. It is expressed in half-revolutions
    and lies in the range of -1/2 to 1/2.

    ATANPI (X) or ATANPI (Y, X)
    Description: Inverse circular tangent function.
    Class: Elemental function.
    Arguments:
     Y     shall be of type real.
     X     If Y appears, X shall be of type real with the same kind type
           parameter as Y. If Y has the value zero, X shall not have the
           value zero. If Y does not appear, X shall be of type real.
    Result Characteristics: Same as X.
    Result Value: If Y appears, the result is the same as the result of
    ATAN2PI (Y, X). If Y does not appear, the result has a value equal
    to a processor-dependent approximation to arctan(X)/pi and lies in
    the range -1/2 to 1/2.

    ATAN2PI (Y, X)
    Description: Inverse circular tangent function.
    Class: Elemental function.
    Arguments:
     Y     shall be of type real.
     X     X shall be of the same type and kind type
           parameter as Y. If Y has the value zero, X shall not have the
           value zero.
    Result Characteristics: Same as X
    Result Value: The result has a value equal to a processor-dependent
    approximation to arctan(Y/X)/pi if X != 0; it lies in the range
    -1 to 1. If Y > zero, the result is positive. If Y < zero, the
    result is negative. If Y = zero, the result is Y (if X > zero),
    approximately 1 (if X < zero and Y is positive real zero or the
    processor does not distinguish between positive and negative real
    zero) or approximately -1 (if Y is negative real zero). If X = zero,
    the absolute value of the result is approximately 1/2.

    COSPI (X)
    Description: Circular cosine function.
    Class: Elemental function.
    Argument: X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics: Same as X.
    Result Value: The result has a value equal to a processor-dependent
    approximation to cos(X * pi).

    SINPI (X)
    Description: Circular sine function.
    Class: Elemental function.
    Argument: X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics: Same as X.
    Result Value: The result has a value equal to a processor-dependent
    approximation to sin(X * pi).

    TANPI (X)
    Description: Circular tangent function.
    Class: Elemental function.
    Argument: X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics: Same as X.
    Result Value: The result has a value equal to a processor-dependent
    approximation to tan(X * pi).

4 Edits to 18-007r1
"""""""""""""""""""

{add mention of circular trigonometric intrinsics to the introduction}

[xiii, "Intrinsic procedures and modules" bullet point]

Add: "New intrinsic functions support trigonometric computation
in which angles are specified in half-revolutions (that is, as
multiples of pi): ACOSPI, ASINPI, ATANPI, ATAN2PI, COSPI, SINPI,
and TANPI."

{add ACOSPI to the table describing standard generic intrinsic
procedures}

[332:15+, 16.7.2, Table 16.1, below the entry for "ACOSH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"ACOSPI     (X)                E    Inverse circular cosine function."

{add ASINPI to the table describing standard generic intrinsic
procedures}

[333, 16.7.2, Table 16.1, below the entry for "ASINH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"ASINPI     (X)                E    Inverse circular sine function."

{add ATANPI to the table describing standard generic intrinsic
procedures}

[333, 16.7.2, Table 16.1, below the entry for "ATANH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"ATANPI     (X) or (Y, X)      E    Inverse circular tangent function."

{add ATAN2PI to the table describing standard generic intrinsic
procedures}

[333, 16.7.2, Table 16.1, below the entry for "ATANH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"ATAN2PI    (Y, X)             E    Inverse circular tangent function."

{add COSPI to the table describing standard generic intrinsic
procedures}

[334, 16.7.2, Table 16.1, below the entry for "COSHAPE"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"COSPI      (X)                E    Circular cosine function."

{add SINPI to the table describing standard generic intrinsic
procedures}

[337, 16.7.2, Table 16.1, below the entry for "SINH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"SINPI      (X)                E    Circular sine function."

{add TANPI to the table describing standard generic intrinsic
procedures}

[337, 16.7.2, Table 16.1, below the entry for "TANH"] add
(first field under "Procedure" in the table, second field under
"Arguments" in the table, third field under "Class" in the table,
final field under "Description" in the table):

"TANPI      (X)                E    Circular tangent function."

{add the description of the ACOSPI intrinsic}

[340:36+, 16.9.5+]

Add a new sub-subsection 16.9.5+:

    "
    ACOSPI (X)
    Description. Inverse circular cosine function.
    Class. Elemental function.
    Argument. X shall be of type real with a value that satisfies the
              inequality |X| <= 1.
    Result Characteristics. Same as X.
    Result Value. The result has a value equal to a processor-dependent
    approximation to arccos(X)/pi. It is expressed in
    half-revolutions and lies in the range 0 <= ACOSPI (X) <= 1.
    Example. ACOSPI (-1.0) has the value 1.0 (approximately).
    "

{add the description of the ASINPI intrinsic}

[344:4+, 16.9.15+]

Add a new sub-subsection 16.9.15+:

    "
    ASINPI (X)
    Description. Inverse circular sine function.
    Class. Elemental function.
    Argument. X shall be of type real with a value that satisfies the
              inequality |X| <= 1.
    Result Characteristics. Same as X.
    Result Value. The result has a value equal to a processor-dependent
    approximation to arcsin(X)/pi. It is expressed in half-revolutions
    and lies in the range -1/2 <= ASINPI (X) <= 1/2.
    Example. ASINPI (1.0) has the value 0.5 (approximately).
    "

{add the description of the ATANPI intrinsic}

[346:1+, 16.9.19+]

Add a new sub-subsection 16.9.19+:

    "
    ATANPI (X) or ATANPI (Y,X)
    Description. Inverse circular tangent function.
    Class. Elemental function.
    Arguments.
     Y     shall be of type real.
     X     If Y appears, X shall be of type real with the same kind type
           parameter as Y. If Y has the value zero, X shall not have the
           value zero. If Y does not appear, X shall be of type real.
    Result Characteristics. Same as X.
    Result Value. If Y appears, the result is the same as the result of
    ATAN2PI (Y, X). If Y does not appear, the result has a value equal
    to a processor-dependent approximation to arctan(X)/pi and lies in
    the range -1/2 <= ATANPI (X) <= 1/2.
    Example. ATANPI (1.0) has the value 0.25 (approximately).
    "

{add the description of the ATAN2PI intrinsic}

[346:1+, 16.9.19+]

Add a new sub-subsection 16.9.19+:

    "
    ATAN2PI (Y, X)
    Description. Inverse circular tangent function.
    Class. Elemental function.
    Arguments.
     Y     shall be of type real.
     X     X shall be of the same type and kind type
           parameter as Y. If Y has the value zero, X shall not have the
           value zero.
    Result Characteristics. Same as X
    Result Value. The result has a value equal to a processor-dependent
    approximation to arctan(Y/X)/pi if X != 0; it lies in the range
    -1 <= ATAN2PI (Y, X) <= 1.  If Y > zero, the result is positive.
    If Y < zero, the result is negative.  If Y = zero, the result is Y
    (if X > zero), approximately 1 (if X < zero and Y is positive real
    zero or the processor does not distinguish between positive and
    negative real zero) or approximately -1 (if Y is negative real
    zero). If X = zero, the absolute value of the result is approximately
    1/2.
    Example. ATAN2PI (1.0, 1.0) has the value 0.25 (approximately).  If Y
    has the value $\begin{array}[cc] 1 & 1 // -1 & -1 \end{array}$ and X
    has the value $\begin{array}[cc] -1 & 1 // -1 & 1 \end{array}$, the
    value of ATAN2PI (Y, X) is approximately
    $\begin{array}[cc] 0.75 & 0.25 // -0.75 & -0.25 \end{array}$.
    "

{add the description of the COSPI intrinsic}

[359:32+, 16.9.55+]

Add a new sub-subsection 16.9.55+:

    "
    COSPI (X)
    Description. Circular cosine function.
    Class. Elemental function.
    Argument. X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics. Same as X.
    Result Value. The result has a value equal to a processor-dependent
    approximation to cos(X * pi).
    Example. COSPI (1.0) has the value -1.0 (approximately).
    "

{add the description of the SINPI intrinsic}

[416:26+, 16.9.178+]

Add a new sub-subsection 16.9.178+:

    "
    SINPI (X)
    Description. Circular sine function.
    Class. Elemental function.
    Argument. X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics. Same as X.
    Result Value. The result has a value equal to a processor-dependent
    approximation to sin(X * pi).
    Example. SINPI (1.0) has the value 0.0 (approximately).
    "

{add the description of the TANPI intrinsic}

[420:37+, 16.9.188+]

Add a new sub-subsection 16.9.188+:

    "
    TANPI (X)
    Description. Circular tangent function.
    Class. Elemental function.
    Argument. X shall be of type real, regarded as a value in
    half-revolutions.
    Result Characteristics. Same as X.
    Result Value. The result has a value equal to a processor-dependent
    approximation to tan(X * pi).
    Example. TANPI (1.0) has the value 0.0 (approximately).
    "

==END==