gh-94906: Support multiple steps in math.nextafter

[matthiasgoergens]

See issue for discussion.

• Issue: Let math.nextafter() compute multiple steps at a time. #94906

[rhettinger]

It would be nice if steps could be negative rather than having to switch the sign of the second argument:

# Current way
nearby = [nextafter(x, -inf, steps=2),
          nextafter(x, -inf, steps=1),
          x,
          nextafter(x, inf, steps=1),
          nextafter(x, inf, steps=2),
]

# Better way
nearby = [nextafter(x, inf, steps=n) for n in (-2, -1, 0, 1, 2)]

[rhettinger]

@mdickinson Please make the final decision on this. I still like the idea and would use it, but if you want to reject it, you have my support.

[matthiasgoergens]

@rhettinger I'd be happy to make negative steps work. I left it out for simplicity, because there are questions about semantics that would need to be resolved:

The most obvious semantics would be for negative steps to move away from the target.

Or are you suggesting that negative steps should be equivalent to negating the target argument? So for example:

nextafter(x, 0.0, -1) == nextafter(x, -0.0, 1)

Should infinity be absorbing, or should going beyond infinity give NaN? The former seems reasonable to me. But I can also come up with arguments for the latter.

Similarly, we have nextafter(x, x, n) == x for all x and all n. (Ignoring that NaNs don't compare with == equality.) Including x=inf.

That's rather different from nextafter(x, -x, -n) for most x and most n.

We could throw a value error for all the weird cases, and allow negative n for the obvious cases only. But that seems like it might be hard to understand for users?

[mdickinson]

Thanks @rhettinger. I'm short of time right now, but I'll take a fresh look at this this weekend.

[mdickinson]

Okay, let's go ahead with this.

Comments: I'm not totally convinced that nextafter is the right place for this functionality - I suspect the real need is to either add or subtract "n" ulps from a given value, while nextafter is doing something more complicated than that (e.g., saturating when it hits the target value). I'd be open to suggestions for alternative spellings for the functionality. (Aside: an obvious extension of this functionality would be the ability to subtract one float from another and get a result expressed in an integer number of ulps.)

But nextafter itself is already a slightly odd beast, in that I don't think the generality of the second argument is valuable - I suspect there are few use-cases that aren't one of next-towards-plus-infinity / next-towards-negative-infinity / next-towards-zero / next-away-from-zero (and that last one isn't even expressible cleanly with nextafter). Maybe that's why IEEE 754 went with nextUp and nextDown instead of following C's nextafter.

It's only recently that we've started assuming that the floating-point format in use by CPython is IEEE 754 binary64, which is what makes the type-punning via a union work. (Note that we're also assuming in this PR that uint64_t and double have matching endianness; in theory that's not guaranteed, but in practice it seems to be a fairly safe assumption. It may be worth a comment in the implementation, though.)

@matthiasgoergens

On negative steps:

The most obvious semantics would be for negative steps to move away from the target.

Agreed, and that's what I'd favour, but I also agree that the semantics aren't obvious. The more I think about it, the more this feels like an argument for having nextdown and nextup instead of nextafter (or even just nextup), where it is obvious what negative steps would mean.

Should infinity be absorbing, or should going beyond infinity give NaN?

Definitely absorbing.

How about we get this in before the beta-1 cutoff and punt on allowing negative steps for now - we can always add those later.

[matthiasgoergens]

@mdickinson Seems all good to me.

(Aside: an obvious extension of this functionality would be the ability to subtract one float from another and get a result expressed in an integer number of ulps.)

We can do that in pure Python and stick it into a (non-standard) library, if there's demand for it?

Even the multiple-steps-nextafter could live in a place that's not the standard library. I only took this PR to show off that you don't need a loop but can use some clever manipulation of the bits instead, not actually because I think this functionality needs to live in the standard library.

How about we get this in before the beta-1 cutoff and punt on allowing negative steps for now - we can always add those later.

Works for me! Is there anything we need to change in this PR for that?

[mdickinson]

This generally looks good to me; a few comments.

[rhettinger]

The feature freeze is fast approaching. Is the ready to be applied? Once the core API is in, it is okay for the docs and tests continue to be tweaked.

[matthiasgoergens]

@rhettinger I implemented the review suggestions.

[matthiasgoergens]

There's a failed check "Tests / Ubunt SSL tests with OpenSSL (1.1.1t)" but it seems to be flaky and nothing to do with this PR. https://github.com/python/cpython/actions/runs/5001023587/jobs/8959184113?pr=103881

[matthiasgoergens]

I noticed that we are supporting hypothesis property based testing now. I added some property tests.

[matthiasgoergens]

Hmm, I don't understand the test failures. They seem unrelated to what I did, but I am not sure. My tests work locally for me.

[mdickinson]

Thanks for the updates; I'll re-review (and look into the bot failure) shortly.

[mdickinson]

@matthiasgoergens

Hmm, I don't understand the test failures. [...]

make patchcheck was failing on a whitespace error (a stray TAB character); I've fixed it in 6527b77.

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @mdickinson for commit 66ef3f9 🤖

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[mdickinson]

Code LGTM; functionality works as expected in manual testing, and the bots seem happy. I'm not going to wait for the buildbots to finish, since that will take all night (literally).