This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Type: Add math.nextafter(a, b) resolved Library (Lib) Python 3.9
process
Status: Resolution: closed fixed lemburg, mark.dickinson, rhettinger, steven.daprano, stutzbach, tim.peters, vstinner normal 3.3regression, patch

Created on 2020-01-10 15:51 by vstinner, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
PR 17937 merged vstinner, 2020-01-10 15:53
PR 17962 merged vstinner, 2020-01-12 09:34
Messages (18)
msg359731 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-10 15:51
```Linux manual page of nextafter():
"""
The nextafter() function return the next representable floating-point  value following x in the direction of y.  If y is less than x, these functions will return the largest representable number less than x.

If x equals y, the functions return y.
"""

I used this function to round an integer towards zero when casting a float to an integer in bpo-39277. Example in C:

#include <math.h>
#include <stdio.h>
#include <stdint.h>
int main()
{
int64_t int64_max = 9223372036854775807LL;
double d = (double)int64_max;  /* ROUND_HALF_EVEN */
double d2 = nextafter(d, 0.0);
printf("i = %ld\n", int64_max);
printf("d = %.0f\n", d);
printf("d2 = %.0f\n", d2);
printf("d - d2 = %.0f\n", d - d2);
return 0;
}

Output:

i = 9223372036854775807
d = 9223372036854775808
d2 = 9223372036854774784
d - d2 = 1024

The function exists in numpy:

numpy.nextafter(x1, x2, /, out=None, *, where=True, casting='same_kind', order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc 'nextafter'>

Return the next floating-point value after x1 towards x2, element-wise.

https://docs.scipy.org/doc/numpy/reference/generated/numpy.nextafter.html

msg359753 - (view) Author: Mark Dickinson (mark.dickinson) * Date: 2020-01-10 20:03
```I'm not opposed to some form of this by any means, but I fear there's some bikeshedding to go through, both on the name and the functionality (one function with two arguments, or two functions each taking a single argument?).

