[Numpy-discussion] Proposal for changing the names of inverse trigonometrical/hyperbolic functions

[Francesc Alted]

Hi,

After dealing with another issue, I realized that the names of inverse
trigonometrical/hyperbolic functions in NumPy don't follow the main
standards in computer science. For example, where Python writes:

asin, acos, atan, asinh, acosh, atanh

NumPy choose:

arcsin, arccos, arctan, arcsinh, arccosh, arctanh

And not only Python, the former also seems to be the standard in
computer science. Quoting:

http://en.wikipedia.org/wiki/Inverse_hyperbolic_function

"""
The usual abbreviations for them in mathematics are arsinh, arcsinh (in
the USA) or asinh (in computer science).
...
The acronyms arcsinh, arccosh etc. are commonly used, even though they
are misnomers, since the prefix arc is the abbreviation for arcus,
while the prefix ar stands for area.
"""

So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.

What people think?

[Eric Firing]

Post by Francesc Alted
Hi,
After dealing with another issue, I realized that the names of inverse
trigonometrical/hyperbolic functions in NumPy don't follow the main
asin, acos, atan, asinh, acosh, atanh
arcsin, arccos, arctan, arcsinh, arccosh, arctanh
And not only Python, the former also seems to be the standard in
http://en.wikipedia.org/wiki/Inverse_hyperbolic_function
"""
The usual abbreviations for them in mathematics are arsinh, arcsinh (in
the USA) or asinh (in computer science).
...
The acronyms arcsinh, arccosh etc. are commonly used, even though they
are misnomers, since the prefix arc is the abbreviation for arcus,
while the prefix ar stands for area.
"""
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1
I have stumbled over this myself. If there is resistance to removing
the old names, then just leave them as synonyms; but definitely numpy
should have asin etc.

Eric

[Jon Wright]

Post by Eric Firing

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix.

+1
I have stumbled over this myself. If there is resistance to removing

-1

There is resistance. Please don't remove the old names. Also note that
your proposed change will alter people's code in subtle, but potentially

Post by Eric Firing

Post by Francesc Alted

from math import *
from numpy import *
type(arcsin(1)) is type(asin(1))

False

Post by Eric Firing

Post by Francesc Alted

from numpy import arcsin as transformacion_del_arco_seno
arcsin == transformacion_del_arco_seno

True

asin(1j) raises an exception, arcsin doesn't. They are *different*
functions, hence the names.

I have the feeling the only times I ever write to this list is to say
"please don't change the API". So, here I am again, "please don't change
the API". This is a cosmetic change whose only effect seems to be to
have everyone change their code, and then support multiple incompatible
numpy versions.

Thanks,

Jon

[Robert Kern]

Post by Jon Wright
I have the feeling the only times I ever write to this list is to say
"please don't change the API". So, here I am again, "please don't change
the API". This is a cosmetic change whose only effect seems to be to
have everyone change their code, and then support multiple incompatible
numpy versions.

I agree. -1.

[Gabriel Gellner]

Post by Jon Wright
There is resistance. Please don't remove the old names. Also note that
your proposed change will alter people's code in subtle, but potentially

from math import *
from numpy import *
type(arcsin(1)) is type(asin(1))

False

from numpy import arcsin as transformacion_del_arco_seno
arcsin == transformacion_del_arco_seno

True
asin(1j) raises an exception, arcsin doesn't. They are *different*
functions, hence the names.

type(np.sin(1)) == type(math.sin(1))

False

And they have the same name. Isn't this what name spaces are for? I think it is
strange that some of the math functions have the same name, and some don't. I
can't see how being different functions justifies this, or we need to rename
the normal trig functions.

I can see not wanting to break API compatibility but I don't find the
`different functions` argument compelling.

Gabriel

[David Warde-Farley]

Post by Gabriel Gellner

Post by Jon Wright
asin(1j) raises an exception, arcsin doesn't. They are *different*
functions, hence the names.

type(np.sin(1)) == type(math.sin(1))

False

In fact, this goes for every single function listed in the math
module's docs, except for the somewhat useless pow(). *Every* other
function in math has a corresponding numpy ufunc with the exact same
name. So, no, I don't think that's a compelling argument either.

