API: adjust nD fft s param to array API

[lucascolley]

Towards gh-25076, closes gh-14179, closes scipy/scipy#10569

scipy/scipy#10569 reported that the s parameter of NumPy's nD fft functions behaves differently to the equivalent in scipy.fft. I checked, and there are some changes needed for array API compatibility. This PR adjusts for the following lines of the spec:

If s[i] is -1, the whole input array along the axis i is used (no padding/trimming).

If s is not None, axes must not be None.

---

To be deprecated:

"If s is not None, axes must not be None."

• Current behaviour: axes is allowed to be None

s and axes should be of type Sequence[Int]

• Current behaviour:

• numpy.fft: Undocumented behavior of s argument #14179

New features:

"If s[i] is -1, the whole input array along the axis i is used (no padding/trimming)."

• Current behaviour: ValueError: Invalid number of FFT data points (-1) specified.

[ngoldbaum]

If we want to do this, it needs a release note. It should likely also be mentioned in the array API compat notes in the docs. Also it sounds like the array API tests don't cover this unless our test suite has an exception for it already.

I searched a little and found one real-world usage this would break in a hydrodynamics solver: https://github.com/pencil-code/pencil-code/blob/91ad3991c339fa62cdf5546cea64fac854c2ba9f/python/pencil/math/Helmholtz.py#L99

Perhaps this could be a deprecation?

[lucascolley]

Also it sounds like the array API tests don't cover this unless our test suite has an exception for it already.

https://github.com/numpy/numpy/blob/main/tools/ci/array-api-skips.txt#L36-L37

Apparently the fft tests are all skipped right now due to them being buggy. I assume this is why there aren't any points on gh-25076 for fft yet.

Perhaps this could be a deprecation?

I thought the point was to use 2.0 to make the necessary breaking changes for ~100% compat, but forgive me if I'm out of the loop.

If we want to do this, it needs a release note. It should likely also be mentioned in the array API compat notes in the docs.

Happy to add these if we want to continue here.

[lucascolley]

Also, I didn't look thoroughly at whether these functions need any other changes. If it turns out that you are going to be touching these functions anyway @mtsokol, feel free to take over my PR. I thought this might have just been something which was missed, which would be understandable considering the buggy tests.

[lucascolley]

From community meeting, to-do here:

• add the additional doc lines as per comment above
• For breaking changes, deprecate instead
• For new behaviour which used to give errors, fine to introduce
• also deal with undocumented None behaviour
• add release note

[lucascolley]

What should the deprecation messages say? Mark for removal in 2 release cycles or...?

[ngoldbaum]

The warning should describe the behavior that's deprecated (e.g. "specifying the s parameter without also specifying the axes parameter is deprecated") and suggest an alternative that isn't deprecated if that's possible. You should also leave a comment next to the deprecation saying when it happened and which numpy version it's in. A few numpy deprecations list a specific version the deprecation will expire but it leaves a little more flexibility if you don't specify it. Also make sure the stacklevel is correct given where in the call stack the warning comes from.

An example I found via grep:

fromnumeric.py
2341-
2342-    >>> np.sum([10], initial=5)
2343-    15
2344-    """
2345-    if isinstance(a, _gentype):
2346-        # 2018-02-25, 1.15.0
2347-        warnings.warn(
2348-            "Calling np.sum(generator) is deprecated, and in the future will "
2349-            "give a different result. Use np.sum(np.fromiter(generator)) or "
2350-            "the python sum builtin instead.",
2351:            DeprecationWarning, stacklevel=2
2352-        )

[seberg]

Please make sure to add when the warning was added, like (Deprecated in NumPy 2.0). We don't have a habit of promising an expiration version, since it is hard to predict the future.

[lucascolley]

To be deprecated:

"If s is not None, axes must not be None."

• Current behaviour: axes is allowed to be None

s and axes should be of type Sequence[Int]

• Current behaviour: numpy.fft: Undocumented behavior of s argument #14179

New features:

"If s[i] is -1, the whole input array along the axis i is used (no padding/trimming)."

• Current behaviour: ValueError: Invalid number of FFT data points (-1) specified.

[lucascolley]

Looks like CI is happy, ready for a look @ngoldbaum !

[lucascolley]

I think the doc changes look good, although I need to add deprecation notes for s containing None values.

[ngoldbaum]

Suggested wording change to the above:

Using `numpy.fft.fftn`, `numpy.fft.ifftn`, `numpy.fft.rfftn` and `numpy.fft.irfftn` with the ``s`` parameter set to value that is not `None` and the ``axes`` set to ``None`` has been deprecated, to match the array API standard.

Right now a reader might mistakenly read that the whole function is deprecated, not just this one usage.

If a user has s set to None or passes an array containing None, what should they do now to get the same behavior back?

EDIT: Ah, I see you mention the fix in the warning, just need to also mention it here.

[lucascolley]

I've updated the release notes for your suggestion and also documented the deprecations for (i)fft2, as well as adding tests for those functions.

[lucascolley]

real transforms aren't included since the shapes aren't the same

[ngoldbaum]

Thanks @lucascolley!

[lucascolley]

thanks for the review Nathan and Marten!