From c51ce801315ab90b81dd2c901363ab62cb421a08 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 11 Dec 2023 17:27:16 -0700 Subject: [PATCH 01/44] Use better wording for the return dtypes for fft functions Fixes #717 --- src/array_api_stubs/_draft/fft.py | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 4a59392d5..a7e587a2f 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -60,7 +60,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -111,7 +111,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -169,7 +169,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -227,7 +227,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -278,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -329,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). Notes ----- @@ -387,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -445,7 +445,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. Notes ----- @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -541,7 +541,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). Notes ----- @@ -552,7 +552,7 @@ def ihfft( def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> array: """ - Returns the discrete Fourier transform sample frequencies. + Computes the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: @@ -573,7 +573,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar Returns ------- out: array - an array of length ``n`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array of length ``n`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- @@ -584,7 +584,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> array: """ - Returns the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). + Computes the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: @@ -607,7 +607,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a Returns ------- out: array - an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array of length ``n//2+1`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- From 1dd9757bb7f98a3a698bd921f41ec77970c89a78 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 11 Dec 2023 18:02:24 -0700 Subject: [PATCH 02/44] Specify the output shapes for fft functions Also cleanup some wording for consistency. This fixes the incorrect output shape for ihfft. Fixes #718. --- src/array_api_stubs/_draft/fft.py | 104 +++++++++++++++--------------- 1 file changed, 52 insertions(+), 52 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index a7e587a2f..c935034fc 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -39,9 +39,9 @@ def fft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -60,7 +60,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -90,9 +90,9 @@ def ifft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -111,7 +111,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -139,14 +139,14 @@ def fftn( x: array input array. Should have a floating-point data type. s: Sequence[int] - size of each transformed axis of the output. If + length of each transformed axis of the output. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -169,7 +169,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -197,14 +197,14 @@ def ifftn( x: array input array. Should have a floating-point data type. s: Sequence[int] - size of each transformed axis of the output. If + length of each transformed axis of the output. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -227,7 +227,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -257,9 +257,9 @@ def rfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -278,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -308,9 +308,9 @@ def irfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array, the input array is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array is trimmed to length ``n//2+1``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -329,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- @@ -357,14 +357,14 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the **input**. If + length of each transformed axis of the **input**. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -387,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -415,14 +415,14 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If + length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If - - ``n`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``n``. - - ``n`` is less than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``n``. + - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -445,7 +445,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Notes ----- @@ -472,9 +472,9 @@ def hfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array, the input array is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array is trimmed to length ``n//2+1``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array axis, the input array axis is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- @@ -520,9 +520,9 @@ def ihfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -541,7 +541,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``m//2 + 1``, where ``m` is ``n` if ``n`` is given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -573,7 +573,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar Returns ------- out: array - an array of length ``n`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. + an array of shape ``(n,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- @@ -607,7 +607,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a Returns ------- out: array - an array of length ``n//2+1`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. + an array of shape ``(n//2+1,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- @@ -635,7 +635,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. + the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. Notes ----- @@ -661,7 +661,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. + the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. Notes ----- From bde524e5f681826ea544b19facdea8c5b6a48bc9 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 11 Dec 2023 18:07:38 -0700 Subject: [PATCH 03/44] Fix typo for rfft return dtype --- src/array_api_stubs/_draft/fft.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index c935034fc..c89bab024 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -329,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- From 1fd3429eb1bfe3a62875404e4e5e45d01873dd3f Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 13 Dec 2023 21:01:22 -0800 Subject: [PATCH 04/44] Add specification for computing the cumulative sum PR-URL: https://github.com/data-apis/array-api/pull/653 --- .../statistical_functions.rst | 1 + .../_draft/statistical_functions.py | 60 ++++++++++++++++++- 2 files changed, 60 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/statistical_functions.rst b/spec/draft/API_specification/statistical_functions.rst index 23cd2cb1d..20e02b3f9 100644 --- a/spec/draft/API_specification/statistical_functions.rst +++ b/spec/draft/API_specification/statistical_functions.rst @@ -18,6 +18,7 @@ Objects in API :toctree: generated :template: method.rst + cumulative_sum max mean min diff --git a/src/array_api_stubs/_draft/statistical_functions.py b/src/array_api_stubs/_draft/statistical_functions.py index 92cdb5755..14952402c 100644 --- a/src/array_api_stubs/_draft/statistical_functions.py +++ b/src/array_api_stubs/_draft/statistical_functions.py @@ -1,9 +1,67 @@ -__all__ = ["max", "mean", "min", "prod", "std", "sum", "var"] +__all__ = ["cumulative_sum", "max", "mean", "min", "prod", "std", "sum", "var"] from ._types import Optional, Tuple, Union, array, dtype +def cumulative_sum( + x: array, + /, + *, + axis: Optional[int] = None, + dtype: Optional[dtype] = None, + include_initial: bool = False, +) -> array: + """ + Calculates the cumulative sum of elements in the input array ``x``. + + Parameters + ---------- + x: array + input array. Should have a numeric data type. + axis: Optional[int] + axis along which a cumulative sum must be computed. If ``axis`` is negative, the function must determine the axis along which to compute a cumulative sum by counting from the last dimension. + + If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. + dtype: Optional[dtype] + data type of the returned array. If ``None``, + + - if the default data type corresponding to the data type "kind" (integer, real-valued floating-point, or complex floating-point) of ``x`` has a smaller range of values than the data type of ``x`` (e.g., ``x`` has data type ``int64`` and the default data type is ``int32``, or ``x`` has data type ``uint64`` and the default data type is ``int64``), the returned array must have the same data type as ``x``. + + - if the default data type corresponding to the data type "kind" of ``x`` has the same or a larger range of values than the data type of ``x``, + + - if ``x`` has a real-valued floating-point data type, the returned array must have the default real-valued floating-point data type. + - if ``x`` has a complex floating-point data type, the returned array must have the default complex floating-point data type. + - if ``x`` has a signed integer data type (e.g., ``int16``), the returned array must have the default integer data type. + - if ``x`` has an unsigned integer data type (e.g., ``uint16``), the returned array must have an unsigned integer data type having the same number of bits as the default integer data type (e.g., if the default integer data type is ``int32``, the returned array must have a ``uint32`` data type). + + If the data type (either specified or resolved) differs from the data type of ``x``, the input array should be cast to the specified data type before computing the sum. Default: ``None``. + + .. note:: + keyword argument is intended to help prevent data type overflows. + + include_initial: bool + boolean indicating whether to include the initial value as the first value in the output. By convention, the initial value must be the additive identity (i.e., zero). Default: ``False``. + + Returns + ------- + out: array + an array containing the cumulative sums. The returned array must have a data type as described by the ``dtype`` parameter above. + + Let ``N`` be the size of the axis along which to compute the cumulative sum. The returned array must have a shape determined according to the following rules: + + - if ``include_initial`` is ``True``, the returned array must have the same shape as ``x``, except the size of the axis along which to compute the cumulative sum must be ``N+1``. + - if ``include_initial`` is ``False``, the returned array must have the same shape as ``x``. + + Notes + ----- + + **Special Cases** + + For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of :func:`~array_api.add`. + """ + + def max( x: array, /, From bda9c4872f65d5420142d65269968e287bcc9d59 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 13 Dec 2023 21:06:13 -0800 Subject: [PATCH 05/44] Add note clarifying behavior for out-of-bounds indices in `take` PR-URL: https://github.com/data-apis/array-api/pull/701 --- src/array_api_stubs/_draft/indexing_functions.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/array_api_stubs/_draft/indexing_functions.py b/src/array_api_stubs/_draft/indexing_functions.py index 3f4c25215..f3bf0fc14 100644 --- a/src/array_api_stubs/_draft/indexing_functions.py +++ b/src/array_api_stubs/_draft/indexing_functions.py @@ -16,6 +16,10 @@ def take(x: array, indices: array, /, *, axis: Optional[int] = None) -> array: input array. indices: array array indices. The array must be one-dimensional and have an integer data type. + + .. note:: + This specification does not require bounds checking. The behavior for out-of-bounds indices is left unspecified. + axis: int axis over which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension. From 50ca6792b44aa3d10a31c696adbd03f815ffabac Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 13 Dec 2023 21:11:35 -0800 Subject: [PATCH 06/44] Add specifications for `maximum` and `minimum` Closes: https://github.com/data-apis/array-api/issues/667 PR-URL: https://github.com/data-apis/array-api/pull/713 --- .../elementwise_functions.rst | 2 + .../_draft/elementwise_functions.py | 62 +++++++++++++++++++ 2 files changed, 64 insertions(+) diff --git a/spec/draft/API_specification/elementwise_functions.rst b/spec/draft/API_specification/elementwise_functions.rst index b3f08727b..7984d8e02 100644 --- a/spec/draft/API_specification/elementwise_functions.rst +++ b/spec/draft/API_specification/elementwise_functions.rst @@ -60,6 +60,8 @@ Objects in API logical_not logical_or logical_xor + maximum + minimum multiply negative not_equal diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 5ff0c45d6..3da5412ca 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -42,6 +42,8 @@ "logical_not", "logical_or", "logical_xor", + "maximum", + "minimum", "multiply", "negative", "not_equal", @@ -1820,6 +1822,66 @@ def logical_xor(x1: array, x2: array, /) -> array: """ +def maximum(x1: array, x2: array, /) -> array: + r""" + Computes the maximum value for each element ``x1_i`` of the input array ``x1`` relative to the respective element ``x2_i`` of the input array ``x2``. + + .. note:: + For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + + Parameters + ---------- + x1: array + first input array. Should have a real-valued data type. + x2: array + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. + + Returns + ------- + out: array + an array containing the element-wise maximum values. The returned array must have a data type determined by :ref:`type-promotion`. + + Notes + ----- + + **Special Cases** + + For floating-point operands, + + - If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``. + """ + + +def minimum(x1: array, x2: array, /) -> array: + r""" + Computes the minimum value for each element ``x1_i`` of the input array ``x1`` relative to the respective element ``x2_i`` of the input array ``x2``. + + .. note:: + For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + + Parameters + ---------- + x1: array + first input array. Should have a real-valued data type. + x2: array + second input array. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. + + Returns + ------- + out: array + an array containing the element-wise minimum values. The returned array must have a data type determined by :ref:`type-promotion`. + + Notes + ----- + + **Special Cases** + + For floating-point operands, + + - If either ``x1_i`` or ``x2_i`` is ``NaN``, the result is ``NaN``. + """ + + def multiply(x1: array, x2: array, /) -> array: r""" Calculates the product for each element ``x1_i`` of the input array ``x1`` with the respective element ``x2_i`` of the input array ``x2``. From 5c2423a96c9fd5113e405df88f2422f14cd978b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Sok=C3=B3=C5=82?= <8431159+mtsokol@users.noreply.github.com> Date: Mon, 18 Dec 2023 21:27:33 +0100 Subject: [PATCH 07/44] Fix definition of complex inner product in `vecdot` (#723) PR-URL: https://github.com/data-apis/array-api/pull/723 Reviewed-by: Athan Reines --- src/array_api_stubs/_2022_12/linear_algebra_functions.py | 4 ++-- src/array_api_stubs/_draft/linear_algebra_functions.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_2022_12/linear_algebra_functions.py b/src/array_api_stubs/_2022_12/linear_algebra_functions.py index 110a19ce1..d5329db76 100644 --- a/src/array_api_stubs/_2022_12/linear_algebra_functions.py +++ b/src/array_api_stubs/_2022_12/linear_algebra_functions.py @@ -122,9 +122,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as .. math:: - \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} a_i\overline{b_i} + \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} \overline{a_i}b_i - over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{b_i}` denotes the complex conjugate if :math:`b_i` is complex and the identity if :math:`b_i` is real-valued. + over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{a_i}` denotes the complex conjugate if :math:`a_i` is complex and the identity if :math:`a_i` is real-valued. Parameters ---------- diff --git a/src/array_api_stubs/_draft/linear_algebra_functions.py b/src/array_api_stubs/_draft/linear_algebra_functions.py index 079a90ee6..96f082bd5 100644 --- a/src/array_api_stubs/_draft/linear_algebra_functions.py +++ b/src/array_api_stubs/_draft/linear_algebra_functions.py @@ -126,9 +126,9 @@ def vecdot(x1: array, x2: array, /, *, axis: int = -1) -> array: Let :math:`\mathbf{a}` be a vector in ``x1`` and :math:`\mathbf{b}` be a corresponding vector in ``x2``. The dot product is defined as .. math:: - \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} a_i\overline{b_i} + \mathbf{a} \cdot \mathbf{b} = \sum_{i=0}^{n-1} \overline{a_i}b_i - over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{b_i}` denotes the complex conjugate if :math:`b_i` is complex and the identity if :math:`b_i` is real-valued. + over the dimension specified by ``axis`` and where :math:`n` is the dimension size and :math:`\overline{a_i}` denotes the complex conjugate if :math:`a_i` is complex and the identity if :math:`a_i` is real-valued. Parameters ---------- From 32957765c8986f050c09a7fa55b3af317854881e Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 9 Jan 2024 17:38:20 -0700 Subject: [PATCH 08/44] Update fft, ifft, fftn, ifftn, and hfft to only accept complex inputs See the discussion at #720 This still requires changelog entries. --- src/array_api_stubs/_draft/fft.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index c89bab024..0cd3d8722 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -35,7 +35,7 @@ def fft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the output. If @@ -60,7 +60,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -86,7 +86,7 @@ def ifft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the output. If @@ -111,7 +111,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -137,7 +137,7 @@ def fftn( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. s: Sequence[int] length of each transformed axis of the output. If @@ -169,7 +169,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -195,7 +195,7 @@ def ifftn( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. s: Sequence[int] length of each transformed axis of the output. If @@ -227,7 +227,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -468,7 +468,7 @@ def hfft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the **output**. If @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. If ``x`` has a complex floating-point data type, the returned array must have the same data type as ``x``. If ``x`` has a real-valued floating-point data type, the returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- From 72f86f37e51cd28183c6b25c6b0b6d81ff497856 Mon Sep 17 00:00:00 2001 From: Athan Date: Thu, 11 Jan 2024 13:47:26 -0800 Subject: [PATCH 09/44] Add `searchsorted` to the specification (#699) --- .../API_specification/searching_functions.rst | 1 + .../_draft/searching_functions.py | 54 ++++++++++++++++++- 2 files changed, 53 insertions(+), 2 deletions(-) diff --git a/spec/draft/API_specification/searching_functions.rst b/spec/draft/API_specification/searching_functions.rst index 01ab4e82a..c952f1aad 100644 --- a/spec/draft/API_specification/searching_functions.rst +++ b/spec/draft/API_specification/searching_functions.rst @@ -23,4 +23,5 @@ Objects in API argmax argmin nonzero + searchsorted where diff --git a/src/array_api_stubs/_draft/searching_functions.py b/src/array_api_stubs/_draft/searching_functions.py index e586a7656..dda000e74 100644 --- a/src/array_api_stubs/_draft/searching_functions.py +++ b/src/array_api_stubs/_draft/searching_functions.py @@ -1,7 +1,7 @@ -__all__ = ["argmax", "argmin", "nonzero", "where"] +__all__ = ["argmax", "argmin", "nonzero", "searchsorted", "where"] -from ._types import Optional, Tuple, array +from ._types import Optional, Tuple, Literal, array def argmax(x: array, /, *, axis: Optional[int] = None, keepdims: bool = False) -> array: @@ -87,6 +87,56 @@ def nonzero(x: array, /) -> Tuple[array, ...]: """ +def searchsorted( + x1: array, + x2: array, + /, + *, + side: Literal["left", "right"] = "left", + sorter: Optional[array] = None, +) -> array: + """ + Finds the indices into ``x1`` such that, if the corresponding elements in ``x2`` were inserted before the indices, the order of ``x1``, when sorted in ascending order, would be preserved. + + Parameters + ---------- + x1: array + input array. Must be a one-dimensional array. Should have a real-valued data type. If ``sorter`` is ``None``, must be sorted in ascending order; otherwise, ``sorter`` must be an array of indices that sort ``x1`` in ascending order. + x2: array + array containing search values. Should have a real-valued data type. + side: Literal['left', 'right'] + argument controlling which index is returned if a value lands exactly on an edge. + + Let ``x`` be an array of rank ``N`` where ``v`` is an individual element given by ``v = x2[n,m,...,j]``. + + If ``side == 'left'``, then + + - each returned index ``i`` must satisfy the index condition ``x1[i-1] < v <= x1[i]``. + - if no index satisfies the index condition, then the returned index for that element must be ``0``. + + Otherwise, if ``side == 'right'``, then + + - each returned index ``i`` must satisfy the index condition ``x1[i-1] <= v < x1[i]``. + - if no index satisfies the index condition, then the returned index for that element must be ``N``, where ``N`` is the number of elements in ``x1``. + + Default: ``'left'``. + sorter: Optional[array] + array of indices that sort ``x1`` in ascending order. The array must have the same shape as ``x1`` and have an integer data type. Default: ``None``. + + Returns + ------- + out: array + an array of indices with the same shape as ``x2``. The returned array must have the default array index data type. + + Notes + ----- + + For real-valued floating-point arrays, the sort order of NaNs and signed zeros is unspecified and thus implementation-dependent. Accordingly, when a real-valued floating-point array contains NaNs and signed zeros, what constitutes ascending order may vary among specification-conforming array libraries. + + While behavior for arrays containing NaNs and signed zeros is implementation-dependent, specification-conforming libraries should, however, ensure consistency with ``sort`` and ``argsort`` (i.e., if a value in ``x2`` is inserted into ``x1`` according to the corresponding index in the output array and ``sort`` is invoked on the resultant array, the sorted result should be an array in the same order). + """ + + def where(condition: array, x1: array, x2: array, /) -> array: """ Returns elements chosen from ``x1`` or ``x2`` depending on ``condition``. From 8fe8b0864ce0dd48cca1006accb684c34513783d Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Thu, 11 Jan 2024 23:26:14 +0100 Subject: [PATCH 10/44] Fix sidebar contents under Extensions (#729) The problem was that the sidebar doesn't show the named pages in the toctree if that toctree is under a subheading in index.rst Closes gh-716 --- spec/draft/extensions/index.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/spec/draft/extensions/index.rst b/spec/draft/extensions/index.rst index 30d9cfa90..3b9409954 100644 --- a/spec/draft/extensions/index.rst +++ b/spec/draft/extensions/index.rst @@ -24,11 +24,10 @@ the implementer, e.g. via a regular submodule that is imported under the The functions in an extension must adhere to the same conventions as those in the array API standard. See :ref:`api-specification`. - -Extensions ----------- +------------------------------------------------------------------------------ .. toctree:: + :caption: Extension modules: :maxdepth: 1 fourier_transform_functions From 7a56675105864d98cf43b65656f6c2edf93bd2d4 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 12 Jan 2024 10:41:22 +0100 Subject: [PATCH 11/44] Update DLPack content to address unsupported use cases (#709) Also extend the description of errors when DLPack cannot be supported --- spec/draft/design_topics/data_interchange.rst | 19 +++++++++++++++++++ .../_draft/creation_functions.py | 14 ++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/spec/draft/design_topics/data_interchange.rst b/spec/draft/design_topics/data_interchange.rst index 8686042c8..3b3040672 100644 --- a/spec/draft/design_topics/data_interchange.rst +++ b/spec/draft/design_topics/data_interchange.rst @@ -84,3 +84,22 @@ page gives a high-level specification for data exchange in Python using DLPack. are recommended to do so using the same syntax and semantics as outlined below. They are not required to return an array object from ``from_dlpack`` which conforms to this standard. + +Non-supported use cases +----------------------- + +Use of DLPack requires that the data can be represented by a strided, in-memory +layout on a single device. This covers usage by a large range of, but not all, +known and possible array libraries. Use cases that are not supported by DLPack +include: + +- Distributed arrays, i.e., the data residing on multiple nodes or devices, +- Sparse arrays, i.e., sparse representations where a data value (typically + zero) is implicit. + +There may be other reasons why it is not possible or desirable for an +implementation to materialize the array as strided data in memory. In such +cases, the implementation may raise a `BufferError` in the `__dlpack__` or +`__dlpack_device__` method. In case an implementation is never able to export +its array data via DLPack, it may omit `__dlpack__` and `__dlpack_device__` +completely, and hence `from_dlpack` may raise an `AttributeError`. diff --git a/src/array_api_stubs/_draft/creation_functions.py b/src/array_api_stubs/_draft/creation_functions.py index 5e2bb44e6..69733a646 100644 --- a/src/array_api_stubs/_draft/creation_functions.py +++ b/src/array_api_stubs/_draft/creation_functions.py @@ -232,6 +232,20 @@ def from_dlpack(x: object, /) -> array: :class: note The returned array may be either a copy or a view. See :ref:`data-interchange` for details. + + Raises + ------ + BufferError + The ``__dlpack__`` and ``__dlpack_device__`` methods on the input array + may raise ``BufferError`` when the data cannot be exported as DLPack + (e.g., incompatible dtype or strides). It may also raise other errors + when export fails for other reasons (e.g., not enough memory available + to materialize the data). ``from_dlpack`` must propagate such + exceptions. + AttributeError + If the ``__dlpack__`` and ``__dlpack_device__`` methods are not present + on the input array. This may happen for libraries that are never able + to export their data with DLPack. """ From 7c3f99a5505507ab176500b4188da87f5205671c Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 12 Jan 2024 14:43:48 -0700 Subject: [PATCH 12/44] Backport fft language improvements to 2022.12 --- src/array_api_stubs/_2022_12/fft.py | 118 ++++++++++++++-------------- 1 file changed, 59 insertions(+), 59 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 7979095fe..e8e97766b 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -18,13 +18,13 @@ def fft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -43,7 +43,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -69,13 +69,13 @@ def ifft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -94,7 +94,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -120,16 +120,16 @@ def fftn( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the output. If + length of each transformed axis of the output. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -152,7 +152,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -178,16 +178,16 @@ def ifftn( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the output. If + length of each transformed axis of the output. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -210,7 +210,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -240,9 +240,9 @@ def rfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -261,7 +261,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -291,9 +291,9 @@ def irfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array, the input array is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array is trimmed to length ``n//2+1``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -312,7 +312,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise). + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- @@ -340,14 +340,14 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the **input**. If + length of each transformed axis of the **input**. If - - ``s[i]`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``s[i]``. - - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``s[i]``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. + - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -370,7 +370,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. Notes ----- @@ -398,14 +398,14 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Sequence[int] - size of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If + length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If - - ``n`` is greater than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to size ``n``. - - ``n`` is less than the size of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to size ``n``. + - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the size of each transformed axis (dimension) in the output array must equal the size of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the size along the transformed axis specified by ``axes[i]``. + If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. axes: Sequence[int] @@ -428,7 +428,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2*(m - 1)`` (otherwise), and all other axes ``s[i]``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Notes ----- @@ -451,13 +451,13 @@ def hfft( Parameters ---------- x: array - input array. Should have a floating-point data type. + input array. Should have a complex-valued floating-point data type. n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array, the input array is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array is trimmed to length ``n//2+1``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array axis, the input array axis is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -476,7 +476,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- @@ -503,9 +503,9 @@ def ihfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array, the input array is zero-padded to length ``n``. - - ``n`` is less than the length of the input array, the input array is trimmed to length ``n``. - - ``n`` is not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. + - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -524,7 +524,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex-valued floating-point data type determined by :ref:`type-promotion`. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``m//2 + 1``, where ``m` is ``n` if ``n`` is given, or the length of the input along the axis specified by ``axis`` otherwise. Notes ----- @@ -535,7 +535,7 @@ def ihfft( def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> array: """ - Returns the discrete Fourier transform sample frequencies. + Computes the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: @@ -556,7 +556,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar Returns ------- out: array - an array of length ``n`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array of shape ``(n,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- @@ -567,7 +567,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> array: """ - Returns the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). + Computes the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: @@ -590,7 +590,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a Returns ------- out: array - an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a real-valued floating-point data type determined by :ref:`type-promotion`. + an array of shape ``(n//2+1,)`` containing the sample frequencies. The returned array must have the default real-valued floating-point data type. Notes ----- @@ -618,7 +618,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. + the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. Notes ----- @@ -644,7 +644,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. + the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. Notes ----- From 62f95fddc7792487a679e461dc212ec47f817141 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Fri, 12 Jan 2024 14:53:23 -0700 Subject: [PATCH 13/44] Fix typo for hfft return dtype --- src/array_api_stubs/_2022_12/fft.py | 2 +- src/array_api_stubs/_draft/fft.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index e8e97766b..487d97ecd 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -476,7 +476,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 0cd3d8722..a7275e1a9 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. Notes ----- From 6e320d01b60dc38e7119ed3e9d409a00818bbe0b Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 22 Jan 2024 12:07:38 -0800 Subject: [PATCH 14/44] Add `clip` to the specification PR-URL: https://github.com/data-apis/array-api/pull/715 --- .../elementwise_functions.rst | 1 + .../_draft/elementwise_functions.py | 35 ++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/spec/draft/API_specification/elementwise_functions.rst b/spec/draft/API_specification/elementwise_functions.rst index 7984d8e02..f0b69cfcb 100644 --- a/spec/draft/API_specification/elementwise_functions.rst +++ b/spec/draft/API_specification/elementwise_functions.rst @@ -33,6 +33,7 @@ Objects in API bitwise_right_shift bitwise_xor ceil + clip conj copysign cos diff --git a/src/array_api_stubs/_draft/elementwise_functions.py b/src/array_api_stubs/_draft/elementwise_functions.py index 3da5412ca..c71b6674b 100644 --- a/src/array_api_stubs/_draft/elementwise_functions.py +++ b/src/array_api_stubs/_draft/elementwise_functions.py @@ -15,6 +15,7 @@ "bitwise_right_shift", "bitwise_xor", "ceil", + "clip", "conj", "copysign", "cos", @@ -65,7 +66,7 @@ ] -from ._types import array +from ._types import Optional, Union, array def abs(x: array, /) -> array: @@ -775,6 +776,38 @@ def ceil(x: array, /) -> array: """ +def clip( + x: array, + /, + min: Optional[Union[int, float, array]] = None, + max: Optional[Union[int, float, array]] = None, +) -> array: + r""" + Clamps each element ``x_i`` of the input array ``x`` to the range ``[min, max]``. + + Parameters + ---------- + x: array + input array. Should have a real-valued data type. + min: Optional[Union[int, float, array]] + lower-bound of the range to which to clamp. If ``None``, no lower bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + max: Optional[Union[int, float, array]] + upper-bound of the range to which to clamp. If ``None``, no upper bound must be applied. Must be compatible with ``x1`` (see :ref:`broadcasting`). Should have a real-valued data type. Default: ``None``. + + Returns + ------- + out: array + an array containing element-wise results. The returned array must have the same data type as ``x``. + + Notes + ----- + + - If both ``min`` and ``max`` are ``None``, the elements of the returned array must equal the respective elements in ``x``. + - If a broadcasted element in ``min`` is greater than a corresponding broadcasted element in ``max``, behavior is unspecified and thus implementation-dependent. + - If ``x`` and either ``min`` or ``max`` have different data type kinds (e.g., integer versus floating-point), behavior is unspecified and thus implementation-dependent. + """ + + def conj(x: array, /) -> array: """ Returns the complex conjugate for each element ``x_i`` of the input array ``x``. From 0cde841671d99fc2e028eea87cd13d6eea49704e Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 22 Jan 2024 21:30:09 +0100 Subject: [PATCH 15/44] Clarify guidance in the "function and method signatures" section The type annotations part was a little outdated. For the positional and keyword-only descriptions, improve the language to account for exceptions to the default design rules. Closes: #475 PR-URL: https://github.com/data-apis/array-api/pull/730 Reviewed-by: Athan Reines --- .../function_and_method_signatures.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/spec/draft/API_specification/function_and_method_signatures.rst b/spec/draft/API_specification/function_and_method_signatures.rst index 86d0819a6..0eca2ac69 100644 --- a/spec/draft/API_specification/function_and_method_signatures.rst +++ b/spec/draft/API_specification/function_and_method_signatures.rst @@ -5,7 +5,7 @@ Function and method signatures Function signatures in this standard adhere to the following: -1. Positional parameters must be `positional-only `_ parameters. +1. Positional parameters should be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. @@ -20,7 +20,7 @@ Function signatures in this standard adhere to the following: namespace >= 3.8. Alternatively, they can add guidance to their users in the documentation to use the functions as if they were positional-only. -2. Optional parameters must be `keyword-only `_ arguments. +2. Optional parameters should be `keyword-only `_ arguments. *Rationale: this leads to more readable code, and it makes it easier to evolve an API over time by adding keywords without having to worry about @@ -30,8 +30,8 @@ Function signatures in this standard adhere to the following: is called ``x``. For functions that have multiple array parameters, those parameters are called ``xi`` with ``i = 1, 2, ...`` (i.e., ``x1``, ``x2``). -4. Type annotations are left out of the signatures themselves for readability; however, - they are added to individual parameter descriptions. For code which aims to +4. Signatures include type annotations. The type annotations are also added to + individual parameter and return value descriptions. For code which aims to adhere to the standard, adding type annotations is strongly recommended. A function signature and description will look like: @@ -57,3 +57,7 @@ A function signature and description will look like: Method signatures will follow the same conventions modulo the addition of ``self``. + +Note that there are a few exceptions to rules (1) and (2), in cases where +it enhances readability or use of the non-default form of the parameter in +question is commonly used in code written for existing array libraries. From 293512d35f8acccb55b184462505cdb1ab5d1a14 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Mon, 22 Jan 2024 23:22:28 +0100 Subject: [PATCH 16/44] Upgrade Sphinx version used in doc deployment (#735) * Upgrade Sphinx version used in doc deployment It was breaking with: ``` sphinx-build "spec/2021.12" "_site/2021.12" -W --keep-going Running Sphinx v4.3.0 Sphinx version error: The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version. ``` * Fix some doc build warnings that broke in CI --- doc-requirements.txt | 3 +-- spec/2021.12/assumptions.md | 4 ++-- spec/2021.12/purpose_and_scope.md | 2 +- spec/2021.12/use_cases.md | 2 +- spec/2022.12/assumptions.md | 4 ++-- spec/2022.12/purpose_and_scope.md | 2 +- spec/2022.12/use_cases.md | 2 +- spec/draft/assumptions.md | 4 ++-- spec/draft/purpose_and_scope.md | 2 +- spec/draft/use_cases.md | 2 +- src/_array_api_conf.py | 2 ++ 11 files changed, 15 insertions(+), 14 deletions(-) diff --git a/doc-requirements.txt b/doc-requirements.txt index 488aa3e81..08ced9aa2 100644 --- a/doc-requirements.txt +++ b/doc-requirements.txt @@ -1,8 +1,7 @@ -sphinx==4.3.0 +sphinx==6.2.1 sphinx-material==0.0.30 myst-parser sphinx_markdown_tables sphinx_copybutton sphinx_favicon -docutils<0.18 sphinx-math-dollar diff --git a/spec/2021.12/assumptions.md b/spec/2021.12/assumptions.md index 3a90710ea..b11482c5a 100644 --- a/spec/2021.12/assumptions.md +++ b/spec/2021.12/assumptions.md @@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values. The only dependency that's assumed in this standard is that on Python itself. Python >= 3.8 is assumed, motivated by the use of positional-only parameters -(see [function and method signatures](API_specification/function_and_method_signatures.md)). +(see [function and method signatures](API_specification/function_and_method_signatures.rst)). Importantly, array libraries are not assumed to be aware of each other, or of a common array-specific layer. The [use cases](use_cases.md) do not require @@ -39,7 +39,7 @@ for that is: Array libraries may know how to interoperate with each other, for example by constructing their own array type from that of another library or by shared -memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)). +memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)). This can be done without a dependency though - only adherence to a protocol is enough. diff --git a/spec/2021.12/purpose_and_scope.md b/spec/2021.12/purpose_and_scope.md index 4678ba064..0debbc08a 100644 --- a/spec/2021.12/purpose_and_scope.md +++ b/spec/2021.12/purpose_and_scope.md @@ -151,7 +151,7 @@ standard is shown in this diagram: _Rationale: this is an important topic for some array-consuming libraries, but there is no widely shared C/Cython API and hence it doesn't make sense at this point in time to standardize anything. See - the [C API section](design_topics/C_API.md) for more details._ + the [C API section](design_topics/C_API.rst) for more details._ 4. Standardization of these dtypes is out of scope: bfloat16, complex, extended precision floating point, datetime, string, object and void dtypes. diff --git a/spec/2021.12/use_cases.md b/spec/2021.12/use_cases.md index 26f7a529c..e24aa50db 100644 --- a/spec/2021.12/use_cases.md +++ b/spec/2021.12/use_cases.md @@ -59,7 +59,7 @@ array implementation as a dependency. It's clear that SciPy functionality that relies on compiled extensions (C, C++, Cython, Fortran) directly can't easily be run on another array library -than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python +than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python code can work though. There's two main possibilities: 1. Testing with another package, manually or in CI, and simply provide a list diff --git a/spec/2022.12/assumptions.md b/spec/2022.12/assumptions.md index 3a90710ea..b11482c5a 100644 --- a/spec/2022.12/assumptions.md +++ b/spec/2022.12/assumptions.md @@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values. The only dependency that's assumed in this standard is that on Python itself. Python >= 3.8 is assumed, motivated by the use of positional-only parameters -(see [function and method signatures](API_specification/function_and_method_signatures.md)). +(see [function and method signatures](API_specification/function_and_method_signatures.rst)). Importantly, array libraries are not assumed to be aware of each other, or of a common array-specific layer. The [use cases](use_cases.md) do not require @@ -39,7 +39,7 @@ for that is: Array libraries may know how to interoperate with each other, for example by constructing their own array type from that of another library or by shared -memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)). +memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)). This can be done without a dependency though - only adherence to a protocol is enough. diff --git a/spec/2022.12/purpose_and_scope.md b/spec/2022.12/purpose_and_scope.md index 38287f270..f375c9512 100644 --- a/spec/2022.12/purpose_and_scope.md +++ b/spec/2022.12/purpose_and_scope.md @@ -151,7 +151,7 @@ standard is shown in this diagram: _Rationale: this is an important topic for some array-consuming libraries, but there is no widely shared C/Cython API and hence it doesn't make sense at this point in time to standardize anything. See - the [C API section](design_topics/C_API.md) for more details._ + the [C API section](design_topics/C_API.rst) for more details._ 4. Standardization of these dtypes is out of scope: bfloat16, extended precision floating point, datetime, string, object and void dtypes. diff --git a/spec/2022.12/use_cases.md b/spec/2022.12/use_cases.md index 26f7a529c..e24aa50db 100644 --- a/spec/2022.12/use_cases.md +++ b/spec/2022.12/use_cases.md @@ -59,7 +59,7 @@ array implementation as a dependency. It's clear that SciPy functionality that relies on compiled extensions (C, C++, Cython, Fortran) directly can't easily be run on another array library -than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python +than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python code can work though. There's two main possibilities: 1. Testing with another package, manually or in CI, and simply provide a list diff --git a/spec/draft/assumptions.md b/spec/draft/assumptions.md index 3a90710ea..b11482c5a 100644 --- a/spec/draft/assumptions.md +++ b/spec/draft/assumptions.md @@ -26,7 +26,7 @@ of functions to be predictable from input dtypes only rather than input values. The only dependency that's assumed in this standard is that on Python itself. Python >= 3.8 is assumed, motivated by the use of positional-only parameters -(see [function and method signatures](API_specification/function_and_method_signatures.md)). +(see [function and method signatures](API_specification/function_and_method_signatures.rst)). Importantly, array libraries are not assumed to be aware of each other, or of a common array-specific layer. The [use cases](use_cases.md) do not require @@ -39,7 +39,7 @@ for that is: Array libraries may know how to interoperate with each other, for example by constructing their own array type from that of another library or by shared -memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.md)). +memory use of an array (see [Data interchange mechanisms](design_topics/data_interchange.rst)). This can be done without a dependency though - only adherence to a protocol is enough. diff --git a/spec/draft/purpose_and_scope.md b/spec/draft/purpose_and_scope.md index 38287f270..f375c9512 100644 --- a/spec/draft/purpose_and_scope.md +++ b/spec/draft/purpose_and_scope.md @@ -151,7 +151,7 @@ standard is shown in this diagram: _Rationale: this is an important topic for some array-consuming libraries, but there is no widely shared C/Cython API and hence it doesn't make sense at this point in time to standardize anything. See - the [C API section](design_topics/C_API.md) for more details._ + the [C API section](design_topics/C_API.rst) for more details._ 4. Standardization of these dtypes is out of scope: bfloat16, extended precision floating point, datetime, string, object and void dtypes. diff --git a/spec/draft/use_cases.md b/spec/draft/use_cases.md index 26f7a529c..e24aa50db 100644 --- a/spec/draft/use_cases.md +++ b/spec/draft/use_cases.md @@ -59,7 +59,7 @@ array implementation as a dependency. It's clear that SciPy functionality that relies on compiled extensions (C, C++, Cython, Fortran) directly can't easily be run on another array library -than NumPy (see [C API](design_topics/C_API.md) for more details about this topic). Pure Python +than NumPy (see [C API](design_topics/C_API.rst) for more details about this topic). Pure Python code can work though. There's two main possibilities: 1. Testing with another package, manually or in CI, and simply provide a list diff --git a/src/_array_api_conf.py b/src/_array_api_conf.py index d3a136eaa..9c5722f94 100644 --- a/src/_array_api_conf.py +++ b/src/_array_api_conf.py @@ -52,12 +52,14 @@ nitpick_ignore = [ ("py:class", "collections.abc.Sequence"), ("py:class", "Optional[Union[int, float, Literal[inf, - inf, 'fro', 'nuc']]]"), + ("py:class", "int | float | ~typing.Literal[inf, -inf, 'fro', 'nuc'] | None"), ("py:class", "Union[int, float, Literal[inf, - inf]]"), ( "py:obj", "typing.Optional[typing.Union[int, float, typing.Literal[inf, - inf, 'fro', 'nuc']]]", ), ("py:obj", "typing.Union[int, float, typing.Literal[inf, - inf]]"), + ("py:class", "int | float | ~typing.Literal[inf, -inf]"), ("py:class", "enum.Enum"), ("py:class", "ellipsis"), ] From 95332bb71159cea68e15e7d20364a3e07060a402 Mon Sep 17 00:00:00 2001 From: Hameer Abbasi <2190658+hameerabbasi@users.noreply.github.com> Date: Thu, 25 Jan 2024 13:59:59 +0100 Subject: [PATCH 17/44] Fix wording for comparison operators PR-URL: https://github.com/data-apis/array-api/pull/736 Co-authored-by: Athan Reines Reviewed-by: Athan Reines --- spec/2022.12/API_specification/array_object.rst | 3 ++- spec/draft/API_specification/array_object.rst | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/spec/2022.12/API_specification/array_object.rst b/spec/2022.12/API_specification/array_object.rst index b15bbdc43..45aec9b34 100644 --- a/spec/2022.12/API_specification/array_object.rst +++ b/spec/2022.12/API_specification/array_object.rst @@ -163,7 +163,8 @@ A conforming implementation of the array API standard must provide and support a - `operator.ne(x1, x2) `_ - `operator.__ne__(x1, x2) `_ -Comparison operators should be defined for arrays having any data type. +:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type. +For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). In-place Operators ~~~~~~~~~~~~~~~~~~ diff --git a/spec/draft/API_specification/array_object.rst b/spec/draft/API_specification/array_object.rst index 0fadf9fc5..f8a586ade 100644 --- a/spec/draft/API_specification/array_object.rst +++ b/spec/draft/API_specification/array_object.rst @@ -163,7 +163,8 @@ A conforming implementation of the array API standard must provide and support a - `operator.ne(x1, x2) `_ - `operator.__ne__(x1, x2) `_ -Comparison operators should be defined for arrays having any data type. +:meth:`.array.__lt__`, :meth:`.array.__le__`, :meth:`.array.__gt__`, :meth:`.array.__ge__` are only defined for arrays having real-valued data types. Other comparison operators should be defined for arrays having any data type. +For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). In-place Operators ~~~~~~~~~~~~~~~~~~ From e9988f2c4f2ef7ef285d1a1f218581d787b16c57 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 5 Feb 2024 16:11:03 -0700 Subject: [PATCH 18/44] Fix the text for the output shape for (i)rfft(n) --- src/array_api_stubs/_draft/fft.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index a7275e1a9..f2a216d82 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -259,7 +259,7 @@ def rfft( - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full the length of the input array axis must be used. Default: ``None``. axis: int @@ -278,7 +278,8 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). If ``n`` is even, the length of the transformed axis is ``(n/2)+1``. If ``n`` is odd, the length is ``(n+1)/2``. If ``n`` is ``None``, it defaults to ``x.shape[axis]``. + Notes ----- @@ -310,7 +311,7 @@ def irfft( - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. Default: ``None``. axis: int @@ -329,7 +330,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis]-1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. Notes ----- @@ -387,7 +388,8 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. + Notes ----- @@ -445,7 +447,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. Notes ----- From 22fc23aebfecf66df6b537deea281e85f3d96eb4 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Mon, 5 Feb 2024 16:16:21 -0700 Subject: [PATCH 19/44] Add Optional type annotation for some parameters that can be None --- src/array_api_stubs/_draft/fft.py | 40 +++++++++++++++---------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index f2a216d82..7b8185e71 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -124,8 +124,8 @@ def fftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -138,7 +138,7 @@ def fftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the output. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -149,7 +149,7 @@ def fftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -182,8 +182,8 @@ def ifftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -196,7 +196,7 @@ def ifftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the output. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -207,7 +207,7 @@ def ifftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -343,8 +343,8 @@ def rfftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -357,7 +357,7 @@ def rfftn( ---------- x: array input array. Must have a real-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the **input**. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -368,7 +368,7 @@ def rfftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -402,8 +402,8 @@ def irfftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -416,7 +416,7 @@ def irfftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. @@ -427,7 +427,7 @@ def irfftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -618,7 +618,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a """ -def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: +def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ Shift the zero-frequency component to the center of the spectrum. @@ -631,7 +631,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ---------- x: array input array. Should have a floating-point data type. - axes: Union[int, Sequence[int]] + axes: Optional[Union[int, Sequence[int]]] axes over which to shift. If ``None``, the function must shift all axes. Default: ``None``. Returns @@ -646,7 +646,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: """ -def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: +def ifftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ Inverse of ``fftshift``. @@ -657,7 +657,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ---------- x: array input array. Should have a floating-point data type. - axes: Union[int, Sequence[int]] + axes: Optional[Union[int, Sequence[int]]] axes over which to perform the inverse shift. If ``None``, the function must shift all axes. Default: ``None``. Returns From d4eebdf7144e3af0398df9d818df52285dc9a255 Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 20:51:45 -0500 Subject: [PATCH 20/44] back port optional type annotation --- src/array_api_stubs/_2022_12/fft.py | 40 ++++++++++++++--------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 487d97ecd..da6f641fe 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -107,8 +107,8 @@ def fftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -121,7 +121,7 @@ def fftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the output. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -132,7 +132,7 @@ def fftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -165,8 +165,8 @@ def ifftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -179,7 +179,7 @@ def ifftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the output. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -190,7 +190,7 @@ def ifftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -325,8 +325,8 @@ def rfftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -339,7 +339,7 @@ def rfftn( ---------- x: array input array. Must have a real-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the **input**. If - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. @@ -350,7 +350,7 @@ def rfftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -383,8 +383,8 @@ def irfftn( x: array, /, *, - s: Sequence[int] = None, - axes: Sequence[int] = None, + s: Optional[Sequence[int]] = None, + axes: Optional[Sequence[int]] = None, norm: Literal["backward", "ortho", "forward"] = "backward", ) -> array: """ @@ -397,7 +397,7 @@ def irfftn( ---------- x: array input array. Should have a complex-valued floating-point data type. - s: Sequence[int] + s: Optional[Sequence[int]] length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. @@ -408,7 +408,7 @@ def irfftn( If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. Default: ``None``. - axes: Sequence[int] + axes: Optional[Sequence[int]] axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. @@ -599,7 +599,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a """ -def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: +def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ Shift the zero-frequency component to the center of the spectrum. @@ -612,7 +612,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ---------- x: array input array. Should have a floating-point data type. - axes: Union[int, Sequence[int]] + axes: Optional[Union[int, Sequence[int]]] axes over which to shift. If ``None``, the function must shift all axes. Default: ``None``. Returns @@ -627,7 +627,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: """ -def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: +def ifftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ Inverse of ``fftshift``. @@ -638,7 +638,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array: ---------- x: array input array. Should have a floating-point data type. - axes: Union[int, Sequence[int]] + axes: Optional[Union[int, Sequence[int]]] axes over which to perform the inverse shift. If ``None``, the function must shift all axes. Default: ``None``. Returns From 86cc351403754671b105d6b9081f02190f5a3f65 Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 20:55:48 -0500 Subject: [PATCH 21/44] nits --- src/array_api_stubs/_draft/fft.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 7b8185e71..2f216ab6d 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -280,7 +280,6 @@ def rfft( out: array an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). If ``n`` is even, the length of the transformed axis is ``(n/2)+1``. If ``n`` is odd, the length is ``(n+1)/2``. If ``n`` is ``None``, it defaults to ``x.shape[axis]``. - Notes ----- @@ -390,7 +389,6 @@ def rfftn( out: array an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. - Notes ----- From c4df0beabeb790d7a556caa0289a3c2d5d45a31a Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 21:05:41 -0500 Subject: [PATCH 22/44] sync 2022 and draft --- src/array_api_stubs/_2022_12/fft.py | 47 ++++++++++++++--------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index da6f641fe..2f216ab6d 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -1,3 +1,20 @@ +__all__ = [ + "fft", + "ifft", + "fftn", + "ifftn", + "rfft", + "irfft", + "rfftn", + "irfftn", + "hfft", + "ihfft", + "fftfreq", + "rfftfreq", + "fftshift", + "ifftshift", +] + from ._types import Tuple, Union, Sequence, array, Optional, Literal, device @@ -242,7 +259,7 @@ def rfft( - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full the length of the input array axis must be used. Default: ``None``. axis: int @@ -261,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). If ``n`` is even, the length of the transformed axis is ``(n/2)+1``. If ``n`` is odd, the length is ``(n+1)/2``. If ``n`` is ``None``, it defaults to ``x.shape[axis]``. Notes ----- @@ -293,7 +310,7 @@ def irfft( - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. Default: ``None``. axis: int @@ -312,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis]-1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. Notes ----- @@ -370,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. Notes ----- @@ -428,7 +445,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. Notes ----- @@ -651,21 +668,3 @@ def ifftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) .. versionadded:: 2022.12 """ - - -__all__ = [ - "fft", - "ifft", - "fftn", - "ifftn", - "rfft", - "irfft", - "rfftn", - "irfftn", - "hfft", - "ihfft", - "fftfreq", - "rfftfreq", - "fftshift", - "ifftshift", -] From 6a2d6d00863503f0cba6ce1ff284749d22e5a45d Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 21:10:36 -0500 Subject: [PATCH 23/44] nit: length of array "along" axis --- src/array_api_stubs/_2022_12/fft.py | 36 ++++++++++++++--------------- src/array_api_stubs/_draft/fft.py | 36 ++++++++++++++--------------- 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 2f216ab6d..a9c51624e 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -39,9 +39,9 @@ def fft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -90,9 +90,9 @@ def ifft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -257,9 +257,9 @@ def rfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -308,9 +308,9 @@ def irfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. + - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. Default: ``None``. axis: int @@ -472,9 +472,9 @@ def hfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array axis, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -520,9 +520,9 @@ def ihfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 2f216ab6d..a9c51624e 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -39,9 +39,9 @@ def fft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -90,9 +90,9 @@ def ifft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -257,9 +257,9 @@ def rfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -308,9 +308,9 @@ def irfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. + - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. Default: ``None``. axis: int @@ -472,9 +472,9 @@ def hfft( n: int length of the transformed axis of the **output**. If - - ``n//2+1`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array axis, the input array axis is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. + - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int @@ -520,9 +520,9 @@ def ihfft( n: int length of the transformed axis of the **input**. If - - ``n`` is greater than the length of the input array axis, the input array axis is zero-padded to length ``n``. - - ``n`` is less than the length of the input array axis, the input array axis is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array axis must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. Default: ``None``. axis: int From 4d6e519496fa8f9cd4cdf22519f0cde7016873c0 Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 21:47:00 -0500 Subject: [PATCH 24/44] mention untransformed axes & align style --- src/array_api_stubs/_2022_12/fft.py | 32 ++++++++++++++--------------- src/array_api_stubs/_draft/fft.py | 32 ++++++++++++++--------------- 2 files changed, 32 insertions(+), 32 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index a9c51624e..fb30e7e1c 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -41,7 +41,7 @@ def fft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -60,7 +60,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -92,7 +92,7 @@ def ifft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -111,7 +111,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -169,7 +169,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -227,7 +227,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -259,7 +259,7 @@ def rfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -278,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). If ``n`` is even, the length of the transformed axis is ``(n/2)+1``. If ``n`` is odd, the length is ``(n+1)/2``. If ``n`` is ``None``, it defaults to ``x.shape[axis]``. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -310,7 +310,7 @@ def irfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -329,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis]-1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -387,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -445,7 +445,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given, or ``2*(x.shape[axes[-1]] - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -474,7 +474,7 @@ def hfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along ``axis``. Default: ``None``. axis: int @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -522,7 +522,7 @@ def ihfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along ``axis``. Default: ``None``. axis: int @@ -541,7 +541,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``m//2 + 1``, where ``m` is ``n` if ``n`` is given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index a9c51624e..fb30e7e1c 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -41,7 +41,7 @@ def fft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -60,7 +60,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -92,7 +92,7 @@ def ifft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -111,7 +111,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -169,7 +169,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -227,7 +227,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -259,7 +259,7 @@ def rfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int @@ -278,7 +278,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). If ``n`` is even, the length of the transformed axis is ``(n/2)+1``. If ``n`` is odd, the length is ``(n+1)/2``. If ``n`` is ``None``, it defaults to ``x.shape[axis]``. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -310,7 +310,7 @@ def irfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis]-1)``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -329,7 +329,7 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis]-1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -387,7 +387,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -445,7 +445,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]`` if given, or ``2*(m - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given, or ``2*(x.shape[axes[-1]] - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -474,7 +474,7 @@ def hfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along ``axis``. Default: ``None``. axis: int @@ -493,7 +493,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given or ``2*(m-1)`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -522,7 +522,7 @@ def ihfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full the length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along the axis specified by ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along ``axis``. Default: ``None``. axis: int @@ -541,7 +541,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``m//2 + 1``, where ``m` is ``n` if ``n`` is given, or the length of the input along the axis specified by ``axis`` otherwise. + an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- From 35f2ea464c44019e0e0f9d7c16de7d9a1ea8136b Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 21:52:30 -0500 Subject: [PATCH 25/44] no more m --- src/array_api_stubs/_2022_12/fft.py | 6 +++--- src/array_api_stubs/_draft/fft.py | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index fb30e7e1c..5a2da565c 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -420,7 +420,7 @@ def irfftn( - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(x.shape[axes[-1]] - 1)``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -474,7 +474,7 @@ def hfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -522,7 +522,7 @@ def ihfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index fb30e7e1c..5a2da565c 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -420,7 +420,7 @@ def irfftn( - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(m-1)``, where ``m`` is the length of the input along the axis. + - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(x.shape[axes[-1]] - 1)``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -474,7 +474,7 @@ def hfft( - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(m-1)``, where ``m`` is the length of the input along ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -522,7 +522,7 @@ def ihfft( - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``m//2 + 1``, where ``m`` is the length of the input along ``axis``. + - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int From a84c293dfa163816ee3d999240f2da007f8b4f67 Mon Sep 17 00:00:00 2001 From: Leo Fang Date: Tue, 6 Feb 2024 23:21:47 -0500 Subject: [PATCH 26/44] separately list the condition when s/n is None --- src/array_api_stubs/_2022_12/fft.py | 40 +++++++++++++++++------------ src/array_api_stubs/_draft/fft.py | 40 +++++++++++++++++------------ 2 files changed, 46 insertions(+), 34 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 5a2da565c..eb9929e0d 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -255,11 +255,12 @@ def rfft( x: array input array. Must have a real-valued floating-point data type. n: int - length of the transformed axis of the **input**. If + length of the transformed axis of the **input**. If ``n`` is not ``None`` and - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int @@ -306,11 +307,12 @@ def irfft( x: array input array. Should have a complex-valued floating-point data type. n: int - length of the transformed axis of the **output**. If + length of the transformed axis of the **output**. If ``n`` is not ``None`` and - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -357,12 +359,13 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **input**. If + length of each transformed axis of the **input**. If ``s`` is not ``None`` and - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. + + If ``s`` is ``None`` (not provided), the full lengths of the input array along each transformed axis (dimension) are used (no padding/trimming). The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``x.shape[axes[-1]]//2 + 1``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -387,7 +390,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must equal ``s[-1]//2 + 1``, if ``s[-1]`` is given and not ``-1``, or `x.shape[axes[-1]]//2 + 1` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``s[i]`` is given and not ``-1``, or ``x.shape[axes[i]]`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -415,12 +418,13 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If + length of each transformed axis of the **output**. If ``s`` is not ``None``, ``n=s[i]`` is the number of input points used along the transformed axis (dimension) ``i``, except for the last transformed axis, where ``n=s[-1]//2 + 1`` points of the input are used. If - - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. + - ``s[i]`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(x.shape[axes[-1]] - 1)``. + + If ``s`` is ``None`` (not provided), the full length of the input array along each transformed axis (dimension) must be used. The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``2*(x.shape[axes[-1]] - 1)``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -445,7 +449,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given, or ``2*(x.shape[axes[-1]] - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given and not ``-1``, or ``2*(x.shape[axes[-1]] - 1)`` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``given and not ``-1``, or ``x.shape[i]``. Therefore, to get an odd number of output points along the last transformed axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -470,11 +474,12 @@ def hfft( x: array input array. Should have a complex-valued floating-point data type. n: int - length of the transformed axis of the **output**. If + length of the transformed axis of the **output**. If ``n`` is not ``None`` and - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -518,11 +523,12 @@ def ihfft( x: array input array. Must have a real-valued floating-point data type. n: int - length of the transformed axis of the **input**. If + length of the transformed axis of the **input**. If ``n`` is not ``None`` and - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``x.shape[axis]//2 + 1``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 5a2da565c..eb9929e0d 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -255,11 +255,12 @@ def rfft( x: array input array. Must have a real-valued floating-point data type. n: int - length of the transformed axis of the **input**. If + length of the transformed axis of the **input**. If ``n`` is not ``None`` and - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int @@ -306,11 +307,12 @@ def irfft( x: array input array. Should have a complex-valued floating-point data type. n: int - length of the transformed axis of the **output**. If + length of the transformed axis of the **output**. If ``n`` is not ``None`` and - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -357,12 +359,13 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **input**. If + length of each transformed axis of the **input**. If ``s`` is not ``None`` and - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. + + If ``s`` is ``None`` (not provided), the full lengths of the input array along each transformed axis (dimension) are used (no padding/trimming). The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``x.shape[axes[-1]]//2 + 1``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -387,7 +390,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must be equal to ``s[-1]//2+1`` and the length along the remaining transformed axes ``i`` must be equal to ``s[i]``, where ``s`` defaults to ``x.shape`` if the parameter ``s`` is ``None`` and ``s[i]`` defaults to ``x.shape[i]`` if ``s[i]`` is ``-1``. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must equal ``s[-1]//2 + 1``, if ``s[-1]`` is given and not ``-1``, or `x.shape[axes[-1]]//2 + 1` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``s[i]`` is given and not ``-1``, or ``x.shape[axes[i]]`` otherwise. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -415,12 +418,13 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **output**. ``n=s[i]`` is also the number of input points used along the axis (dimension) ``i``, except for the last axis, where ``n=s[-1]//2+1`` points of the input are used. If + length of each transformed axis of the **output**. If ``s`` is not ``None``, ``n=s[i]`` is the number of input points used along the transformed axis (dimension) ``i``, except for the last transformed axis, where ``n=s[-1]//2 + 1`` points of the input are used. If - - ``n`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. + - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. + - ``s[i]`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array, except for the last axis which is trimmed to ``2*(x.shape[axes[-1]] - 1)``. + + If ``s`` is ``None`` (not provided), the full length of the input array along each transformed axis (dimension) must be used. The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``2*(x.shape[axes[-1]] - 1)``. If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. @@ -445,7 +449,7 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given, or ``2*(x.shape[axes[-1]] - 1)`` otherwise, and all other axes ``s[i]``. Therefore, to get an odd number of output points along the last axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given and not ``-1``, or ``2*(x.shape[axes[-1]] - 1)`` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``given and not ``-1``, or ``x.shape[i]``. Therefore, to get an odd number of output points along the last transformed axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. Notes ----- @@ -470,11 +474,12 @@ def hfft( x: array input array. Should have a complex-valued floating-point data type. n: int - length of the transformed axis of the **output**. If + length of the transformed axis of the **output**. If ``n`` is not ``None`` and - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. Default: ``None``. axis: int @@ -518,11 +523,12 @@ def ihfft( x: array input array. Must have a real-valued floating-point data type. n: int - length of the transformed axis of the **input**. If + length of the transformed axis of the **input**. If ``n`` is not ``None`` and - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. The length of the transformed axis must equal ``x.shape[axis]//2 + 1``. + + If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis must equal ``x.shape[axis]//2 + 1``. Default: ``None``. axis: int From 029afcdca1c9054b911fca425b8f1091de82c218 Mon Sep 17 00:00:00 2001 From: Athan Date: Wed, 7 Feb 2024 02:31:30 -0800 Subject: [PATCH 27/44] Update language to be consistent with existing specification conventions --- src/array_api_stubs/_2022_12/fft.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index eb9929e0d..75ca8245b 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -39,9 +39,9 @@ def fft( n: int length of the transformed axis of the output. If - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` must be zero-padded to length ``n``. + - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` must be trimmed to length ``n``. + - ``n`` is ``None``, the full length of the input array along ``axis`` must be used. Default: ``None``. axis: int From 6d9fac46f126a4c1373acf1dea600f8f1254a0b6 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 02:16:56 -0800 Subject: [PATCH 28/44] Update copy for `fft` --- src/array_api_stubs/_2022_12/fft.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 75ca8245b..e5daf6320 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -30,24 +30,22 @@ def fft( Computes the one-dimensional discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (length, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the output. If + n: Optional[int] + number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` must be zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` must be trimmed to length ``n``. - - ``n`` is ``None``, the full length of the input array along ``axis`` must be used. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the discrete Fourier transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the Fourier transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -60,7 +58,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- @@ -650,7 +648,9 @@ def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) - """ -def ifftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: +def ifftshift( + x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None +) -> array: """ Inverse of ``fftshift``. From 66e9e292323acaa16975fd3ea32f23c7e84f8cd4 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 02:18:51 -0800 Subject: [PATCH 29/44] Update copy --- src/array_api_stubs/_2022_12/fft.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index e5daf6320..c65f58f35 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -41,7 +41,7 @@ def fft( - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. - - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the discrete Fourier transform. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int From 99cb7760ba9a5016457753df71f8c5e7d76d13ac Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 02:25:39 -0800 Subject: [PATCH 30/44] Update copy for `ifft` --- src/array_api_stubs/_2022_12/fft.py | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index c65f58f35..2cb540120 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -45,7 +45,7 @@ def fft( Default: ``None``. axis: int - axis (dimension) of the input array over which to compute the Fourier transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -79,24 +79,22 @@ def ifft( Computes the one-dimensional inverse discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same (length, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the output. If + n: Optional[int] + number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -109,7 +107,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- From 04a4e663ceeabbbe2c39c099a3e86b4489f17673 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 02:27:25 -0800 Subject: [PATCH 31/44] style: satisfy linting --- src/array_api_stubs/_draft/fft.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index eb9929e0d..3681cf8bc 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -650,7 +650,9 @@ def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) - """ -def ifftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: +def ifftshift( + x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None +) -> array: """ Inverse of ``fftshift``. From 9f208f65194d42a100c5e77f153f1e96a77ebc03 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 02:52:06 -0800 Subject: [PATCH 32/44] Update copy for `fftn` --- src/array_api_stubs/_2022_12/fft.py | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 2cb540120..59c579a2d 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -37,7 +37,7 @@ def fft( x: array input array. Should have a complex-valued floating-point data type. n: Optional[int] - number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. @@ -86,7 +86,7 @@ def ifft( x: array input array. Should have a complex-valued floating-point data type. n: Optional[int] - number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. @@ -135,22 +135,17 @@ def fftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the output. If + number of elements in the transformed axes (dimensions) of the output array. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -165,7 +160,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. Notes ----- From 9a6fcc714b71a48ba50352998e4d013c1bbd5323 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 03:02:01 -0800 Subject: [PATCH 33/44] Update copy for `ifftn` --- src/array_api_stubs/_2022_12/fft.py | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 59c579a2d..9d3cf7879 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -188,22 +188,17 @@ def ifftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the output. If + number of elements in the transformed axes (dimensions) of the output array. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. - - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] specify the normalization mode. Should be one of the following modes: @@ -218,7 +213,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. Notes ----- From 454ded734f9e8b4a0ba13b4ff81394f8a6e07321 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 03:09:05 -0800 Subject: [PATCH 34/44] Update copy --- src/array_api_stubs/_2022_12/fft.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 9d3cf7879..fd5533daf 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -37,7 +37,7 @@ def fft( x: array input array. Should have a complex-valued floating-point data type. n: Optional[int] - number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. @@ -86,7 +86,7 @@ def ifft( x: array input array. Should have a complex-valued floating-point data type. n: Optional[int] - number of elements in the transformed axis of the output array. Let ``M`` be the size of the input array along the axis (dimension) specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. @@ -135,7 +135,7 @@ def fftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - number of elements in the transformed axes (dimensions) of the output array. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. @@ -188,7 +188,7 @@ def ifftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - number of elements in the transformed axes (dimensions) of the output array. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. From 21e284039d57cb160168c256ca42222bfc558a6f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 03:16:29 -0800 Subject: [PATCH 35/44] Update copy for `rfft` --- src/array_api_stubs/_2022_12/fft.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index fd5533daf..847f01f01 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -240,19 +240,16 @@ def rfft( ---------- x: array input array. Must have a real-valued floating-point data type. - n: int - length of the transformed axis of the **input**. If ``n`` is not ``None`` and - - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``x.shape[axis]//2 + 1``. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -265,7 +262,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. Notes ----- From 22d354a469e66bddc37ac7f2e791e92fc056ec4b Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 03:43:20 -0800 Subject: [PATCH 36/44] Update copy for `irfft` --- src/array_api_stubs/_2022_12/fft.py | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 847f01f01..b91f0462a 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -234,7 +234,7 @@ def rfft( Computes the one-dimensional discrete Fourier transform for real-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent length. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- @@ -283,25 +283,22 @@ def irfft( Computes the one-dimensional inverse of ``rfft`` for complex-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent length. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the **output**. If ``n`` is not ``None`` and + n: Optional[int] + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. - - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to size ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -314,11 +311,13 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- + - In order to return an array having an odd number of elements along the transformed axis, the function must be provided an odd integer for ``n``. + .. versionadded:: 2022.12 """ From 4d0160c9cc24bd7308447c4b3bd2f00454666bfb Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 03:58:51 -0800 Subject: [PATCH 37/44] Update copy for `rfftn` --- src/array_api_stubs/_2022_12/fft.py | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index b91f0462a..ff19c1f32 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -341,23 +341,17 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **input**. If ``s`` is not ``None`` and + number of elements over which to compute the transform along axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - If ``s`` is ``None`` (not provided), the full lengths of the input array along each transformed axis (dimension) are used (no padding/trimming). The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``x.shape[axes[-1]]//2 + 1``. - - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -372,7 +366,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must equal ``s[-1]//2 + 1``, if ``s[-1]`` is given and not ``-1``, or `x.shape[axes[-1]]//2 + 1` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``s[i]`` is given and not ``-1``, or ``x.shape[axes[i]]`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the last transformed axis which must have size ``s[-1]//2 + 1`` and the remaining transformed axes which must have size ``s[i]``. Notes ----- From 9d90326b0e42ac6bbccdbea52cc3448a34b1dd51 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:28:31 -0800 Subject: [PATCH 38/44] Update copy for `irfftn` --- src/array_api_stubs/_2022_12/fft.py | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index ff19c1f32..50d76ffa5 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -394,23 +394,17 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **output**. If ``s`` is not ``None``, ``n=s[i]`` is the number of input points used along the transformed axis (dimension) ``i``, except for the last transformed axis, where ``n=s[-1]//2 + 1`` points of the input are used. If + number of elements along the transformed axes (dimensions) specified by ``axes`` in the **output array**. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``, except for the last transformed axis in which ``s[i]`` equals ``2*(M[i]-1)``. For each ``i``, let ``n`` equal ``s[i]``, except for the last transformed axis in which ``n`` equals ``s[i]//2+1``. - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - - ``s[i]`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). + - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array must be zero-padded to size ``n``. + - If ``n`` is less than ``M[i]``, axis ``i`` of the input array must be trimmed to size ``n``. + - If ``n`` equals ``M[i]`` or ``-1``, all elements along the axis ``i`` of the input array must be used when computing the transform. - If ``s`` is ``None`` (not provided), the full length of the input array along each transformed axis (dimension) must be used. The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``2*(x.shape[axes[-1]] - 1)``. - - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. - - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. - - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -425,11 +419,13 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given and not ``-1``, or ``2*(x.shape[axes[-1]] - 1)`` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``given and not ``-1``, or ``x.shape[i]``. Therefore, to get an odd number of output points along the last transformed axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the transformed axes which must have size ``s[i]``. Notes ----- + - In order to return an array having an odd number of elements along the last transformed axis, the function must be provided an odd integer for ``s[-1]``. + .. versionadded:: 2022.12 """ From 8f2b6df579050c0f8a72f81d35f94720a579ebd7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:34:35 -0800 Subject: [PATCH 39/44] Update copy for `hfft` --- src/array_api_stubs/_2022_12/fft.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 50d76ffa5..bc637a5d4 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -445,19 +445,16 @@ def hfft( ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the **output**. If ``n`` is not ``None`` and - - - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + n: Optional[int] + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to length ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -470,7 +467,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- From 43e96fa97d1fcbfda8c1a3c2c9e77af1d471b45f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:38:47 -0800 Subject: [PATCH 40/44] Update copy for `ihfft` --- src/array_api_stubs/_2022_12/fft.py | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index bc637a5d4..878c54ac6 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -491,19 +491,16 @@ def ihfft( ---------- x: array input array. Must have a real-valued floating-point data type. - n: int - length of the transformed axis of the **input**. If ``n`` is not ``None`` and - - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis must equal ``x.shape[axis]//2 + 1``. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -516,7 +513,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. Notes ----- From c1800344355267a1ad2e63aa7a64fdc4c1d1168e Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:44:10 -0800 Subject: [PATCH 41/44] Update copy --- src/array_api_stubs/_2022_12/fft.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 878c54ac6..30bcfb94b 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -526,7 +526,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar """ Computes the discrete Fourier transform sample frequencies. - For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: + For a Fourier transform of length ``n`` and length unit of ``d``, the frequencies are described as: .. code-block:: @@ -558,7 +558,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a """ Computes the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). - For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: + For a Fourier transform of length ``n`` and length unit of ``d``, the frequencies are described as: .. code-block:: @@ -590,7 +590,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ - Shift the zero-frequency component to the center of the spectrum. + Shifts the zero-frequency component to the center of the spectrum. This function swaps half-spaces for all axes (dimensions) specified by ``axes``. @@ -607,7 +607,7 @@ def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) - Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. + the shifted array. The returned array must have the same data type and shape as ``x``. Notes ----- @@ -635,7 +635,7 @@ def ifftshift( Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. + the shifted array. The returned array must have the same data type and shape as ``x``. Notes ----- From 9f1c20e058553a6ac4ce2c523b95b9a30a76eda7 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:44:29 -0800 Subject: [PATCH 42/44] Copy changes over to draft specification --- src/array_api_stubs/_draft/fft.py | 208 +++++++++++++----------------- 1 file changed, 87 insertions(+), 121 deletions(-) diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 3681cf8bc..30bcfb94b 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -30,24 +30,22 @@ def fft( Computes the one-dimensional discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (length, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the output. If + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -60,7 +58,7 @@ def fft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- @@ -81,24 +79,22 @@ def ifft( Computes the one-dimensional inverse discrete Fourier transform. .. note:: - Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same (length, axis, and normalization mode). + Applying the one-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``ifft(fft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (number of elements, axis, and normalization mode). Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the output. If + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - ``n`` is not provided, the full length of the input array along ``axis`` must be used. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -111,7 +107,7 @@ def ifft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have the same data type as ``x``. The length along the transformed axis is ``n``, if given, or the length of the input along ``axis`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- @@ -139,22 +135,17 @@ def fftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the output. If - - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -169,7 +160,7 @@ def fftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. Notes ----- @@ -197,22 +188,17 @@ def ifftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the output. If - - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - ``s`` is not provided, the length of each transformed axis (dimension) in the output array must equal the length of the corresponding axis in the input array. + number of elements over which to compute the transform along the axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] specify the normalization mode. Should be one of the following modes: @@ -227,7 +213,7 @@ def ifftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have the same data type as ``x``. The length along each transformed axis ``i`` is ``s[i]``, if ``s`` is given and ``s[i]`` is not ``-1``, or the length of the corresponding axis of the input array otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimensions) specified by ``axes``. The returned array must have the same data type as ``x`` and must have the same shape as ``x``, except for the axes specified by ``axes`` which must have size ``s[i]``. Notes ----- @@ -248,25 +234,22 @@ def rfft( Computes the one-dimensional discrete Fourier transform for real-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent length. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- x: array input array. Must have a real-valued floating-point data type. - n: int - length of the transformed axis of the **input**. If ``n`` is not ``None`` and - - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``x.shape[axis]//2 + 1``. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -279,7 +262,7 @@ def rfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. Notes ----- @@ -300,25 +283,22 @@ def irfft( Computes the one-dimensional inverse of ``rfft`` for complex-valued input. .. note:: - Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and normalization mode) and consistent length. + Applying the one-dimensional inverse discrete Fourier transform for real-valued input to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy (i.e., ``irfft(rfft(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axis and and normalization mode) and consistent values for the number of elements over which to compute the transforms. Parameters ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the **output**. If ``n`` is not ``None`` and + n: Optional[int] + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. - - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. - - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to size ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -331,11 +311,13 @@ def irfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. Therefore, to get an odd number of output points along ``axis``, ``n`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- + - In order to return an array having an odd number of elements along the transformed axis, the function must be provided an odd integer for ``n``. + .. versionadded:: 2022.12 """ @@ -359,23 +341,17 @@ def rfftn( x: array input array. Must have a real-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **input**. If ``s`` is not ``None`` and - - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``s[i]``. - - ``s[i]`` is less than the length of the input array along a corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``s[i]``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). - - If ``s`` is ``None`` (not provided), the full lengths of the input array along each transformed axis (dimension) are used (no padding/trimming). The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``x.shape[axes[-1]]//2 + 1``. + number of elements over which to compute the transform along axes (dimensions) specified by ``axes``. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. + - If ``s[i]`` is greater than ``M[i]``, axis ``i`` must be zero-padded to size ``s[i]``. + - If ``s[i]`` is less than ``M[i]``, axis ``i`` must be trimmed to size ``s[i]``. + - If ``s[i]`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` must be used when computing the transform. - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. - - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -390,7 +366,7 @@ def rfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the last transformed axis must equal ``s[-1]//2 + 1``, if ``s[-1]`` is given and not ``-1``, or `x.shape[axes[-1]]//2 + 1` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``s[i]`` is given and not ``-1``, or ``x.shape[axes[i]]`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the last transformed axis which must have size ``s[-1]//2 + 1`` and the remaining transformed axes which must have size ``s[i]``. Notes ----- @@ -418,23 +394,17 @@ def irfftn( x: array input array. Should have a complex-valued floating-point data type. s: Optional[Sequence[int]] - length of each transformed axis of the **output**. If ``s`` is not ``None``, ``n=s[i]`` is the number of input points used along the transformed axis (dimension) ``i``, except for the last transformed axis, where ``n=s[-1]//2 + 1`` points of the input are used. If - - - ``s[i]`` is greater than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is zero-padded to length ``n``. - - ``s[i]`` is less than the length of the input array along the corresponding axis (dimension) ``i``, the input array along the axis ``i`` is trimmed to length ``n``. - - ``s[i]`` is ``-1``, the whole input array along the axis ``i`` is used (no padding/trimming). + number of elements along the transformed axes (dimensions) specified by ``axes`` in the **output array**. Let ``i`` be the index of the nth axis specified by ``axes`` and ``M[i]`` be the size of the input array along axis ``i``. When ``s`` is ``None``, the function must set ``s`` equal to a sequence of integers, such that, for all ``i``, ``s[i]`` equals ``M[i]``, except for the last transformed axis in which ``s[i]`` equals ``2*(M[i]-1)``. For each ``i``, let ``n`` equal ``s[i]``, except for the last transformed axis in which ``n`` equals ``s[i]//2+1``. - If ``s`` is ``None`` (not provided), the full length of the input array along each transformed axis (dimension) must be used. The length of the output array must equal the length of the corresponding axis in the input array, except for the last transformed axis which must equal ``2*(x.shape[axes[-1]] - 1)``. + - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array must be zero-padded to size ``n``. + - If ``n`` is less than ``M[i]``, axis ``i`` of the input array must be trimmed to size ``n``. + - If ``n`` equals ``M[i]`` or ``-1``, all elements along the axis ``i`` of the input array must be used when computing the transform. - If ``s`` is not ``None``, ``axes`` must not be ``None`` either, and ``s[i]`` corresponds to the length along the transformed axis specified by ``axes[i]``. - - Default: ``None``. + If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] - axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed. + axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. - - Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -449,11 +419,13 @@ def irfftn( Returns ------- out: array - an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the last transformed axis is ``s[-1]``, if given and not ``-1``, or ``2*(x.shape[axes[-1]] - 1)`` otherwise. The lengths along the remaining transformed axes ``i`` must equal ``s[i]``, if ``given and not ``-1``, or ``x.shape[i]``. Therefore, to get an odd number of output points along the last transformed axis, ``s`` must be specified. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axes (dimension) specified by ``axes``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the transformed axes which must have size ``s[i]``. Notes ----- + - In order to return an array having an odd number of elements along the last transformed axis, the function must be provided an odd integer for ``s[-1]``. + .. versionadded:: 2022.12 """ @@ -473,19 +445,16 @@ def hfft( ---------- x: array input array. Should have a complex-valued floating-point data type. - n: int - length of the transformed axis of the **output**. If ``n`` is not ``None`` and - - - ``n//2+1`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n//2+1``. - - ``n//2+1`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n//2+1``. + n: Optional[int] + number of elements along the transformed axis (dimension) specified by ``axis`` in the **output array**. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``2*(M-1)``. - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis of the output must equal ``2*(x.shape[axis] - 1)``. + - If ``n//2+1`` is greater than ``M``, the axis of the input array specified by ``axis`` must be zero-padded to length ``n//2+1``. + - If ``n//2+1`` is less than ``M``, the axis of the input array specified by ``axis`` must be trimmed to size ``n//2+1``. + - If ``n//2+1`` equals ``M``, all elements along the axis of the input array specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -498,7 +467,7 @@ def hfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The length along the transformed axis is ``n``, if given, or ``2*(x.shape[axis] - 1)`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a real-valued floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``complex128``, then the returned array must have a ``float64`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n``. Notes ----- @@ -522,19 +491,16 @@ def ihfft( ---------- x: array input array. Must have a real-valued floating-point data type. - n: int - length of the transformed axis of the **input**. If ``n`` is not ``None`` and + n: Optional[int] + number of elements over which to compute the transform along the axis (dimension) specified by ``axis``. Let ``M`` be the size of the input array along the axis specified by ``axis``. When ``n`` is ``None``, the function must set ``n`` equal to ``M``. - - ``n`` is greater than the length of the input array along ``axis``, the input array along ``axis`` is zero-padded to length ``n``. - - ``n`` is less than the length of the input array along ``axis``, the input array along ``axis`` is trimmed to length ``n``. - - If ``n`` is ``None`` (not provided), the full length of the input array along ``axis`` must be used. The length along the transformed axis must equal ``x.shape[axis]//2 + 1``. + - If ``n`` is greater than ``M``, the axis specified by ``axis`` must be zero-padded to size ``n``. + - If ``n`` is less than ``M``, the axis specified by ``axis`` must be trimmed to size ``n``. + - If ``n`` equals ``M``, all elements along the axis specified by ``axis`` must be used when computing the transform. Default: ``None``. axis: int - axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used. - - Default: ``-1``. + axis (dimension) of the input array over which to compute the transform. A valid ``axis`` must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an ``axis`` is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). Default: ``-1``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: @@ -547,7 +513,7 @@ def ihfft( Returns ------- out: array - an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The length along the transformed axis is ``n//2 + 1`` if ``n`` is given, or ``x.shape[axis]//2 + 1`` otherwise. The lengths along the un-transformed axes remain unchanged. + an array transformed along the axis (dimension) specified by ``axis``. The returned array must have a complex floating-point data type whose precision matches the precision of ``x`` (e.g., if ``x`` is ``float64``, then the returned array must have a ``complex128`` data type). The returned array must have the same shape as ``x``, except for the axis specified by ``axis`` which must have size ``n//2 + 1``. Notes ----- @@ -560,7 +526,7 @@ def fftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> ar """ Computes the discrete Fourier transform sample frequencies. - For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: + For a Fourier transform of length ``n`` and length unit of ``d``, the frequencies are described as: .. code-block:: @@ -592,7 +558,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a """ Computes the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``). - For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as: + For a Fourier transform of length ``n`` and length unit of ``d``, the frequencies are described as: .. code-block:: @@ -624,7 +590,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0, device: Optional[device] = None) -> a def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) -> array: """ - Shift the zero-frequency component to the center of the spectrum. + Shifts the zero-frequency component to the center of the spectrum. This function swaps half-spaces for all axes (dimensions) specified by ``axes``. @@ -641,7 +607,7 @@ def fftshift(x: array, /, *, axes: Optional[Union[int, Sequence[int]]] = None) - Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. + the shifted array. The returned array must have the same data type and shape as ``x``. Notes ----- @@ -669,7 +635,7 @@ def ifftshift( Returns ------- out: array - the shifted array. The returned array must have the same data type as ``x``. The returned array must have the same shape as the input array ``x``. + the shifted array. The returned array must have the same data type and shape as ``x``. Notes ----- From b97bb34a959fbd977b0ddd7df4355a7ddd094b8a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:56:27 -0800 Subject: [PATCH 43/44] Update copy --- src/array_api_stubs/_2022_12/fft.py | 2 +- src/array_api_stubs/_draft/fft.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 30bcfb94b..860cb2c0a 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -398,7 +398,7 @@ def irfftn( - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array must be zero-padded to size ``n``. - If ``n`` is less than ``M[i]``, axis ``i`` of the input array must be trimmed to size ``n``. - - If ``n`` equals ``M[i]`` or ``-1``, all elements along the axis ``i`` of the input array must be used when computing the transform. + - If ``n`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` of the input array must be used when computing the transform. If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 30bcfb94b..860cb2c0a 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -398,7 +398,7 @@ def irfftn( - If ``n`` is greater than ``M[i]``, axis ``i`` of the input array must be zero-padded to size ``n``. - If ``n`` is less than ``M[i]``, axis ``i`` of the input array must be trimmed to size ``n``. - - If ``n`` equals ``M[i]`` or ``-1``, all elements along the axis ``i`` of the input array must be used when computing the transform. + - If ``n`` equals ``M[i]`` or ``-1``, all elements along axis ``i`` of the input array must be used when computing the transform. If ``s`` is not ``None``, ``axes`` must not be ``None``. Default: ``None``. axes: Optional[Sequence[int]] From 0a7df554d9e8158b8c997adc3a68ffa2bc55f610 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Thu, 8 Feb 2024 04:57:07 -0800 Subject: [PATCH 44/44] Fix indentation --- src/array_api_stubs/_2022_12/fft.py | 2 +- src/array_api_stubs/_draft/fft.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/array_api_stubs/_2022_12/fft.py b/src/array_api_stubs/_2022_12/fft.py index 860cb2c0a..f79aa155e 100644 --- a/src/array_api_stubs/_2022_12/fft.py +++ b/src/array_api_stubs/_2022_12/fft.py @@ -404,7 +404,7 @@ def irfftn( axes: Optional[Sequence[int]] axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: diff --git a/src/array_api_stubs/_draft/fft.py b/src/array_api_stubs/_draft/fft.py index 860cb2c0a..f79aa155e 100644 --- a/src/array_api_stubs/_draft/fft.py +++ b/src/array_api_stubs/_draft/fft.py @@ -404,7 +404,7 @@ def irfftn( axes: Optional[Sequence[int]] axes (dimensions) over which to compute the transform. A valid axis must be an integer on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If an axis is specified as a negative integer, the function must determine the axis along which to compute the transform by counting backward from the last dimension (where ``-1`` refers to the last dimension). - If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. + If ``s`` is provided, the corresponding ``axes`` to be transformed must also be provided. If ``axes`` is ``None``, the function must compute the transform over all axes. Default: ``None``. norm: Literal['backward', 'ortho', 'forward'] normalization mode. Should be one of the following modes: