Math module - should we rename carg?

[lydia-duncan]

As someone who isn't familiar with this area of math, I have a hard time determining what this function is for based on its name. I believe C stands for complex in this case, but we've typically used it to refer to the C language in other parts of our code, so this overloads the abbreviation. The documentation says it computes the real phase angle of the argument - as a result, I propose renaming this function to phaseAngle, as it is more descriptive of its functionality.

We do inherit this name from C, so programmers familiar with it in that language may expect to use the same name. However, we can make it findable by using that name in our documentation.

[damianmoz]

A complex number x+iy is defined in polar coordinates by its argument (an angle - often called theta) and modulus (or radius often called r). If somebody who is using complex numbers in a program cannot extrapolate the concept of Complex Argument to carg, they need to do more homework. I cannot remember the last time I used the world phase angle.

Functions in languages supporting complex numbers have used the letter c to imply a function pertaining to complex numbers for decades. Untimately the number of C routines called by Chapel will diminish but you will be stuck with complex numbers.

The name carg() was inherited from Fortran. It is at least 44+ years old because it was coded explicitly in L Wayne Fullerton's 1977 version of FNLIB. I think it actually existed before that but I have nobody to ask and have no documentation from before that time to which I can refer.

The same comments as #19010 and #19011 apply here. Sorry, I am going backwards through your list.

I would vote to stick with the original name.

[lydia-duncan]

If somebody who is using complex numbers in a program cannot extrapolate the concept of Complex Argument to carg, they need to do more homework.

But what if they're not using complex numbers? What if they're just looking at options in the Math module?

[lydia-duncan]

Typically, Chapel uses overloading with different argument types rather than including the argument type in the name of a function, because we can handle that where languages like C do not. So you won't often see complex abbreviated at all, Chapel users will be more used to c referring to the language (and c versus c_ seems like a pretty subtle difference to me). Argument is a common word but not in this context (i.e. it is not common in the name of the function, more often being used to refer to arguments to functions), so it made sense to me to provide additional context.

[bradcray]

But what if they're not using complex numbers? What if they're just looking at options in the Math module?

Wouldn't the module documentation tell them what it is/does?

Chapel users will be more used to c referring to the language (and c versus c_ seems like a pretty subtle difference to me).

I hear what you're saying, but am not sure I buy it. For example, I don't think we'd rename cos() simply because of fear that someone would confuse it with a C Operating System call or c_os(). And if the world is accustomed to cos(), I don't think we'd rename it to cosine() simply to make it more self-documenting (though we obviously could if the community sentiment was that it's been an ongoing shame that the world uses sin() and cos()).

My feeling here is that if none of the more modern popular languages since Fortran/C have changed this name, then we shouldn't either.

[bradcray]

Adding one more note on why I don't think we should be concerned about the c_ prefix vs. routines starting with c: All of the c_ symbols are now defined in a library and not used by default (unless we missed something), and I don't think every library should have to worry about potentially causing confusion with every other library in terms of naming.

[lydia-duncan]

It sounds like we're keeping carg

[lydia-duncan]

Based on Damian's comment on the conjg issue (https://github.com/chapel-lang/chapel/issues/19010), we'll take a look at whether to rename this function in the sprint starting August 8th. However, we might run out of time, in which case we may mark it unstable and revisit post 2.0 to determine a better name.

1. What is the API being presented?

  /* Returns the phase (often called `argument`) of complex `x`, an angle (in
     radians).

     In concert with the related :proc:`abs`, the magnitude (a.k.a.
     modulus) of `x`, it can be used to recompute `x`.

     :rtype: ``real(w/2)`` when `x` has a type of ``complex(w)``.
  */

  inline proc carg(x: complex(?w)): real(w/2) { … }

How is it intended to be used?