Post by Gabriel Gellner
And they have the same name. Isn't this what name spaces are for? I think it is
strange that some of the math functions have the same name, and some don't. I
can't see how being different functions justifies this, or we need to rename
the normal trig functions.
I can see not wanting to break API compatibility but I don't find the
`different functions` argument compelling.

+1. Mixing np.foo and math.foo calls is kind of a recipe for disaster
in the general case, I would think.

David

[Charles R Harris]

Post by David Warde-Farley

Post by Gabriel Gellner

Post by Jon Wright
asin(1j) raises an exception, arcsin doesn't. They are *different*
functions, hence the names.

type(np.sin(1)) == type(math.sin(1))

False

In fact, this goes for every single function listed in the math
module's docs, except for the somewhat useless pow(). *Every* other
function in math has a corresponding numpy ufunc with the exact same
name. So, no, I don't think that's a compelling argument either.

Post by Gabriel Gellner
And they have the same name. Isn't this what name spaces are for? I think it is
strange that some of the math functions have the same name, and some don't. I
can't see how being different functions justifies this, or we need to rename
the normal trig functions.
I can see not wanting to break API compatibility but I don't find the
`different functions` argument compelling.

+1. Mixing np.foo and math.foo calls is kind of a recipe for disaster
in the general case, I would think.

Yes, but many folks will do it for quick and dirty ease. I also don't see
why we need to deprecate the old names, just leave them in there. To add new
names like this, just copy copy the old ufunc definition in the generator
and change "arcsin" to "asin".

I think the currently deprecated C-API functions should also remain with
their warnings. They only amount to about a hundred lines of code.

That said, I'm 0- on this at the moment.

Chuck

[Gael Varoquaux]

Post by Jon Wright
There is resistance. Please don't remove the old names. Also note that
your proposed change will alter people's code in subtle, but potentially

from math import *
from numpy import *
type(arcsin(1)) is type(asin(1))

False

from numpy import arcsin as transformacion_del_arco_seno
arcsin == transformacion_del_arco_seno

True

"from foo import *" is really bad. I used to think it wasn't that bad,
but I came to realize over the years that it did nothing more than cause
confusion (like the one above), and that the cost was very small.

Maybe it is just that I have lost contact with basic users...

Post by Jon Wright
I have the feeling the only times I ever write to this list is to say
"please don't change the API". So, here I am again, "please don't change
the API".

I understand your point, and it is very valid. I am +0 on that ("+"
because I favor consistency, "0" because as you point out, this is bad).

Gaël

[Joshua Lippai]

I agree with Jon here. I can see plenty of motivation for adding the
names asin, etc., but there really isn't a need to remove the current
versions, and it will just introduce compatibility issues when someone
tries to run code written with NumPy 1.x using a NumPy 2.x
installation for even the simplest scripts. We wouldn't exactly
wasting tons of space by keeping both in. So as the suggestion stands,
-1.

Josh

Post by Jon Wright
This is a cosmetic change whose only effect seems to be to
have everyone change their code, and then support multiple incompatible
numpy versions.
Thanks,
Jon
_______________________________________________
Numpy-discussion mailing list
http://projects.scipy.org/mailman/listinfo/numpy-discussion

[Gabriel Gellner]

Post by Francesc Alted
Hi,
After dealing with another issue, I realized that the names of inverse
trigonometrical/hyperbolic functions in NumPy don't follow the main
asin, acos, atan, asinh, acosh, atanh
arcsin, arccos, arctan, arcsinh, arccosh, arctanh
And not only Python, the former also seems to be the standard in
http://en.wikipedia.org/wiki/Inverse_hyperbolic_function
"""
The usual abbreviations for them in mathematics are arsinh, arcsinh (in
the USA) or asinh (in computer science).
...
The acronyms arcsinh, arccosh etc. are commonly used, even though they
are misnomers, since the prefix arc is the abbreviation for arcus,
while the prefix ar stands for area.
"""
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1

Gabriel

[Travis E. Oliphant]

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1

-Travis

