Julia: rename `angle` to `phase` (or something else) in 2.0

[ExpandingMan]

The function for efficiently computing the phase of a complex number (on the 0-branch) is currently called angle. This name sounds really weird. phase might be a little more obvious. Note that "arg" is also a pretty traditional name for this function, but arg probably appears a little too often in code for that to be a good idea.

[JeffBezanson]

+1 to phase; I feel like that's what I learned and what it's usually called.

[jaakkor2]

?angle says "Compute the phase angle in radians of a complex number z.". Could well be any of arg, phase, angle, phaseangle.

Randomly changing function names for no practical gain feels counterproductive post Julia v1. And does not help the transition to Julia v2.

+1 to phase; I feel like that's what I learned and what it's usually called.

Hmm. It was defined as arg(z::Complex) = atan2(z.im, z.re) back in 2010 https://github.com/JuliaLang/julia/commit/c42669ae9340a8b0d8299813cc87fe6c933b74d4.

Renamed to angle back in 2011 https://github.com/JuliaLang/julia/commit/448fac7b89ede6d8e556880179b8ec39696cc4b4. So, angle is established now in Julia for more than eight years.

[ExpandingMan]

This would hardly seem like a "random" change. The name angle is just bizarre and nobody will ever be able to find it. I created this issue after looking all over for this function and failing to find it. The first name I checked, and the first or second name most people would check, was phase. Like I said, arg is a pretty standard, well-recognized name for this function, but I suspect the reason it was changed from arg is because the symbol arg is so commonly used in programming. Just because something has been around for 8 years doesn't mean that it was a good idea in the first place.

[jaakkor2]

Is the issue discoverability?

julia> apropos("phase")
Base.angle

[StefanKarpinski]

No need to hash it out now. There are a number of unfortunately generic names exported from Base, this is one of them. We should reconsider them in 2.0 but we don't need to decide now.

[stevengj]

Probably the angle function was so-named because that is what it is called in Matlab and in NumPy. In C++ it is called arg (or Arg in R and Mathematica). Python cmath calls it phase.

In short, there is enough diversity here, and the term angle is sufficiently widely used, that I doubt it is worth changing.

[i-apellaniz]

IMHO, similally to cosd or sind I would also add phased to get the phase in degrees. In the mean time angled would make sense too.

[sgaure]

phase is a term from physical applications of complex numbers. It’s used in electrical engineering, quantum physics, and such.

However, the mathematical term for this quantity is usually «argument». In some undergraduate contexts which depend on visualization it’s called angle (and it certainly was in the first visualization of the complex plane, Caspar Wessel’s in 1797. He was a cartographer and land surveyor).

I suggest that a general programming language avoids adopting language from various applied fields. Most people would certainly be confused if «Vector» in Julia had the meaning it has in e.g. epidemiology. Or if «Complex» was called «Scalar», from some random field like C*-algebras, and «Complex» was from the field of convex geometry, i.e. simplicial complex.

That is, stick to simple mathematics which is common to all applied fields. Call it arg.

[StefanKarpinski]

That’s really not viable given the prevalence of the terms arg and argument in programming and computer science in general.

[brenhinkeller]

PLEASE no breaking changes for non-technical reasons in 2.0.

[brenhinkeller]

Breaking changes that enable, e.g., amazing new AD functionality are one thing; breaking changes because someone likes one name better than another are something completely different.

[timholy]

I don't have a strong opinion on this particular issue, though I do like phase noticeably better than angle.

However, to the chorus of people asking for some kind of block on name changes: programming is fundamentally about concepts and how they interact in the human brain, not how they interact on the processor. If changing a name encourages a significantly more discoverable, accurate, or expansive view of a particular operation, by all means we should do it. I'm not advocating for gratuitous name changes, but some changes are far from irrelevant. How you name stuff matters.

With femtocleaner, name changes are no big deal for code. Docs, blog posts, etc, are much harder to deal with, and that is a genuine cost that we would have to weigh. There should definitely be a bar that a proposed change has to cross, but an outright ban would be crippling.

[brenhinkeller]

All the eloquence in the world is cold comfort to a user who finds their script no longer runs because some developer liked one word better than another.

If the issue is discoverability, I'm very sympathetic to that, but there seem to be better ways of promoting discoverability, as in the apropos suggestion above.

I'm not asking for a "total ban" either, personally, but in this context I would like to highlight that the users who are sufficiently engaged in the community to be able to comment here are also the least likely to struggle with breaking changes. What percent of users do you think know what femtocleaner is? I've maybe heard of it once before, and I've been using Julia near-daily for two years.