As stated in the documentation, it can be used to recompute the original complex when combined with the magnitude (obtained via abs). Wikipedia points out that this is used to represent the complex’s polar coordinates in the complex plane (https://en.wikipedia.org/wiki/Complex_number), and that formulas for multiplication, division and exponentiation of complex numbers are simpler using the polar coordinates.

Wikipedia also points out that the argument (phase) can be typically represented by color in domain coloring, while the magnitude is typically represented by brightness.

I’m not an expert on mathematics involving complex numbers, unfortunately, but it seems like there’s utility in determining which complex numbers share a phase angle and thus could be viewed as “in a line” with each other (e.g. the only difference being their magnitude).

The argument (phase) also will change its sign when conjugation is performed on the original complex number.

Complex numbers are used in signal analysis, because they are convenient for describing signals that vary periodically.

How is it being used in Arkouda and CHAMPS?

Not used in Arkouda or CHAMPS, so far as we can tell.

2. What's the history of the feature, if it already exists?


It was added in 2016 along with several other math functions for complex numbers. The PR initially used the name arg for it, but before merging it was renamed to carg to avoid conflicts with arg in other contexts and to match the C name.

Damian helped me improve the documentation for this function when we dealt with abs.

There was some uncertainty about whether we should continue to include it in all programs by default, but upon understanding its role in complex number computations, we decided it was important to continue to include it in all programs.

3. What's the precedent in other languages, if they support it?

a. Python

Python uses the name phase to represent it (https://docs.python.org/3/library/cmath.html#cmath.phase) and refers to “argument” in its definition.

Python also provides a polar function (https://docs.python.org/3/library/cmath.html#cmath.polar) that is equivalent to (abs(x), phase(x)).

It looks like NumPy uses angle instead (https://numpy.org/doc/stable/reference/generated/numpy.angle.html#numpy.angle).

b. C/C++

C/C++ use carg, cargf and cargl for this functionality (where the name varies based on the type of the argument, https://en.cppreference.com/w/c/numeric/complex/carg). We chose our name for this function based on this name.

c. Rust

I’m not seeing an equivalent in Rust.

d. Swift

I’m not seeing an equivalent in Swift.

e. Julia

Julia provides angle (https://docs.julialang.org/en/v1/base/math/#Base.angle)

f. Go

Go doesn’t provide this function in its base support. I see some packages that refer to something along these lines:

• There’s an angle type (https://pkg.go.dev/github.com/splace/angle#section-readme) as part of the splace package (I think), but it doesn’t mention anything specific to complex numbers.
• The complex type in https://pkg.go.dev/github.com/scrouthtv/algobra/pkg/number#Complex provides a polar function which returns the polar coordinates, but I’m not seeing any individual function for the phase angle.
• This package represents a complex using a Number type but I don’t see anything in it about the phase angle (https://pkg.go.dev/github.com/yasteen/go-parse/mathgroups/complex#Number)


4. Are there known Github issues with the feature?

• Was impacted by the recent PR to unify the argument names in this module.

5. Are there features it is related to? What impact would changing or adding this feature have on those other features?

• Strongly related to complex numbers and the abs overload that takes a complex number (which provides the magnitude). Renaming it will not impact those symbols
• Related to cproj and conjg (soon to be renamed to conj) due to being operations on complex numbers. If this function changes its name, it might make sense to also change the name of cproj, but otherwise it shouldn’t impact them.


6. How do you propose to solve the problem?


A. Leave as is

• Pros:
  • Less implementation work (though wouldn’t be much otherwise)
  • Less work for users (though again, wouldn’t be much otherwise)
  • In line with C/C++ name
• Cons:
  • Doesn’t follow our standard module style guide in terms of naming
  • Doesn’t match the name used by Python, NumPy, or Julia
  • “arg” is the least unique way to specify what it is doing and is the term we frequently use when talking about arguments to functions, so could be confused with that.
  • Encodes “complex” in the type name, which is a departure from how we handle most names

B. Rename to cArg

• Pros:
  • Follows standard module style guide for capitalization
  • Close to the C/C++ name, enough that it can be found by searching as long as case is ignored
• Cons:
  • Doesn’t match the name used by Python, NumPy, or Julia
  • “arg” is the least unique way to specify what it is doing and is the term we frequently use when talking about arguments to functions, so could be confused with that.
  • Encodes “complex” in the type name, which is a departure from how we handle most names
    • Arguably, this version is more likely to be confused with “C argument” than the previous, due to the obvious delineation in the words be represented, where “carg” could divide in several other ways.

C. Rename to phase

• Pros:
  • Matches Python’s name for the same functionality
  • More likely to be conceptually unique than “arg” - at least the basic mathematical version is conceptually related
• Cons:
  • Doesn’t match NumPy, C/C++ or Julia’s name
  • If a user is trying to represent the moon or something, it’ll conflict? I dunno that this holds much water for me (badum tish)

D. Rename to angle

• Pros:
  • Matches NumPy and Julia’s name for the same functionality
  • More likely to be conceptually unique than “arg” - at least the basic mathematical version is conceptually related
• Cons:
  • Doesn’t match Python itself or C/C++
  • More likely to conflict or get shadowed by a local variable variable name than “phase” imo.

E. Rename to phaseAngle

• Pros:
  • Includes portions of Python, NumPy, and Julia’s name for the functionality
  • Quite specific and descriptive
  • Long enough that it’s unlikely to conflict with user symbols
• Cons:
  • Doesn’t match the exact name of any other language
  • Long, perhaps unnecessarily so

F. Rename to something else?

G. Mark unstable until we figure out a better name

• Pros:
  • Gives more time to figure out a good name
• Cons:
  • Including an unstable symbol in all user programs by default is not great (but at least the current name is less likely to conflict with anything the user has defined).
  • Might make the 2.0 story for complex numbers feel less complete (though the fact that it’s only present in half the languages surveyed means this might hold less weight)

I think it would be good to open an issue requesting a polar function like Python provides, but that would be a post 2.0 task.

I’d probably rename to phase or phaseAngle, left to my own devices.

[lydia-duncan]

In our discussion today, we decided:

• To rename this function to phase
• To open an issue requesting a polar function like Python provides
• To also open an issue requesting a magnitude function is also provided (see discussion below)

In addition to the options listed in the previous comment, we also considered:

• complexArg
• cplxArg

Discussion:

• Jeremiah: haven't heard "angle" used in engineering references to the term. But does tend to see abs/arg paired and magnitude/phase paired.
• Jade: likes phaseAngle aside from its length.
• Jeremiah: does like having arg paired with abs, but wouldn't use arg as the name by itself. "complex argument" is a reasonable and commonly used phrase. But happy with phase. phaseAngle is too long for such a common operation.
• Jade: has a strong negative reaction to cArg
• Jade: we could add a mag or magnitude function post-2.0, to maintain the pairing Jeremiah was used to with phase.
  • Lydia: mag is probably too short to be included in all user programs by default, but would be open to adding a magnitude function

[lydia-duncan]

Opened #23173 for the polar function and #23174 for the magnitude function. Once carg has been renamed, we can close this issue.