C 99 prescribes "nextafter" and "nexttoward" (which is pretty much the same as "nextafter" if you don't care about the distinction between float, double and long double).

IEEE 754, on the other hand, requires instead nextUp and nextDown, which take a single argument and move towards +inf or -inf (respectively).

Python's Decimal type has a two-argument next_toward method.

NumPy has nextafter.

Java provides all three of nextUp, nextDown and nextAfter.

For sure implementing nextafter is easiest, since we can just wrap the C version. That doesn't *necessarily* make it the right variant to go for.

(Annoyingly enough, none of these is actually what I tend to want in practice, which is "next larger" and "next smaller" functions, or more precisely, nextAwayFromZero and nextTowardsZero functions. nextTowardsZero is of course a special case of nextafter, but nextAwayFromZero doesn't match any of these.)```
msg359771 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-11 00:43
```> NumPy has nextafter.

That's why I proposed math.nextafter() name.

Moreover, in the math module, most functions reuse the same names than C function names: expm1(), atan2(), erf(), etc.

> IEEE 754, on the other hand, requires instead nextUp and nextDown, which take a single argument and move towards +inf or -inf (respectively).

When I played with bpo-39277, I used nextafter() to try to implement manually a conversion from an integer to a float using rounding towards zero. So I prefer nextafter() than nextUp()/nextDown(): it gives more features.

> but nextAwayFromZero doesn't match any of these

It seems easy to reimplement it using nextafter(), no?

def nextAwayFromZero(x):
if x < 0:
return math.nextafter(x, -float("inf"))
else:
return math.nextafter(x, +float("inf"))

> Python's Decimal type has a two-argument next_toward method.

It also has next_minus() and next_plus() which don't match "nextUp and nextDown" names requires by IEEE 754.

I'm not comfortable with math.next_after() or math.next_toward() name: use a different than the libc function name (add an underscore). For me, the math module is a thin wrapper to libm function, as the os module is a thin wrapper to libc functions.```
msg359775 - (view) Author: Tim Peters (tim.peters) * Date: 2020-01-11 02:42
```No doubt that something along these lines would be useful.

`nextafter()` is too widely implemented to fight against, despite the sucky name ;-)

I believe the rest should be straightforward (for those who want them) to do with one-liners, so there's not much of a case for building them in.  Or is that wrong?  My guesses for correct implementations:

def nextUp(x):
return math.nextafter(x, math.inf)

def nextDown(x):
return math.nextafter(x, -math.inf)

def nextAwayFromZero(x):
return math.nextafter(x, math.copysign(math.inf, x))

That last assumes you want -0 and +0 to act differently; i.e., want

nextAwayFromZero(0.0) == 5e-324
and
nextAwayFromZero(-0.0) == -5e-324```
msg359779 - (view) Author: Steven D'Aprano (steven.daprano) * Date: 2020-01-11 05:32
```I agree, "nextafter" is so widely used it's probably pointless to fight against the name :-)

Mark: "IEEE 754, on the other hand, requires instead nextUp and nextDown".

I know Wikipedia isn't a primary source, but it says IEEE 754 recommends nextafter(x, y).

My understanding of IEEE-754 is that the functionality is required, not the specific API. That is, it's not required to have literally two functions called "nextUp" and "nextDown", so long as you can get the next larger and next smaller float.

I think the second argument should also be optional, so that nextafter(x) returns the next representable float.```
msg359780 - (view) Author: Tim Peters (tim.peters) * Date: 2020-01-11 05:45
```[Steven]
> I think the second argument should also be optional, so
> that nextafter(x) returns the next representable float.

That's why the name sucks - there are, in general, two adjacent floats, so "next" is ambiguous.  I expect you intend that y default to math.inf, which would make one-argument `nextafter(x)` a spelling of `nextUp(x)`.  Fine by me!  That's probably the one I want most often.```
msg359800 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-11 15:35
```PR 17937 is ready to be reviewed. The tests passed on the regular CIs and buildbots: good.

> That last assumes you want -0 and +0 to act differently

It is the case: I wrote an unit test checking exactly that, and it works as expected on all platforms (Windows, macOS, Linux, Intel, PPC, etc.).

> `nextafter()` is too widely implemented to fight against, despite the sucky name ;-)

nexttoward name is less ambiguous, but as you all said: "nextafter" name is way more popular. Honestly, it's not that hard to infer that the function can go "up" or "down" because it has a second parameter. If it's not obvious enough, maybe we can enhance the documentation.

--

About Wikipedia, the following articles are interesting for the ones like me who don't fully understand IEEE 754, rounding mode, etc.

* https://en.wikipedia.org/wiki/Unit_in_the_last_place
* https://en.wikipedia.org/wiki/Machine_epsilon
* https://en.wikipedia.org/wiki/IEEE_754```
msg359802 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-11 15:37
```Oh, I forgot to also give the nextafer() link to the POSIX standard:
https://pubs.opengroup.org/onlinepubs/009695399/functions/nextafter.html

It mentions for example "If x== y, y (of the type x) shall be returned" and "If x or y is NaN, a NaN shall be returned". It's good to know that it's specified ;-)```
msg359811 - (view) Author: Mark Dickinson (mark.dickinson) * Date: 2020-01-11 17:10
```"nextafter" is fine with me. I just wanted to make sure that we'd considered the options, and weren't choosing nextafter simply because it's the easiest thing to implement.

[Victor]

> It mentions for example "If x== y, y (of the type x) shall be returned" and "If x or y is NaN, a NaN shall be returned". It's good to know that it's specified ;-)

Agreed; it would be good to make sure that we have tests for the behaviour matching the spec, particularly with respect to signed zeros: the first clause here implies nextafter(0.0, -0.0) is -0.0, while nextafter(-0.0, 0.0) is 0.0. I'd also recommend adding tests for nextafter(smallest_normal, 0.0), nextafter(largest_normal, inf), nextafter(inf, 0), and the like.

The C standard isn't 100% clear on what nextafter(-0.0, inf) should be: it could be argued that the "next" representable float after -0.0 in the direction of infinity is 0.0. But IEEE 754 is explicit that nextUp(±0) is the smallest positive subnormal, and we should have a test for that, too.

Making the second argument optional sounds reasonable to me, but doesn't necessarily have to happen in the existing PR; we can always add that option later.```
msg359812 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-11 17:28
```Mark:
> Making the second argument optional sounds reasonable to me, but doesn't necessarily have to happen in the existing PR; we can always add that option later.

Do you mean nextafter(x, y=inf, /): toward positive infinity by default? I prefer to keep the second parameter mandatory, to make the direction more explicit. As Tim showed, it's easy to implement nextUp() on top of
nextafter().

> "nextafter" is fine with me.

Good :-) It seems like everybody agrees on nextafter().

> it would be good to make sure that we have tests for the behaviour matching the spec, particularly with respect to signed zeros: the first clause here implies nextafter(0.0, -0.0) is -0.0, while nextafter(-0.0, 0.0) is 0.0.

I had a test for math.nextafter(+0.0, -0.0). I added a test for math.nextafter(-0.0, +0.0).

> I'd also recommend adding tests for nextafter(smallest_normal, 0.0), nextafter(largest_normal, inf), nextafter(inf, 0),

Done.

> and the like.

Feel free to suggest more tests on the PR.

> The C standard isn't 100% clear on what nextafter(-0.0, inf) should be

I added a test for it, for positive and negative zeros.

> But IEEE 754 is explicit that nextUp(±0) is the smallest positive subnormal

That's what I get.```
msg359813 - (view) Author: Mark Dickinson (mark.dickinson) * Date: 2020-01-11 17:30
```[Steven]

> I know Wikipedia isn't a primary source, but it says IEEE 754 recommends nextafter(x, y).

Um. Then it sounds as though Wikipedia is out of date. Which page was this on?

IEEE 754-1985 did recommend nextafter, but only in Annex A, which is not strictly part of the standard. ("This Appendix is not a part of ANSI/IEEE Std 754-1985, IEEE Standard for Binary Floating-Point Arithmetic [...]")

IEEE 754-2008 (section 5.3.1) added nextUp and nextDown as required operations, and the text for those operations is word-for-word identical in the current IEEE 754-2019, save for "sNaNs" being spelled out as "signaling NaNs".

> My understanding of IEEE-754 is that the functionality is required, not the specific API. That is, it's not required to have literally two functions called "nextUp" and "nextDown", so long as you can get the next larger and next smaller float.

Agreed. It's not really spelled out in the standard exactly what "conformance" would mean, but I agree that providing nextafter should be sufficient if we want to claim that Python supports the nextUp and nextDown operations.

Not that Python makes any claim to conform with IEEE 754 anyway, but I think it's still a useful standard to consider when we're choosing what to do in the math module.

I guess if we *wanted* to claim strict conformance with IEEE 754 (which we don't, right now), we'd probably also want to add a note in the docs explaining how nextUp and nextDown are represented in terms of nextafter. But that seems a bit redundant to me.```
msg359814 - (view) Author: Mark Dickinson (mark.dickinson) * Date: 2020-01-11 17:33
```> Do you mean nextafter(x, y=inf, /): toward positive infinity by default?

Yes; I believe that was what Steven was suggesting in the last part of msg359779. I don't have strong feelings either way.```
msg359826 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-12 01:15
```New changeset 100fafcf20e8fc67cd8ef512074f9c0a253cb427 by Victor Stinner in branch 'master':
https://github.com/python/cpython/commit/100fafcf20e8fc67cd8ef512074f9c0a253cb427
```
msg359827 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-12 01:21
```I chose to make y mandatory in nextafter(x, y). Implement your own flavor if nextUp(x) if you want to omit y. I prefer to make y explicit, becauseit has been said in this discussion that "nextafter" name is ambiguous.

Thanks all for the constructive discussion. I merged my PR reviewed by Mark. Enjoy IEEE 754 and have fun with rounding!```
msg359828 - (view) Author: Raymond Hettinger (rhettinger) * Date: 2020-01-12 01:38
`I suggest "next_after" instead of "nextafter".`
msg359838 - (view) Author: Mark Dickinson (mark.dickinson) * Date: 2020-01-12 10:32
```> I suggest "next_after" instead of "nextafter".

"nextafter" gives us consistency with C, with NumPy and with other compound names in the math module ("isnan", "isclose", "copysign"). My own brain doesn't perceive either of "nextafter" or "next_after" as more readable than the other.

What's the argument for "next_after"?```
msg359845 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-12 11:57
```New changeset 54cfbb2feee1f7328c3d6799ec3734b00824b555 by Victor Stinner in branch 'master':
bpo-39288: Add examples to math.nextafter() documentation (GH-17962)
https://github.com/python/cpython/commit/54cfbb2feee1f7328c3d6799ec3734b00824b555
```
msg359854 - (view) Author: STINNER Victor (vstinner) * Date: 2020-01-12 16:30
`I created bpo-39310 to propose to add math.ulp(x).`
History
Date User Action Args
2020-01-12 16:30:18vstinnersetmessages: + msg359854
2020-01-12 11:57:51vstinnersetmessages: + msg359845
2020-01-12 10:32:35mark.dickinsonsetmessages: + msg359838
2020-01-12 09:34:51vstinnersetpull_requests: + pull_request17371
2020-01-12 01:38:46rhettingersetmessages: + msg359828
2020-01-12 01:21:08vstinnersetstatus: open -> closed
resolution: fixed
messages: + msg359827

stage: patch review -> resolved
2020-01-12 01:15:50vstinnersetmessages: + msg359826
2020-01-11 17:33:44mark.dickinsonsetmessages: + msg359814
2020-01-11 17:30:37mark.dickinsonsetmessages: + msg359813
2020-01-11 17:28:40vstinnersetmessages: + msg359812
2020-01-11 17:10:04mark.dickinsonsetmessages: + msg359811
2020-01-11 15:37:52vstinnersetmessages: + msg359802
2020-01-11 15:35:26vstinnersetmessages: + msg359800