[timholy]

It took me 3 months to migrate my 60k lines of private code from 0.6 to 0.7/1.0, and I lived through each 0.0->0.1, 0.1->0.2, 0.2->0.3 transition etc. I used to carve out an entire week of each summer to migrate my code. I know your pain far better than you think.

[brenhinkeller]

I don't doubt it! A lot of lesser mortals would give up under those circumstances though.

[JeffBezanson]

All the eloquence in the world is cold comfort to a user who finds their script no longer runs because some developer liked one word better than another.

I hear you, and we commit to this strictly in 1.x. But to me compatibility is pretty much all-or-nothing: if we make any breaking changes at all, somebody's script will stop working. I suppose we could try to make 2.0 minimally-breaking, but (1) that only sounds good until your script is the one that breaks, and (2) it's questionable whether a "mostly-compatible" release is a worthwhile upgrade at all.

[brenhinkeller]

I appreciate the response. I have to seriously respectfully disagree, however, with idea that compatibility between versions is all-or-nothing; there is a direct quantitative metric for how breaking something is in terms of how many person-hours are required to update to the new syntax.

This particular proposed change is not so bad in terms of person-hours to fix, but the benefit also seems quite slim given that 90% of the issue is one of discoverability, which can be fixed without any breakage.

[timholy]

how many person-hours are required to update to the new syntax.

Suppose for Julia 2.0 there are 15 names that have been proposed for change. Almost everyone agrees that 2 of them are really important, and the other 13 are generally viewed as a net positive but not nearly so clear on their own. Given that femtocleaner can fix 1, 2, 3, or all 15 of them automatically for you with equal ease, is there really a strong case for restricting the list of name changes to just those 2 critical changes?

I'm guessing from your comments you've not been through one of these transitions before? Do you realize that femtocleaner comes with a bot that can automatically go through registered Julia repositories and submit pull requests to make the changes? (It's not available anymore, but was back in the transition days.) If you have unregistered or private repositories, you can still run it manually. Accepting its changes is a single button click. Deeper changes, like "foo! no longer initializes its input array to zero," are far harder to deal with, and the fact that there were so many of them for the 0.6->0.7/1.0 transition was the only reason that it took so long to migrate.

Name changes are the most innocuous form of change, with the exception I mentioned above: old blog/discourse/stackoverflow posts or outdated docs. IMO, any argument against change should focus on that issue, not the difficulty of updating code since femtocleaner makes that nearly trivial.

[brenhinkeller]

Ah, somewhat the opposite -- I was in right in the middle of trying to learn Julia and port my crummy grad school Matlab codes to Julia when the 1.0 transition hit, so my current perspective is a result of being somewhat traumatized by that experience at a formative time. I think that transition was very different if you were "plugged in" to the community at the time than if you were mostly trying to use Julia on your own to do your own things, as I was.

On top of blog posts, etc., I would add: academic publications and their supplementary files! Probably poorly written (but key to the reproducibility of some otherwise-worthwhile piece of science), perhaps just a script, not a package at all, being run years later by someone who knows even less about programming than the author... That's obviously a problem of its own that Julia can't be expected to solve, but also one where I think there can be some harm reduction.

It sounds like 2.0 is much less proximal than I was imagining, so I'm much less worried now, but would still plead to keep opinion-based name changes to a minimum.

[StefanKarpinski]

It would be trivial to have using Julia1 package that exports compatibility aliases (and methods) for Julia 1.x names, which could be used as long as people want to.

[Roger-luo]

FYI, we are using the function phase to represent phase shift gate in Yao: http://docs.yaoquantum.org/dev/man/blocks.html#YaoBlocks.phase-Tuple{Real}. This will make our API very confusing for our users and breaks a lot our user's code (since there will be a conflict in two different generic functions)

[timholy]

somewhat traumatized by that experience at a formative time

Yes, if you were transitioning at that time, it would have been rough. I do feel your pain.

academic publications and their supplementary files!

indeed

I think that transition was very different if you were "plugged in" to the community at the time than if you were mostly trying to use Julia on your own to do your own things, as I was.

The grass is always greener on the other side. Consider that those of us "plugged in" also did much of the work to make the transition happen. There are quite a few of us that donated a person-month or more to fixing public packages, both for our own use but also so that they worked for the larger Julia community (including newbies-at-the-time such as yourself). It sounds like all of us have the scars to prove that these transitions are difficult, yet despite that I'm still arguing we should "do the right thing." Whatever that is :smile:.

But yes, I don't personally see any urgency for 2.0, so I expect that no one needs to be blocking out transition-time on their calendar anytime soon.