Add `angle` function for `stdlib_math`: Return the angle of the complex argument.

[zoziha]

Description

angle computes the phase angle of complex scalar in the interval [-π,π]. The angles in theta are such that z = abs(z)*exp((0.0, theta)).

theta = [[stdlib_math(module):angle(interface) (z)  !! z: `complex` type

Inspired by forlab/angle(MIT license), has been implemented in this branch (add_angle and add_arg) (PR will be made later.)

Prior Art

1. forlab/angle
2. matlab/angle
3. numpy/angle

[arjenmarkus]

Mathematically speaking, this is the argument of the complex number - https://mathworld.wolfram.com/ComplexArgument.html. A more appropriate name, in my view, despite the prior art you included, is arg. Op do 19 aug. 2021 om 13:15 schreef zoziha ***@***.***>:

…

*Description* angle computes the phase angle of complex scalar in the interval [-π,π]. The angles in theta are such that z = abs(z)*exp((0.0, theta)). theta = [[stdlib_math(module):angle(interface) (z) !! z: `complex` type Inspired by forlab/angle(MIT license), has been implemented in this branch (add_angle <fortran-fans/stdlib@5976bb8> ) *Prior Art* 1. forlab/angle <https://github.com/keurfonluu/Forlab/blob/62b80c031fe5f283e6696be0353c13f4ba5886de/src/lib/forlab.f90#L697~L734> 2. matlab/angle <https://ww2.mathworks.cn/help/matlab/ref/angle.html?lang=en> 3. numpy/angle <https://numpy.org/doc/stable/reference/generated/numpy.angle.html> — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#489>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6YR7J4GGBXO2OCCUXI43T5TRVDANCNFSM5CN72FPA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

[nshaffer]

Linking a related issue on math utility functions where this was mentioned: #150

There I suggested the name "phase", but "angle" is OK too. Arjen's suggestion of "arg" works as well if we are not concerned about that name clashing with general programming usage.

Many compilers include trigonometric functions that work with degrees instead of radians, usually named "sind", "atand", etc. These are extensions, but they on the workplan for the next standard (202x), in addition to "pi" trig functions that work with angles in radians in multiples of pi. Let's keep that in mind, so that when these are standardized, we can consider "argd" and "argpi" functions as well. That is, I suggest we not follow numpy's example with the optional "deg" argument.

I do not have the time to implement this right now, but I would be happy to review it when a PR is ready.

[milancurcic]

I don't work with complex numbers often, though this seems useful. I like phase, angle, and arg about equally.

[arjenmarkus]

I like phase because it relates to the use of complex numbers in physics, arg because it is the mathematical term, but I associate angle more with the angle between vectors or lines. I suppose I can live with all three :). Op do 19 aug. 2021 om 18:50 schreef Milan Curcic ***@***.***>:

…

I don't work with complex numbers often, though this seems useful. I like phase, angle, and arg about equally. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#489 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAN6YR4JSMEOZKKSQX4IRDTT5UY7BANCNFSM5CN72FPA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email> .

[zoziha]

From the user's point of view, angle has been named by matlab/numpy, and naming angle seems to be more acceptable.

Mathematically speaking, this is the argument of the complex number

Arjen's suggestion of "arg" works as well if we are not concerned about that name clashing with general programming usage.

arg may indeed conflict with command line arguments (general programming field), and indeed the argument is a mathematical term.

I suggest we not follow numpy's example with the optional "deg" argument.

Matlab.angle has no optional deg parameter, and numpy.angle has an optional deg parameter.
So does our stdlib.angle need an optional deg?

[zoziha]

Hello, I implemented the arg/argd/argpi functions under this branch : add_arg, referring to the Fortran202X feature.

(see 19-203r1.txt and 19-204r1.txt)

I have introduced three precision PI constants in stdlib_math (see PI constant definition). I don't know if it is appropriate to write this way.

#:for k1 in REAL_KINDS
    real(kind=${k1}$), parameter :: PI_${k1}$ = 4.0_${k1}$*atan(1.0_${k1}$)
#:endfor

If there are no major problems, I will submit a PR later.