[Jarrod Millman]

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1
It seems there is a fair amount of favor for adding the new names.
There is some resistance to removing the old ones. I would be happy
to deprecate the old ones, but leave them in until we release a new
major release (i.e., NumPy 2.0.0). We could start creating a list of
API/ABI clean-ups for whenever we find a compelling reason to release
a new major version. In the meantime, we can leave the old names in
and just add a deprecation note to the docs. Once we are ready to
release 2.0, we can release a 1.x with deprecation warnings.

[Charles R Harris]

Post by Jarrod Millman

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1
It seems there is a fair amount of favor for adding the new names.
There is some resistance to removing the old ones. I would be happy
to deprecate the old ones, but leave them in until we release a new
major release (i.e., NumPy 2.0.0). We could start creating a list of
API/ABI clean-ups for whenever we find a compelling reason to release
a new major version. In the meantime, we can leave the old names in
and just add a deprecation note to the docs. Once we are ready to
release 2.0, we can release a 1.x with deprecation warnings.

This still leaves some incompatibilities; code written with the new
functions won't run on older releases of numpy so folks who need portability
will have to use the old names. Note that most Linux distros lag a good ways
behind the latest and greatest numpy. I say to wait for a major release to
add the new names and just leave the old ones alone. This all recalls the
hassle of going through all my old code changing from
Numeric->Numarray->Numpy. It wasn't difficult but it did consume time.

Chuck

[Charles R Harris]

Post by Charles R Harris

Post by Jarrod Millman

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1
It seems there is a fair amount of favor for adding the new names.
There is some resistance to removing the old ones. I would be happy
to deprecate the old ones, but leave them in until we release a new
major release (i.e., NumPy 2.0.0). We could start creating a list of
API/ABI clean-ups for whenever we find a compelling reason to release
a new major version. In the meantime, we can leave the old names in
and just add a deprecation note to the docs. Once we are ready to
release 2.0, we can release a 1.x with deprecation warnings.

This still leaves some incompatibilities; code written with the new
functions won't run on older releases of numpy so folks who need portability
will have to use the old names. Note that most Linux distros lag a good ways
behind the latest and greatest numpy. I say to wait for a major release to
add the new names and just leave the old ones alone. This all recalls the
hassle of going through all my old code changing from
Numeric->Numarray->Numpy. It wasn't difficult but it did consume time.

Maybe we could push all the changes off to a Numpy release compatible with
Python 3.0. Folks will expect a certain amount of hassle when making that
switch.

Re portability: remember how much trouble it was making Numpy work on Python
2.3 after we used features introduced in later versions?

Chuck

[Matthew Brett]

Hi,

I think this change could be confusing.

numpy.asum numpy.arange numpy.amax etc all have the intended meaning
of 'a-for-array-version-of-function'. This obviously isn't the case
for 'acos'. Explaining the difference could be painful.

Best,

Matthew

[Chris Barker]

Post by Matthew Brett
numpy.asum numpy.arange numpy.amax etc all have the intended meaning
of 'a-for-array-version-of-function'. This obviously isn't the case
for 'acos'.

actually, it is, isn't it? a version of math.cos that works for arrays?

But anyway, if we had it to do all over again, I'd never suggest that
anyone use "import *", and I would have called all those numpy.range,
numpy.max, etc.

no, I'm not suggesting that we break the API now....

-Chris
--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R [phone] voice
7600 Sand Point Way NE [phone] fax
Seattle, WA 98115 [phone] main reception

***@noaa.gov

[Robert Kern]

Post by Chris Barker

Post by Matthew Brett
numpy.asum numpy.arange numpy.amax etc all have the intended meaning
of 'a-for-array-version-of-function'. This obviously isn't the case
for 'acos'.

actually, it is, isn't it? a version of math.cos that works for arrays?

No. Not at all. acos() and arccos() are the inverse functions of cos().

[Christopher Barker]

Post by Robert Kern

Post by Chris Barker
actually, it is, isn't it? a version of math.cos that works for arrays?

No. Not at all. acos() and arccos() are the inverse functions of cos().

argg!! total brain freeze there. Can I pretend I never wrote that?

