Degree trigonometric functions

[thenlich]

To: J3 J3/18-139r1
From: Steve Lionel @sblionel
Subject: Degree trigonometric functions
Date: 2018-February-16

Many if not most Fortran implementations support, as extensions,
degree-argument (or return value) versions of some of the trigonometric
intrinsic functions, and these are widely used. In the spirit of
standardizing existing practice, we should add the following generic
intrinsic functions to the standard:

• ACOSD
• ASIND
• ATAN2D
• ATAND
• COSD
• SIND
• TAND

All of these would be similar to their radian counterparts
except that the argument(s) or return values would be in degrees.

During J3 discussion it was noted:

• The hyperbolic functions (COSH, SINH, etc.) do not use radians and
  therefore need no degree equivalents.
• While ATAN2 is effectively replaced by the two-argument form of
  ATAN, it was felt appropriate to include ATAN2D in support of
  existing practice.

[thenlich]

To: J3 J3/18-272r1
From: Lorri Menard
Subject: Degree trigonometric functions
Date: 2018-October-17
Reference: m215/18-139r1

I Introduction
[...]

II Use cases

This provides a portable mechanism for programs that have
mathematical formulas that need the actual degrees.

III What I have in mind

First, the prevailing principle is that only generic functions
are to be added, even if some vendors (ahem) may have provided
specific versions.

[...]

Finally, add the generic intrinsics listed above.

[thenlich]

To: J3 J3/19-203r1
From: Tom Knox
Subject: Degree trigonometric functions (US04)
Date: 2019-August-07
Reference: 19-145r2, 18-007r1

1 Introduction

Addition of the degree trigonometric functions was given specifications
in m218, during which 19-145r2 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 in degrees.

3 Syntax

ACOSD (X)
Description: Arccosine (inverse cosine) function in degrees.
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). The result is expressed in degrees
and lies in the range of 0 to 180 (inclusive).

ASIND (X)
Description: Arcsine (inverse sine) function in degrees.
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). The result is expressed in degrees
and lies in the range -90 to 90 (inclusive).  


ATAND (X) or ATAND (Y,X) 
Description: Arctangent (inverse tangent) function in degrees.
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
ATAN2D (Y, X). If Y does not appear, the result is expressed in
degrees, with a value equal to a processor-dependent approximation
to arctan(X), and lies in the range -90 to 90 (inclusive).

ATAN2D (Y,X) 
Description: Arctangent (inverse tangent) function in degrees.
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 is expressed in degrees and has a value
equal to a processor-dependent approximation to arctan(Y/X) if
X /= 0; it lies in the range -180 to 180 (inclusive). 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 180 (if
X < zero and Y is positive real zero or the processor does not
distinguish between positive and negative real zero) or approximately
-180 (if Y is negative real zero). If X = zero, the absolute value of
the result is approximately 90.

COSD (X)
Description: Degree cosine function.
Class: Elemental function.
Argument: X shall be of type real, regarded as a value in degrees.
Result Characteristics: Same as X.
Result Value: The result has a value equal to a processor-dependent
approximation to cos(X), where X is expressed in degrees.

SIND (X)
Description: Degree sine function.
Class: Elemental function.
Argument: X shall be of type real, regarded as a value in degrees.
Result Characteristics: Same as X.
Result Value: The result has a value equal to a processor-dependent
approximation to sin(X), where X is expressed in degrees.

TAND (X)
Description: Degree tangent function.
Class: Elemental function.
Argument: X shall be of type real, regarded as a value in degrees.
Result Characteristics: Same as X.
Result Value: The result has a value equal to a processor-dependent
approximation to tan(X), where X is expressed in degrees.

