search

j3-fortran / fortran_proposals

Proposals for the Fortran Standard Committee
178 stars 15 forks source link

Degree trigonometric functions #164

Open thenlich opened 4 years ago

thenlich commented 4 years ago

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:

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:

thenlich commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

certik commented 4 years ago

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 https://github.com/j3-fortran/fortran_proposals/issues/164?email_source=notifications&email_token=AAAFAWAUW2GOL5JSWPL4DNDRFZK6ZA5CNFSM4K72DTD2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOENX4ULI#issuecomment-594528813, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAFAWEAWF2PSLZRLI5RV6LRFZK6ZANCNFSM4K72DTDQ.

klausler commented 4 years ago

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 commented 4 years ago

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.