numpy.spacing documentation inaccuracies

The current numpy.spacing documentation seems inaccurate. At the top, it says:

Return the distance between x and the nearest adjacent number.

But this isn’t right for powers of 2: for example, if x = 1.0, the nearest representable float to x is 1.0 - 2**-53, so the distance would be 2.**-53. But in this case, spacing gives 2.0**-52.

It’s also not immediately clear from the description what the expected sign of the result is. From experimentation, it looks as though np.spacing(-x) is -np.spacing(x), except in the case of zeros, where the result is the same for both negative and positive zeros.

[mdickinson]

On the sign, having the sign of the result match the sign of the input seems a perfectly reasonable choice; I think it’s potentially valuable that a + np.spacing(a) gives the next-away-from-zero value from a. I’m not suggesting any behaviour change here - even without backwards compatibility concerns it doesn’t seem a clear choice either way (and as you say, with backwards compatibility concerns, it is clear that this shouldn’t be changed).

The -0.0 corner case is a bit surprising, in that it’s the only case where the sign of the result doesn’t match the sign of the input. OTOH, there’s an argument for having -0.0 and 0.0 behave identically in almost all numeric contexts, with a few well-known exceptions. Both behaviours seem reasonable, but again it would be good to document.

For the np.finfo(np.float64).max case, I guess I find this surprising because I don’t think of the output as being a difference so much as being the value of the least significant place in the given float. OTOH, the “spacing” name clearly indicates that this should be thought of as a difference.

But I agree that all the current choices seem reasonable, and that this is really just a documentation issue.

For context, I was looking at this mostly because CPython just implemented math.ulp, with a similar purpose but a slightly different set of choices: https://bugs.python.org/issue39310.

[mattip]

Are the new math.nextafter and math.ulp going to cause us a whole new set of edge-case incompatibilities with the numpy definitions?