4 Edits to 18-007r1
[...]
Example. ACOSD (-1.0) has the value 180.0 (approximately).
[...]
Example. ASIND (1.0) has the value 90.0 (approximately).
[...]
Example. ATAND (1.0) has the value 45.0 (approximately).
[...]
Example. ATAN2D (1.0, 1.0) has the value 45.0 (approximately). If Y has the value [1 1; -1 -1] and X has the value [-1 1; -1 1], the value of ATAN2D (Y, X) is approximately [135.0 45.0; -135.0 -45.0].
[...]
Example. COSD (180.0) has the value -1.0 (approximately).
[...]
Example. SIND (180.0) has the value 0.0 (approximately).
[...]
Example. TAND (180.0) has the value 0.0 (approximately).

[thenlich]

A logical next step would be to add conversion functions between degrees and radians to the standard. Usual function names are: rad2deg, deg, degrees; deg2rad, rad, radians.

Use case: Often it is necessary to use angles in radians in calculation, e.g. to calculate arc length of a unit circle. Example: the involute function inv(x) = tan(x) - x.

Correctly rounded multiplication by arbitrary precision constants (π/180) or (180/π) is non-trivial.

DEGREES (X)
Description: Radians to degrees conversion function.
Class: Elemental function.
Argument: X shall be of type real, regarded as a value in radians.
Result Characteristics: Same as X.
Result Value: The result has a value equal to a processor-dependent
approximation to X, where X is expressed in degrees.

RADIANS (X)
Description: Degrees to radians conversion function.
Class: Elemental function.
Argument: X shall be of type real, regarded as a value in degrees.
Result Characteristics: Same as X.
Result Value: The result has a value equal to a processor-dependent
approximation to X, where X is expressed in radians.

4 Edits
[...]
Example. DEGREES (3.141593) has the value 180.0 (approximately).
[...]
Example. RADIANS (-360.0) has the value -6.283185 (approximately).

TODO

RADIANS(): define additional (optional) parameters

• (intent: in) to control range reduction to -360°...360°; 0°...360°; -180°...180°; 0°...45° etc.
• (intent: out) to inform about in which 90° or 45° sector the angle lies.

[certik]

Alternatively these conversion functions can go into stdlib.

…

On Wed, Mar 4, 2020, at 6:41 AM, Thomas Henlich wrote: A logical next step would be to add conversion functions between degrees and radians to the standard. Usual function names are: deg2rad, deg, degrees; rad2deg, rad, radians. Use case: Often it is necessary to use angles in radians in calculation, e.g. to calculate arc length of a unit circle. Example: the involute function inv(x) = tan(x) - x. Correctly rounded multiplication by arbitrary precision constants <http://perso.ens-lyon.fr/jean-michel.muller/MultConstant.html> (π/180) or (180/π) is non-trivial. `DEGREES (X) Description: Radians to degrees conversion function. Class: Elemental function. Argument: X shall be of type real, regarded as a value in radians. Result Characteristics: Same as X. Result Value: The result has a value equal to a processor-dependent approximation to X, where X is expressed in degrees. RADIANS (X) Description: Degrees to radians conversion function. Class: Elemental function. Argument: X shall be of type real, regarded as a value in degrees. Result Characteristics: Same as X. Result Value: The result has a value equal to a processor-dependent approximation to X, where X is expressed in radians. ` 4 Edits [...] Example. DEGREES (3.141593) has the value 180.0 (approximately). [...] Example. RADIANS (-360.0) has the value -6.283185 (approximately). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#164?email_source=notifications&email_token=AAAFAWAUW2GOL5JSWPL4DNDRFZK6ZA5CNFSM4K72DTD2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOENX4ULI#issuecomment-594528813>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWEAWF2PSLZRLI5RV6LRFZK6ZANCNFSM4K72DTDQ>.

[klausler]

As another alternative: intrinsic functions that provide multiplication and division by a constant of a distinct (more precise) kind of REAL, returning a result of the kind of the not-necessarily-constant argument. Then DEGREES(x) = DIVBY(180 * x, 3.141592653589793238462643383279503E0_16).

[thenlich]

The Fortran standard is not concerned where or how these functions would be implemented (the word "processor-dependent" is used a lot there), just with what they should do, and how they would be used in a standard-conforming program.