-Chris
--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R [phone] voice
7600 Sand Point Way NE [phone] fax
Seattle, WA 98115 [phone] main reception

***@noaa.gov

[Robert Kern]

Post by Christopher Barker

Post by Robert Kern

Post by Chris Barker
actually, it is, isn't it? a version of math.cos that works for arrays?

No. Not at all. acos() and arccos() are the inverse functions of cos().

argg!! total brain freeze there. Can I pretend I never wrote that?

Sure, but the Google never forgets. :-)

[Robert Kern]

On Mon, Nov 24, 2008 at 17:13, Charles R Harris

Post by Charles R Harris
Maybe we could push all the changes off to a Numpy release compatible with
Python 3.0. Folks will expect a certain amount of hassle when making that
switch.

Guido, et al., have specifically asked that projects not do this if
they can at all avoid it.

[Robert Kern]

On Mon, Nov 24, 2008 at 17:13, Charles R Harris

Post by Charles R Harris
Maybe we could push all the changes off to a Numpy release compatible with
Python 3.0. Folks will expect a certain amount of hassle when making that
switch.

Guido, et al., have specifically asked that projects not do this if
they can at all avoid it.

[Robert Kern]

On Mon, Nov 24, 2008 at 17:13, Charles R Harris

Post by Charles R Harris
Maybe we could push all the changes off to a Numpy release compatible with
Python 3.0. Folks will expect a certain amount of hassle when making that
switch.

Guido, et al., have specifically asked that projects not do this if
they can at all avoid it.

[Francesc Alted]

Post by Jarrod Millman

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse
trigonometric functions from ``arc*`` to ``a*`` prefix. Of course,
in order to do that correctly, one should add the new names and add
a
``DeprecationWarning`` informing that people should start to use
the new names. After two or three NumPy versions, the old function
names can be removed safely.
What people think?

+1
It seems there is a fair amount of favor for adding the new names.
There is some resistance to removing the old ones. I would be happy
to deprecate the old ones, but leave them in until we release a new
major release (i.e., NumPy 2.0.0). We could start creating a list of
API/ABI clean-ups for whenever we find a compelling reason to release
a new major version. In the meantime, we can leave the old names in
and just add a deprecation note to the docs. Once we are ready to
release 2.0, we can release a 1.x with deprecation warnings.

Sounds like a plan. +1 on this. If there are worries about portability
issues, I'd even let the old names in 2.0 (with the deprecation
warning, of course), although if the 1.x series are going to live long
time (say, at least, a year), I don't think this is going to be
necessary.

[Perry Greenfield]

On Mon, Nov 24, 2008 at 10:45 AM, Francesc Alted

Post by Francesc Alted
So, IMHO, I think it would be better to rename the inverse
trigonometric
functions from ``arc*`` to ``a*`` prefix. Of course, in order to do
that correctly, one should add the new names and add a
``DeprecationWarning`` informing that people should start to use the
new names. After two or three NumPy versions, the old function names
can be removed safely.
What people think?

+1
It seems there is a fair amount of favor for adding the new names.
There is some resistance to removing the old ones. I would be happy
to deprecate the old ones, but leave them in until we release a new
major release (i.e., NumPy 2.0.0). We could start creating a list of
API/ABI clean-ups for whenever we find a compelling reason to release
a new major version. In the meantime, we can leave the old names in
and just add a deprecation note to the docs. Once we are ready to
release 2.0, we can release a 1.x with deprecation warnings.

I tend to favor this approach.

Perry

[Joris De Ridder]

Post by Francesc Alted
asin, acos, atan, asinh, acosh, atanh
arcsin, arccos, arctan, arcsinh, arccosh, arctanh
So, IMHO, I think it would be better to rename the inverse
trigonometric
functions from ``arc*`` to ``a*`` prefix.

-1

The current slightly deviating (and in fact more clear) naming
convention of Numpy is IMO not even remotely enough reason to break
the API.
Adding honey by introducing a transition period with a deprecation
warning postpones but doesn't avoid breaking the API.

Joris


Disclaimer: http://www.kuleuven.be/cwis/email_disclaimer.htm