From 2f2f290c4494b3632494175dc4c785c55b8682b7 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Fri, 4 Jun 2021 00:54:00 -0500
Subject: [PATCH 01/30] Add all fft functions
---
.../fast_fourier_transform_functions.md | 670 ++++++++++++++++++
spec/extensions/index.rst | 1 +
2 files changed, 671 insertions(+)
create mode 100644 spec/extensions/fast_fourier_transform_functions.md
diff --git a/spec/extensions/fast_fourier_transform_functions.md b/spec/extensions/fast_fourier_transform_functions.md
new file mode 100644
index 000000000..3bac54db6
--- /dev/null
+++ b/spec/extensions/fast_fourier_transform_functions.md
@@ -0,0 +1,670 @@
+# Fast Fourier Transform Functions
+
+> Array API specification for fast fourier transform functions.
+
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
+
+- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) 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.
+- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+- Broadcasting semantics must follow the semantics defined in {ref}`broadcasting`.
+- Unless stated otherwise, functions must support the data types defined in {ref}`data-types`.
+- Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`.
+- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
+
+## Objects in API
+
+<!-- NOTE: please keep the functions in alphabetical order -->
+(function-fft)=
+### fft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the transformed axis of the output. If it is `None`, the length of the input along the axis given by the `axis` keyword. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axis indicated by the `axis` keyword.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-fft2)=
+### fft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
+
+Computes the two-dimensional discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If `axes` is not given and the length of `s` is different from 2.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-fftfreq)=
+### fftfreq(n, /, *, d=1.0)
+
+Returns the discrete Fourier Transform sample frequencies. For a Fourier Transform of length `n` and length unit of `d` the frequencies are described as:
+
+```
+f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
+f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+```
+
+#### Parameters
+
+- **n**: _int_
+
+ - Window length.
+
+- **d**: _float_
+
+ - Sample spacing between individual samples of the FFT input. Default: `1.0`.
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array of length `n` containing the sample frequencies.
+
+(function-fftn)=
+### fftn(a, /, *, s=None, axes=None, norm='backward')
+
+Computes the n-dimensional discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-fftshift)=
+### fftshift(x, /, *, axes=None)
+
+Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that `out[0]` is the Nyquist component only if the length of the input is even.
+
+#### Parameters
+
+- **x**: _<array>_
+
+ - Input array.
+
+- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to shift. If not specified, it shifts all axes. Default: `None`.
+
+#### Returns
+
+- **out**: _<array>_
+
+ - The shifted array.
+
+(function-hfft)=
+### hfft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional discrete Fourier Transform of a signal with Hermitian symmetry.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - A transformed array.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-ifft)=
+### ifft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional inverse discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the IFFT. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axis indicated by the `axis` keyword.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-ifft2)=
+### ifft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
+
+Computes the two-dimensional inverse discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If `axes` is not given and the length of `s` is different from 2.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-ifftn)=
+### ifftn(a, /, *, s=None, axes=None, norm='backward')
+
+Computes the n-dimensional inverse discrete Fourier Transform.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-ifftshift)=
+### ifftshift(x, /, *, axes=None)
+
+Inverse of `fftshift`.
+
+#### Parameters
+
+- **x**: _<array>_
+
+ - Input array.
+
+- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to calculate. If not specified, it shifts all axes. Default: `None`.
+
+#### Returns
+
+- **out**: _<array>_
+
+ - The shifted array.
+
+(function-ihfft)=
+### ihfft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional inverse discrete Fourier Transform of a signal with Hermitian symmetry.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - A transformed array.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-irfft)=
+### irfft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional inverse discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the real fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axis indicated by the `axis` keyword.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-irfft2)=
+### irfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
+
+Computes the two-dimensional inverse discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axes` keyword. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes used to compute the real fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If `axes` is not given and the length of `s` is different from 2.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-irfftn)=
+### irfftn(a, /, *, s=None, axes=None, norm='backward')
+
+Computes the n-dimensional inverse discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+
+(function-rfft)=
+### rfft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **n**: _int_
+
+ - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
+
+- **axis**: _int_
+
+ - Axis used to compute the real fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axis indicated by the `axis` keyword.
+
+#### Raises
+
+- If `axis` is larger than the last axis of `a`.
+
+(function-rfft2)=
+### rfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
+
+Computes the two-dimensional discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If `axes` is not given and the length of `s` is different from 2.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-rfftfreq)=
+### rfftfreq(n, /, *, d=1.0)
+
+Returns the discrete Fourier Transform sample frequencies. For a Fourier Transform of length `n` and length unit of `d` the frequencies are described as:
+
+```
+f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
+f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+```
+
+The Nyquist frequency component is considered to be positive.
+
+#### Parameters
+
+- **n**: _int_
+
+ - Window length.
+
+- **d**: _float_
+
+ - Sample spacing between individual samples of the FFT input. Default: `1.0`.
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array of length `n` containing the sample frequencies.
+
+(function-rfftn)=
+### rfftn(a, /, *, s=None, axes=None, norm='backward')
+
+Computes the n-dimensional discrete Fourier Transform for real-valued input.
+
+#### Parameters
+
+- **a**: _<array>_
+
+ - Input array.
+
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: No normalization.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: Normalize by `1/n`.
+
+ Default: `'backward'`
+
+#### Returns
+
+- **out**: _<array>_
+
+ - An array transformed along the axes indicated by the `axes` keyword.
+
+#### Raises
+
+- If `s` and `axes` have a different length.
+- If an element of `axes` is larger than the number of axes of `a`.
\ No newline at end of file
diff --git a/spec/extensions/index.rst b/spec/extensions/index.rst
index 1b3b7470f..23bdd727b 100644
--- a/spec/extensions/index.rst
+++ b/spec/extensions/index.rst
@@ -7,4 +7,5 @@ Extensions
:caption: Extensions
:maxdepth: 3
+ fast_fourier_transform_functions
linear_algebra_functions
From 287e6869a2ba6b08290966c41b77698b7e6e6ca0 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Tue, 8 Jun 2021 14:22:07 -0500
Subject: [PATCH 02/30] add consistency among the definitions and add some
minor fixes
---
...ions.md => fourier_transform_functions.md} | 122 +++++++++---------
spec/extensions/index.rst | 2 +-
2 files changed, 62 insertions(+), 62 deletions(-)
rename spec/extensions/{fast_fourier_transform_functions.md => fourier_transform_functions.md} (72%)
diff --git a/spec/extensions/fast_fourier_transform_functions.md b/spec/extensions/fourier_transform_functions.md
similarity index 72%
rename from spec/extensions/fast_fourier_transform_functions.md
rename to spec/extensions/fourier_transform_functions.md
index 3bac54db6..8dfcf2b5b 100644
--- a/spec/extensions/fast_fourier_transform_functions.md
+++ b/spec/extensions/fourier_transform_functions.md
@@ -1,6 +1,6 @@
-# Fast Fourier Transform Functions
+# Fourier transform Functions
-> Array API specification for fast fourier transform functions.
+> Array API specification for Fourier transform functions.
A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
@@ -17,7 +17,7 @@ A conforming implementation of the array API standard must provide and support t
(function-fft)=
### fft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier Transform.
+Computes the one-dimensional discrete Fourier transform.
#### Parameters
@@ -31,7 +31,7 @@ Computes the one-dimensional discrete Fourier Transform.
- **axis**: _int_
- - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -56,7 +56,7 @@ Computes the one-dimensional discrete Fourier Transform.
(function-fft2)=
### fft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-Computes the two-dimensional discrete Fourier Transform.
+Computes the two-dimensional discrete Fourier transform.
#### Parameters
@@ -66,11 +66,11 @@ Computes the two-dimensional discrete Fourier Transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+ - Axes over which to compute the Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
- **norm**: _str_
@@ -97,7 +97,7 @@ Computes the two-dimensional discrete Fourier Transform.
(function-fftfreq)=
### fftfreq(n, /, *, d=1.0)
-Returns the discrete Fourier Transform sample frequencies. For a Fourier Transform of length `n` and length unit of `d` the frequencies are described as:
+Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
```
f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
@@ -112,7 +112,7 @@ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
- **d**: _float_
- - Sample spacing between individual samples of the FFT input. Default: `1.0`.
+ - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
#### Returns
@@ -123,7 +123,7 @@ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
(function-fftn)=
### fftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional discrete Fourier Transform.
+Computes the n-dimensional discrete Fourier transform.
#### Parameters
@@ -133,11 +133,11 @@ Computes the n-dimensional discrete Fourier Transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
- **norm**: _str_
@@ -184,7 +184,7 @@ Reorders n-dimensional FTT data to have negative frequency terms first. In this
(function-hfft)=
### hfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier Transform of a signal with Hermitian symmetry.
+Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
#### Parameters
@@ -194,11 +194,11 @@ Computes the one-dimensional discrete Fourier Transform of a signal with Hermiti
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -223,7 +223,7 @@ Computes the one-dimensional discrete Fourier Transform of a signal with Hermiti
(function-ifft)=
### ifft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier Transform.
+Computes the one-dimensional inverse discrete Fourier transform.
#### Parameters
@@ -233,19 +233,19 @@ Computes the one-dimensional inverse discrete Fourier Transform.
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the IFFT. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the IFourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -262,7 +262,7 @@ Computes the one-dimensional inverse discrete Fourier Transform.
(function-ifft2)=
### ifft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-Computes the two-dimensional inverse discrete Fourier Transform.
+Computes the two-dimensional inverse discrete Fourier transform.
#### Parameters
@@ -272,19 +272,19 @@ Computes the two-dimensional inverse discrete Fourier Transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+ - Axes over which to compute the inverse Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -303,7 +303,7 @@ Computes the two-dimensional inverse discrete Fourier Transform.
(function-ifftn)=
### ifftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional inverse discrete Fourier Transform.
+Computes the n-dimensional inverse discrete Fourier transform.
#### Parameters
@@ -313,19 +313,19 @@ Computes the n-dimensional inverse discrete Fourier Transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -364,7 +364,7 @@ Inverse of `fftshift`.
(function-ihfft)=
### ihfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier Transform of a signal with Hermitian symmetry.
+Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
#### Parameters
@@ -374,19 +374,19 @@ Computes the one-dimensional inverse discrete Fourier Transform of a signal with
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -403,7 +403,7 @@ Computes the one-dimensional inverse discrete Fourier Transform of a signal with
(function-irfft)=
### irfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier Transform for real-valued input.
+Computes the one-dimensional inverse discrete Fourier transform for real-valued input.
#### Parameters
@@ -413,19 +413,19 @@ Computes the one-dimensional inverse discrete Fourier Transform for real-valued
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the real fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -442,7 +442,7 @@ Computes the one-dimensional inverse discrete Fourier Transform for real-valued
(function-irfft2)=
### irfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-Computes the two-dimensional inverse discrete Fourier Transform for real-valued input.
+Computes the two-dimensional inverse discrete Fourier transform for real-valued input.
#### Parameters
@@ -452,19 +452,19 @@ Computes the two-dimensional inverse discrete Fourier Transform for real-valued
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axes` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axes` keyword. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes used to compute the real fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+ - Axes used to compute the real Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -483,7 +483,7 @@ Computes the two-dimensional inverse discrete Fourier Transform for real-valued
(function-irfftn)=
### irfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional inverse discrete Fourier Transform for real-valued input.
+Computes the n-dimensional inverse discrete Fourier transform for real-valued input.
#### Parameters
@@ -493,19 +493,19 @@ Computes the n-dimensional inverse discrete Fourier Transform for real-valued in
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the inverse fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: No normalization.
+ - `'backward'`: Normalize by `1/n`.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+ - `'forward'`: No normalization.
Default: `'backward'`
@@ -524,7 +524,7 @@ Computes the n-dimensional inverse discrete Fourier Transform for real-valued in
(function-rfft)=
### rfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier Transform for real-valued input.
+Computes the one-dimensional discrete Fourier transform for real-valued input.
#### Parameters
@@ -534,11 +534,11 @@ Computes the one-dimensional discrete Fourier Transform for real-valued input.
- **n**: _int_
- - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real FFT. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
+ - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
- **axis**: _int_
- - Axis used to compute the real fast fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -563,7 +563,7 @@ Computes the one-dimensional discrete Fourier Transform for real-valued input.
(function-rfft2)=
### rfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-Computes the two-dimensional discrete Fourier Transform for real-valued input.
+Computes the two-dimensional discrete Fourier transform for real-valued input.
#### Parameters
@@ -573,11 +573,11 @@ Computes the two-dimensional discrete Fourier Transform for real-valued input.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the fast fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
+ - Axes over which to compute the Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
- **norm**: _str_
@@ -604,7 +604,7 @@ Computes the two-dimensional discrete Fourier Transform for real-valued input.
(function-rfftfreq)=
### rfftfreq(n, /, *, d=1.0)
-Returns the discrete Fourier Transform sample frequencies. For a Fourier Transform of length `n` and length unit of `d` the frequencies are described as:
+Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
```
f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
@@ -621,7 +621,7 @@ The Nyquist frequency component is considered to be positive.
- **d**: _float_
- - Sample spacing between individual samples of the FFT input. Default: `1.0`.
+ - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
#### Returns
@@ -632,7 +632,7 @@ The Nyquist frequency component is considered to be positive.
(function-rfftn)=
### rfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional discrete Fourier Transform for real-valued input.
+Computes the n-dimensional discrete Fourier transform for real-valued input.
#### Parameters
@@ -642,11 +642,11 @@ Computes the n-dimensional discrete Fourier Transform for real-valued input.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real fast fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the fast fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
- **norm**: _str_
diff --git a/spec/extensions/index.rst b/spec/extensions/index.rst
index 23bdd727b..7fe36f3ad 100644
--- a/spec/extensions/index.rst
+++ b/spec/extensions/index.rst
@@ -7,5 +7,5 @@ Extensions
:caption: Extensions
:maxdepth: 3
- fast_fourier_transform_functions
+ fourier_transform_functions
linear_algebra_functions
From 07d0654a339b5d5a660471b9d75e1dcf5ba960cd Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 24 Jun 2021 14:36:58 -0500
Subject: [PATCH 03/30] Remove *fft2 functions
---
.../extensions/fourier_transform_functions.md | 164 ------------------
1 file changed, 164 deletions(-)
diff --git a/spec/extensions/fourier_transform_functions.md b/spec/extensions/fourier_transform_functions.md
index 8dfcf2b5b..5153b354e 100644
--- a/spec/extensions/fourier_transform_functions.md
+++ b/spec/extensions/fourier_transform_functions.md
@@ -53,47 +53,6 @@ Computes the one-dimensional discrete Fourier transform.
- If `axis` is larger than the last axis of `a`.
-(function-fft2)=
-### fft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-
-Computes the two-dimensional discrete Fourier transform.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have a different length.
-- If `axes` is not given and the length of `s` is different from 2.
-- If an element of `axes` is larger than the number of axes of `a`.
-
(function-fftfreq)=
### fftfreq(n, /, *, d=1.0)
@@ -259,47 +218,6 @@ Computes the one-dimensional inverse discrete Fourier transform.
- If `axis` is larger than the last axis of `a`.
-(function-ifft2)=
-### ifft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-
-Computes the two-dimensional inverse discrete Fourier transform.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the inverse Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have a different length.
-- If `axes` is not given and the length of `s` is different from 2.
-- If an element of `axes` is larger than the number of axes of `a`.
-
(function-ifftn)=
### ifftn(a, /, *, s=None, axes=None, norm='backward')
@@ -439,47 +357,6 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
- If `axis` is larger than the last axis of `a`.
-(function-irfft2)=
-### irfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-
-Computes the two-dimensional inverse discrete Fourier transform for real-valued input.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axes` keyword. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes used to compute the real Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have a different length.
-- If `axes` is not given and the length of `s` is different from 2.
-- If an element of `axes` is larger than the number of axes of `a`.
-
(function-irfftn)=
### irfftn(a, /, *, s=None, axes=None, norm='backward')
@@ -560,47 +437,6 @@ Computes the one-dimensional discrete Fourier transform for real-valued input.
- If `axis` is larger than the last axis of `a`.
-(function-rfft2)=
-### rfft2(a, /, *, s=None, axes=(-2, -1), norm='backward')
-
-Computes the two-dimensional discrete Fourier transform for real-valued input.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the Fourier transform. If it is not specified, the last two axes are used. Default: `(-2, -1)`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have a different length.
-- If `axes` is not given and the length of `s` is different from 2.
-- If an element of `axes` is larger than the number of axes of `a`.
-
(function-rfftfreq)=
### rfftfreq(n, /, *, d=1.0)
From 3a367b7ee704ad5d5eaaca6b80e1dbb6e4267ebe Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:39:57 -0500
Subject: [PATCH 04/30] Fix config.yml
---
.circleci/config.yml | 30 ++++++++++++++++--------------
1 file changed, 16 insertions(+), 14 deletions(-)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 4b424507c..1809d6bdc 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -8,18 +8,20 @@ _defaults: &defaults
- image: circleci/python:3.7.0
working_directory: ~/repo
-jobs:
- build_page:
- <<: *defaults
- steps:
- - attach_workspace:
- at: ~/
+workflows:
+ build:
+ jobs:
+ - build_page:
+ <<: *defaults
+ steps:
+ - attach_workspace:
+ at: ~/
- - run:
- name: build docs
- no_output_timeout: 25m
- command: |
- pip install -r requirements.txt
- sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- - store_artifacts:
- path: build/latest
+ - run:
+ name: build docs
+ no_output_timeout: 25m
+ command: |
+ pip install -r requirements.txt
+ sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
+ - store_artifacts:
+ path: build/latest
From 5265b6f2adc196736bbb8400fb7fdaff1c03c4e8 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez Gacha <steff456@users.noreply.github.com>
Date: Thu, 8 Jul 2021 15:42:38 -0500
Subject: [PATCH 05/30] Add .circleci/config.yml
From 8871a29b4d452569b8abf6c4c788086074429bde Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:44:10 -0500
Subject: [PATCH 06/30] As example
---
.circleci/config.yml | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 1809d6bdc..4b424507c 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -8,20 +8,18 @@ _defaults: &defaults
- image: circleci/python:3.7.0
working_directory: ~/repo
-workflows:
- build:
- jobs:
- - build_page:
- <<: *defaults
- steps:
- - attach_workspace:
- at: ~/
+jobs:
+ build_page:
+ <<: *defaults
+ steps:
+ - attach_workspace:
+ at: ~/
- - run:
- name: build docs
- no_output_timeout: 25m
- command: |
- pip install -r requirements.txt
- sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- - store_artifacts:
- path: build/latest
+ - run:
+ name: build docs
+ no_output_timeout: 25m
+ command: |
+ pip install -r requirements.txt
+ sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
+ - store_artifacts:
+ path: build/latest
From 35e1cdb50e5f39eb2f6e855dc046b735ead21e3c Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:45:42 -0500
Subject: [PATCH 07/30] Add workflows
---
.circleci/config.yml | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 4b424507c..b6fcfeaaa 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -23,3 +23,9 @@ jobs:
sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- store_artifacts:
path: build/latest
+
+workflows:
+ version: 2
+ default:
+ jobs:
+ - build_page
From f3757655c5dd77acaa04cf414f59f3fc2dd89172 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:46:55 -0500
Subject: [PATCH 08/30] add pwd
---
.circleci/config.yml | 1 +
1 file changed, 1 insertion(+)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index b6fcfeaaa..38ad92187 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -19,6 +19,7 @@ jobs:
name: build docs
no_output_timeout: 25m
command: |
+ pwd
pip install -r requirements.txt
sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- store_artifacts:
From 34beefe2420ebc8c21af1bf2586e126476a9656f Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:47:34 -0500
Subject: [PATCH 09/30] add ls
---
.circleci/config.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 38ad92187..665f0daeb 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -19,7 +19,7 @@ jobs:
name: build docs
no_output_timeout: 25m
command: |
- pwd
+ ls
pip install -r requirements.txt
sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- store_artifacts:
From 2718bfc15539c6ad14be8592794aa7b95aff82f9 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:49:29 -0500
Subject: [PATCH 10/30] Checkout
---
.circleci/config.yml | 2 ++
1 file changed, 2 insertions(+)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 665f0daeb..4f3a78c1d 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -12,6 +12,8 @@ jobs:
build_page:
<<: *defaults
steps:
+ - checkout
+
- attach_workspace:
at: ~/
From cebb3e3206af62b393808d9c008fc5a15bf9bb1f Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:50:29 -0500
Subject: [PATCH 11/30] add --user
---
.circleci/config.yml | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 4f3a78c1d..1cbeab826 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -21,8 +21,7 @@ jobs:
name: build docs
no_output_timeout: 25m
command: |
- ls
- pip install -r requirements.txt
+ pip install --user -r requirements.txt
sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- store_artifacts:
path: build/latest
From ce6df71e9cbf0c788e52232934644a9924e005a0 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:51:20 -0500
Subject: [PATCH 12/30] sudo
---
.circleci/config.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.circleci/config.yml b/.circleci/config.yml
index 1cbeab826..f0471e873 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -21,7 +21,7 @@ jobs:
name: build docs
no_output_timeout: 25m
command: |
- pip install --user -r requirements.txt
+ sudo pip install -r requirements.txt
sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
- store_artifacts:
path: build/latest
From 3fc0ba0f675b325d05156972901de8705fc892f0 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:57:34 -0500
Subject: [PATCH 13/30] add preview
---
.github/workflows/preview.yml | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
create mode 100644 .github/workflows/preview.yml
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
new file mode 100644
index 000000000..ced637494
--- /dev/null
+++ b/.github/workflows/preview.yml
@@ -0,0 +1,17 @@
+on: [status]
+jobs:
+ circleci_artifacts_redirector_job:
+ runs-on: ubuntu-latest
+ name: Run CircleCI artifacts redirector
+ steps:
+ - name: GitHub Action step
+ id: step1
+ uses: larsoner/circleci-artifacts-redirector-action@master
+ with:
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+ artifact-path: 0/build/latest/index.html
+ circleci-jobs: build_page
+ job-title: Check the rendered docs here!
+ - name: Check the URL
+ run: |
+ curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA
\ No newline at end of file
From c363916c695b4cfab04db1b65f97e3eeacc90fa6 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 8 Jul 2021 15:58:56 -0500
Subject: [PATCH 14/30] change name
---
.github/workflows/preview.yml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
index ced637494..46e9a1ef9 100644
--- a/.github/workflows/preview.yml
+++ b/.github/workflows/preview.yml
@@ -12,6 +12,6 @@ jobs:
artifact-path: 0/build/latest/index.html
circleci-jobs: build_page
job-title: Check the rendered docs here!
- - name: Check the URL
+ - name: Array API preview
run: |
curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA
\ No newline at end of file
From 7e720c8bbb1c911d386b202bdf6da718c7ac96a9 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Mon, 19 Jul 2021 09:56:57 -0500
Subject: [PATCH 15/30] Add review changes
---
.../extensions/fourier_transform_functions.md | 281 +++++++++---------
1 file changed, 140 insertions(+), 141 deletions(-)
diff --git a/spec/extensions/fourier_transform_functions.md b/spec/extensions/fourier_transform_functions.md
index 5153b354e..6681e2597 100644
--- a/spec/extensions/fourier_transform_functions.md
+++ b/spec/extensions/fourier_transform_functions.md
@@ -13,11 +13,11 @@ A conforming implementation of the array API standard must provide and support t
## Objects in API
-<!-- NOTE: please keep the functions in alphabetical order -->
+<!-- NOTE: please keep the functions and their inverse together -->
(function-fft)=
### fft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier transform.
+Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `fft(ifft(a)) == a`.
#### Parameters
@@ -27,7 +27,7 @@ Computes the one-dimensional discrete Fourier transform.
- **n**: _int_
- - Length of the transformed axis of the output. If it is `None`, the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
@@ -51,33 +51,46 @@ Computes the one-dimensional discrete Fourier transform.
#### Raises
-- If `axis` is larger than the last axis of `a`.
+- If `axis` is not a valid axis of `a`.
-(function-fftfreq)=
-### fftfreq(n, /, *, d=1.0)
-
-Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
+(function-ifft)=
+### ifft(a, /, *, n=None, axis=-1, norm='backward')
-```
-f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
-f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
-```
+Computes the one-dimensional inverse discrete Fourier transform.
#### Parameters
+- **a**: _<array>_
+
+ - Input array.
+
- **n**: _int_
- - Window length.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
-- **d**: _float_
+- **axis**: _int_
- - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
+ - Axis used to compute the inverse Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: Normalize by `1/n`.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: No normalization.
+
+ Default: `'backward'`
#### Returns
- **out**: _<array>_
- - An array of length `n` containing the sample frequencies.
+ - An array transformed along the axis indicated by the `axis` keyword.
+
+#### Raises
+
+- If `axis` is not a valid axis of `a`.
(function-fftn)=
### fftn(a, /, *, s=None, axes=None, norm='backward')
@@ -92,11 +105,11 @@ Computes the n-dimensional discrete Fourier transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the fast Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the `axes` keyword. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
- **norm**: _str_
@@ -116,34 +129,53 @@ Computes the n-dimensional discrete Fourier transform.
#### Raises
-- If `s` and `axes` have a different length.
+- If `s` and `axes` have different lengths.
- If an element of `axes` is larger than the number of axes of `a`.
-(function-fftshift)=
-### fftshift(x, /, *, axes=None)
+(function-ifftn)=
+### ifftn(a, /, *, s=None, axes=None, norm='backward')
-Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that `out[0]` is the Nyquist component only if the length of the input is even.
+Computes the n-dimensional inverse discrete Fourier transform.
#### Parameters
-- **x**: _<array>_
+- **a**: _<array>_
- Input array.
-- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to shift. If not specified, it shifts all axes. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the `axes` keyword. Default: `None`.
+
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+
+ - Axes over which to compute the inverse Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
+
+- **norm**: _str_
+
+ - Specify the normalization mode. Should be one of the following modes:
+
+ - `'backward'`: Normalize by `1/n`.
+ - `'ortho'`: Normalize by `1/sqrt(n)`
+ - `'forward'`: No normalization.
+
+ Default: `'backward'`
#### Returns
- **out**: _<array>_
- - The shifted array.
+ - An array transformed along the axes indicated by the `axes` keyword.
-(function-hfft)=
-### hfft(a, /, *, n=None, axis=-1, norm='backward')
+#### Raises
-Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
+- If `s` and `axes` have different lengths.
+- If an element of `axes` is larger than the number of axes of `a`.
+
+(function-rfft)=
+### rfft(a, /, *, n=None, axis=-1, norm='backward')
+
+Computes the one-dimensional discrete Fourier transform for real-valued input.
#### Parameters
@@ -153,11 +185,11 @@ Computes the one-dimensional discrete Fourier transform of a signal with Hermiti
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
- **axis**: _int_
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -173,16 +205,16 @@ Computes the one-dimensional discrete Fourier transform of a signal with Hermiti
- **out**: _<array>_
- - A transformed array.
+ - An array transformed along the axis indicated by the `axis` keyword.
#### Raises
-- If `axis` is larger than the last axis of `a`.
+- If `axis` is not a valid axis of `a`.
-(function-ifft)=
-### ifft(a, /, *, n=None, axis=-1, norm='backward')
+(function-irfft)=
+### irfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier transform.
+Computes the one-dimensional inverse discrete Fourier transform for real-valued input.
#### Parameters
@@ -192,11 +224,11 @@ Computes the one-dimensional inverse discrete Fourier transform.
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the IFourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -216,12 +248,12 @@ Computes the one-dimensional inverse discrete Fourier transform.
#### Raises
-- If `axis` is larger than the last axis of `a`.
+- If `axis` is not a valid axis of `a`.
-(function-ifftn)=
-### ifftn(a, /, *, s=None, axes=None, norm='backward')
+(function-rfftn)=
+### rfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional inverse discrete Fourier transform.
+Computes the n-dimensional discrete Fourier transform for real-valued input.
#### Parameters
@@ -231,19 +263,19 @@ Computes the n-dimensional inverse discrete Fourier transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axes over which to compute the Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: Normalize by `1/n`.
+ - `'backward'`: No normalization.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
+ - `'forward'`: Normalize by `1/n`.
Default: `'backward'`
@@ -255,34 +287,13 @@ Computes the n-dimensional inverse discrete Fourier transform.
#### Raises
-- If `s` and `axes` have a different length.
+- If `s` and `axes` have different lengths.
- If an element of `axes` is larger than the number of axes of `a`.
-(function-ifftshift)=
-### ifftshift(x, /, *, axes=None)
-
-Inverse of `fftshift`.
-
-#### Parameters
-
-- **x**: _<array>_
-
- - Input array.
-
-- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to calculate. If not specified, it shifts all axes. Default: `None`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - The shifted array.
-
-(function-ihfft)=
-### ihfft(a, /, *, n=None, axis=-1, norm='backward')
+(function-irfftn)=
+### irfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
+Computes the n-dimensional inverse discrete Fourier transform for real-valued input.
#### Parameters
@@ -290,13 +301,13 @@ Computes the one-dimensional inverse discrete Fourier transform of a signal with
- Input array.
-- **n**: _int_
+- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
-- **axis**: _int_
+- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
- **norm**: _str_
@@ -312,16 +323,17 @@ Computes the one-dimensional inverse discrete Fourier transform of a signal with
- **out**: _<array>_
- - A transformed array.
+ - An array transformed along the axes indicated by the `axes` keyword.
#### Raises
-- If `axis` is larger than the last axis of `a`.
+- If `s` and `axes` have different lengths.
+- If an element of `axes` is larger than the number of axes of `a`.
-(function-irfft)=
-### irfft(a, /, *, n=None, axis=-1, norm='backward')
+(function-hfft)=
+### hfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier transform for real-valued input.
+Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
#### Parameters
@@ -331,19 +343,19 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
- - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
- Specify the normalization mode. Should be one of the following modes:
- - `'backward'`: Normalize by `1/n`.
+ - `'backward'`: No normalization.
- `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
+ - `'forward'`: Normalize by `1/n`.
Default: `'backward'`
@@ -351,16 +363,16 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
+ - A transformed array.
#### Raises
-- If `axis` is larger than the last axis of `a`.
+- If `axis` is not a valid axis of `a`.
-(function-irfftn)=
-### irfftn(a, /, *, s=None, axes=None, norm='backward')
+(function-ihfft)=
+### ihfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the n-dimensional inverse discrete Fourier transform for real-valued input.
+Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
#### Parameters
@@ -368,13 +380,13 @@ Computes the n-dimensional inverse discrete Fourier transform for real-valued in
- Input array.
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+- **n**: _int_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+- **axis**: _int_
- - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+ - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
- **norm**: _str_
@@ -390,52 +402,37 @@ Computes the n-dimensional inverse discrete Fourier transform for real-valued in
- **out**: _<array>_
- - An array transformed along the axes indicated by the `axes` keyword.
+ - A transformed array.
#### Raises
-- If `s` and `axes` have a different length.
-- If an element of `axes` is larger than the number of axes of `a`.
+- If `axis` is not a valid axis of `a`.
+(function-fftfreq)=
+### fftfreq(n, /, *, d=1.0)
-(function-rfft)=
-### rfft(a, /, *, n=None, axis=-1, norm='backward')
+Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
-Computes the one-dimensional discrete Fourier transform for real-valued input.
+```
+f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
+f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+```
#### Parameters
-- **a**: _<array>_
-
- - Input array.
-
- **n**: _int_
- - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
+ - Window length.
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+- **d**: _float_
- Default: `'backward'`
+ - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
#### Returns
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
-
-#### Raises
-
-- If `axis` is larger than the last axis of `a`.
+ - An array of length `n` containing the sample frequencies.
(function-rfftfreq)=
### rfftfreq(n, /, *, d=1.0)
@@ -465,42 +462,44 @@ The Nyquist frequency component is considered to be positive.
- An array of length `n` containing the sample frequencies.
-(function-rfftn)=
-### rfftn(a, /, *, s=None, axes=None, norm='backward')
+(function-fftshift)=
+### fftshift(x, /, *, axes=None)
-Computes the n-dimensional discrete Fourier transform for real-valued input.
+Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that `out[0]` is the Nyquist component only if the length of the input is even.
#### Parameters
-- **a**: _<array>_
+- **x**: _<array>_
- Input array.
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Axes over which to shift. If not specified, it shifts all axes. Default: `None`.
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
+#### Returns
- - Axes over which to compute the Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
+- **out**: _<array>_
-- **norm**: _str_
+ - The shifted array.
- - Specify the normalization mode. Should be one of the following modes:
+(function-ifftshift)=
+### ifftshift(x, /, *, axes=None)
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
+Inverse of `fftshift`.
- Default: `'backward'`
+#### Parameters
-#### Returns
+- **x**: _<array>_
-- **out**: _<array>_
+ - Input array.
- - An array transformed along the axes indicated by the `axes` keyword.
+- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
-#### Raises
+ - Axes over which to calculate. If not specified, it shifts all axes. Default: `None`.
+
+#### Returns
-- If `s` and `axes` have a different length.
-- If an element of `axes` is larger than the number of axes of `a`.
\ No newline at end of file
+- **out**: _<array>_
+
+ - The shifted array.
From 0efc3a3074afae1687559565e87d21d6d8b3ac18 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 12 Aug 2021 17:58:30 -0500
Subject: [PATCH 16/30] Add review changes
---
.../extensions/fourier_transform_functions.md | 46 +++++++++----------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/spec/extensions/fourier_transform_functions.md b/spec/extensions/fourier_transform_functions.md
index 6681e2597..51fb34c82 100644
--- a/spec/extensions/fourier_transform_functions.md
+++ b/spec/extensions/fourier_transform_functions.md
@@ -17,7 +17,7 @@ A conforming implementation of the array API standard must provide and support t
(function-fft)=
### fft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `fft(ifft(a)) == a`.
+Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifft(fft(a)) == a` within numerical accuracy.
#### Parameters
@@ -47,7 +47,7 @@ Computes the one-dimensional discrete Fourier transform. The expected behavior i
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
+ - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
#### Raises
@@ -56,7 +56,7 @@ Computes the one-dimensional discrete Fourier transform. The expected behavior i
(function-ifft)=
### ifft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier transform.
+Computes the one-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifft(fft(a)) == a` within numerical accuracy.
#### Parameters
@@ -86,7 +86,7 @@ Computes the one-dimensional inverse discrete Fourier transform.
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
+ - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
#### Raises
@@ -95,7 +95,7 @@ Computes the one-dimensional inverse discrete Fourier transform.
(function-fftn)=
### fftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional discrete Fourier transform.
+Computes the n-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifftn(fftn(a)) == a` within numerical accuracy.
#### Parameters
@@ -105,7 +105,7 @@ Computes the n-dimensional discrete Fourier transform.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the `axes` keyword. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis `i` will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
@@ -130,12 +130,12 @@ Computes the n-dimensional discrete Fourier transform.
#### Raises
- If `s` and `axes` have different lengths.
-- If an element of `axes` is larger than the number of axes of `a`.
+- If `axes` contains any invalid axis of `a`.
(function-ifftn)=
### ifftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional inverse discrete Fourier transform.
+Computes the n-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifftn(fftn(a)) == a` within numerical accuracy.
#### Parameters
@@ -170,12 +170,12 @@ Computes the n-dimensional inverse discrete Fourier transform.
#### Raises
- If `s` and `axes` have different lengths.
-- If an element of `axes` is larger than the number of axes of `a`.
+- If `axes` contains any invalid axis of `a`.
(function-rfft)=
### rfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional discrete Fourier transform for real-valued input.
+Computes the one-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, `irfft(rfft(a), n=a.shape[axis]) == a` within numerical accuracy.
#### Parameters
@@ -185,7 +185,7 @@ Computes the one-dimensional discrete Fourier transform for real-valued input.
- **n**: _int_
- - Length of the input array. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
+ - Length of the transformed axis of the *input*. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
- **axis**: _int_
@@ -205,7 +205,7 @@ Computes the one-dimensional discrete Fourier transform for real-valued input.
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
+ - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
#### Raises
@@ -214,7 +214,7 @@ Computes the one-dimensional discrete Fourier transform for real-valued input.
(function-irfft)=
### irfft(a, /, *, n=None, axis=-1, norm='backward')
-Computes the one-dimensional inverse discrete Fourier transform for real-valued input.
+Computes the one-dimensional inverse of `rfft`. The expected behavior includes a round-trip transform using the inverse function, `irfft(rfft(a), n=a.shape[axis]) == a` within numerical accuracy.
#### Parameters
@@ -224,7 +224,7 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
- **n**: _int_
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
+ - Length of the transformed axis of the *output*. If given, the input will be either zero-padded or trimmed to `n//2+1` before computing the inverse of `rfft`. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
- **axis**: _int_
@@ -244,7 +244,7 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
- **out**: _<array>_
- - An array transformed along the axis indicated by the `axis` keyword.
+ - A real-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n` (if given) or `2 * (m - 1)`.
#### Raises
@@ -253,7 +253,7 @@ Computes the one-dimensional inverse discrete Fourier transform for real-valued
(function-rfftn)=
### rfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional discrete Fourier transform for real-valued input.
+Computes the n-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, `irfftn(rfftn(a), s=a.shape) == a` within numerical accuracy.
#### Parameters
@@ -263,7 +263,7 @@ Computes the n-dimensional discrete Fourier transform for real-valued input.
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the output. If given, each axis `i` will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. The last element `s[-1]` is for computing `rfft(a[axes[-1]], n=s[-1])` whereas other elements for `fft(a[axes[i]], n=s[i])`. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
@@ -283,17 +283,17 @@ Computes the n-dimensional discrete Fourier transform for real-valued input.
- **out**: _<array>_
- - An array transformed along the axes indicated by the `axes` keyword.
+ - A complex-valued array transformed along the axes indicated by the `axes` keyword. The length along the last transformed axis is `s[-1]//2+1` and along other axes `s[i]`.
#### Raises
- If `s` and `axes` have different lengths.
-- If an element of `axes` is larger than the number of axes of `a`.
+- If `axes` contains any invalid axis of `a`.
(function-irfftn)=
### irfftn(a, /, *, s=None, axes=None, norm='backward')
-Computes the n-dimensional inverse discrete Fourier transform for real-valued input.
+Computes the n-dimensional inverse of `rfftn`. The expected behavior includes a round-trip transform using the inverse function, `irfftn(rfftn(a), s=a.shape) == a` within numerical accuracy.
#### Parameters
@@ -303,7 +303,7 @@ Computes the n-dimensional inverse discrete Fourier transform for real-valued in
- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, no padding will be performed in each dimension. Default: `None`.
+ - Size of each transformed axis of the *output*. If given, the last axis will be either zero-padded or trimmed to `s[-1]//2+1`, whereas all other axes `i` are either zero-padded or trimmed to the length `s[i]`, before computing the inverse of `rfftn`. Otherwise, the last axis is either zero-padded or trimmed to `2 * (m - 1)`, where `m` is the length of the input along the axis, and all other axes use the input shape. The last element `s[-1]` is for computing `irfft(a[axes[-1]], n=s[-1])` whereas other elements for `ifft(a[axes[i]], n=s[i])`. Default: `None`.
- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
@@ -323,12 +323,12 @@ Computes the n-dimensional inverse discrete Fourier transform for real-valued in
- **out**: _<array>_
- - An array transformed along the axes indicated by the `axes` keyword.
+ - A real-valued array transformed along the axes indicated by the `axes` keyword. The length along the last transformed axis is `s[-1]` (if given) or `2 * (m - 1)`, and all other axes `s[i]`.
#### Raises
- If `s` and `axes` have different lengths.
-- If an element of `axes` is larger than the number of axes of `a`.
+- If `axes` contains any invalid axis of `a`.
(function-hfft)=
### hfft(a, /, *, n=None, axis=-1, norm='backward')
From 50a70af66c4e61e8927661523fe8ecb6f8b40a02 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 3 Mar 2022 16:16:15 -0500
Subject: [PATCH 17/30] Update to rst and create fft functions stubs
---
.../signatures/fourier_transform_functions.py | 424 +++++++++++++++
.../extensions/fourier_transform_functions.md | 505 ------------------
.../fourier_transform_functions.rst | 40 ++
3 files changed, 464 insertions(+), 505 deletions(-)
create mode 100644 spec/API_specification/signatures/fourier_transform_functions.py
delete mode 100644 spec/extensions/fourier_transform_functions.md
create mode 100644 spec/extensions/fourier_transform_functions.rst
diff --git a/spec/API_specification/signatures/fourier_transform_functions.py b/spec/API_specification/signatures/fourier_transform_functions.py
new file mode 100644
index 000000000..ada43e593
--- /dev/null
+++ b/spec/API_specification/signatures/fourier_transform_functions.py
@@ -0,0 +1,424 @@
+from ._types import Tuple, Union, Sequence, array, Optional
+
+
+def fft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifft(fft(a)) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ axis: int
+ axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: No normalization.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``.
+ - ``'forward'``: Normalize by ``1/n``.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def ifft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifft(fft(a)) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ axis: int
+ axis used to compute the inverse Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: Normalize by ``1/n``.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``
+ - ``'forward'``: No normalization.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def fftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+ """
+ Computes the n-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifftn(fftn(a)) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ s: Union[Sequence[int], Tuple[int, ...]]
+ size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the Fourier transform. Otherwise, the shape of the input along the axes given by the ``axes`` keyword. Default: ``None``.
+ axes: Union[Sequence[int], Tuple[int, ...]]
+ axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: No normalization.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``.
+ - ``'forward'``: Normalize by ``1/n``.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ an array transformed along the axes indicated by the ``axes`` keyword.
+
+
+ **Raises**
+
+ - If ``s`` and ``axes`` have different lengths.
+ - If ``axes`` contains any invalid axis of ``a``.
+ """
+
+
+def ifftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+ """
+ Computes the n-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifftn(fftn(a)) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ s: Union[Sequence[int], Tuple[int, ...]]
+ size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length ``s[i]`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axes`` keyword. Default: ``None``.
+ axes: Union[Sequence[int], Tuple[int, ...]]
+ axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: Normalize by ``1/n``.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``
+ - ``'forward'``: No normalization.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ an array transformed along the axes indicated by the `axes` keyword.
+
+
+ **Raises**
+
+ - If ``s`` and ``axes`` have different lengths.
+ - If ``axes`` contains any invalid axis of ``a``.
+ """
+
+
+def rfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, ``irfft(rfft(a), n=a.shape[axis]) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the **input**. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the ``axis`` keyword is used. Default: ``None``.
+ axis: int
+ axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: No normalization.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``.
+ - ``'forward'``: Normalize by ``1/n``.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def irfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional inverse of ``rfft``. The expected behavior includes a round-trip transform using the inverse function, ``irfft(rfft(a), n=a.shape[axis]) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the **output**. If given, the input will be either zero-padded or trimmed to ``n//2+1`` before computing the inverse of ``rfft``. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ axis: int
+ axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: Normalize by ``1/n``.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``
+ - ``'forward'``: No normalization.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a real-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def rfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+ """
+ Computes the n-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, ``irfftn(rfftn(a), s=a.shape) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ s: Union[Sequence[int], Tuple[int, ...]]
+ size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the real Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. The last element ``s[-1]`` is for computing ``rfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``fft(a[axes[i]], n=s[i])``. Default: ``None``.
+ axes: Union[Sequence[int], Tuple[int, ...]]
+ axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: No normalization.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``.
+ - ``'forward'``: Normalize by ``1/n``.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a complex-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]//2+1`` and along other axes ``s[i]``.
+
+
+ **Raises**
+
+ - If ``s`` and ``axes`` have different lengths.
+ - If ``axes`` contains any invalid axis of ``a``.
+ """
+
+
+def irfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+ """
+ Computes the n-dimensional inverse of ``rfftn``. The expected behavior includes a round-trip transform using the inverse function, ``irfftn(rfftn(a), s=a.shape) == a`` within numerical accuracy.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ s: Union[Sequence[int], Tuple[int, ...]]
+ size of each transformed axis of the **output**. If given, the last axis will be either zero-padded or trimmed to ``s[-1]//2+1``, whereas all other axes ``i`` are either zero-padded or trimmed to the length ``s[i]``, before computing the inverse of ``rfftn``. Otherwise, the last axis is either zero-padded or trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis, and all other axes use the input shape. The last element ``s[-1]`` is for computing ``irfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``ifft(a[axes[i]], n=s[i])``. Default: ``None``.
+ axes: Union[Sequence[int], Tuple[int, ...]]
+ axes over which to compute the inverse Fourier transform. If it is not specified, the last ``len(s)`` axes are used or all axes if ``s`` is also not specified. Default: ``None``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: Normalize by ``1/n``.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``
+ - ``'forward'``: No normalization.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a real-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``.
+
+
+ **Raises**
+
+ - If ``s`` and ``axes`` have different lengths.
+ - If ``axes`` contains any invalid axis of ``a``.
+ """
+
+
+def hfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ axis: int
+ axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: No normalization.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``.
+ - ``'forward'``: Normalize by ``1/n``.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a transformed array.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def ihfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+ """
+ Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
+
+ Parameters
+ ----------
+ a: array
+ input array
+ n: int
+ length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ axis: int
+ axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
+ norm: str
+ specify the normalization mode. Should be one of the following modes:
+
+ - ``'backward'``: Normalize by ``1/n``.
+ - ``'ortho'``: Normalize by ``1/sqrt(n)``
+ - ``'forward'``: No normalization.
+
+ Default: ``'backward'``.
+
+ Returns
+ -------
+ out: array
+ a transformed array.
+
+
+ **Raises**
+
+ - If ``axis`` is not a valid axis of ``a``.
+ """
+
+
+def fftfreq(n: int, /, *, d: float = 1.0):
+ """
+ Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
+
+
+ .. code-block::
+
+ f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
+ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+
+ Parameters
+ ----------
+ n: int
+ window length.
+ d: float
+ sample spacing between individual samples of the Fourier transform input. Default: ``1.0``.
+
+ Returns
+ -------
+ out: array
+ an array of length ``n`` containing the sample frequencies.
+ """
+
+
+def rfftfreq(n: int, /, *, d: float = 1.0):
+ """
+ Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
+
+
+ .. code-block::
+
+ f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
+ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+
+ The Nyquist frequency component is considered to be positive.
+
+ Parameters
+ ----------
+ n: int
+ window length.
+ d: float
+ sample spacing between individual samples of the Fourier transform input. Default: ``1.0``.
+
+ Returns
+ -------
+ out: array
+ an array of length ``n`` containing the sample frequencies.
+ """
+
+
+def fftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] = None):
+ """
+ Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that ``out[0]`` is the Nyquist component only if the length of the input is even.
+
+ Parameters
+ ----------
+ x: array
+ input array.
+ axes: Union[int, Sequence[int], Tuple[int, ...]]
+ axes over which to shift. If not specified, it shifts all axes. Default: ``None``.
+
+ Returns
+ -------
+ out: array
+ the shifted array.
+ """
+
+
+def ifftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] = None):
+ """
+ Inverse of ``fftshift``.
+
+ Parameters
+ ----------
+ x: array
+ input array.
+ axes: Union[int, Sequence[int], Tuple[int, ...]]
+ axes over which to calculate. If not specified, it shifts all axes. Default: ``None``.
+
+ Returns
+ -------
+ out: array
+ the shifted array.
+ """
+
+
+__all__ = ['fft','ifft','fftn','ifftn','rfft','irfft','rfftn','irfftn','hfft','ihfft','fftfreq','rfftfreq','fftshift','ifftshift']
\ No newline at end of file
diff --git a/spec/extensions/fourier_transform_functions.md b/spec/extensions/fourier_transform_functions.md
deleted file mode 100644
index 51fb34c82..000000000
--- a/spec/extensions/fourier_transform_functions.md
+++ /dev/null
@@ -1,505 +0,0 @@
-# Fourier transform Functions
-
-> Array API specification for Fourier transform functions.
-
-A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
-
-- Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) 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.
-- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
-- Broadcasting semantics must follow the semantics defined in {ref}`broadcasting`.
-- Unless stated otherwise, functions must support the data types defined in {ref}`data-types`.
-- Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`.
-- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
-
-## Objects in API
-
-<!-- NOTE: please keep the functions and their inverse together -->
-(function-fft)=
-### fft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifft(fft(a)) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-ifft)=
-### ifft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifft(fft(a)) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length `n` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the `axis` keyword. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the inverse Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-fftn)=
-### fftn(a, /, *, s=None, axes=None, norm='backward')
-
-Computes the n-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifftn(fftn(a)) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis `i` will be either zero-padded or trimmed to the length `s[i]` before computing the Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have different lengths.
-- If `axes` contains any invalid axis of `a`.
-
-(function-ifftn)=
-### ifftn(a, /, *, s=None, axes=None, norm='backward')
-
-Computes the n-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, `ifftn(fftn(a)) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length `s[i]` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the `axes` keyword. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the inverse Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array transformed along the axes indicated by the `axes` keyword.
-
-#### Raises
-
-- If `s` and `axes` have different lengths.
-- If `axes` contains any invalid axis of `a`.
-
-(function-rfft)=
-### rfft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, `irfft(rfft(a), n=a.shape[axis]) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the *input*. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the `axis` keyword is used. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A complex-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n//2+1`.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-irfft)=
-### irfft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional inverse of `rfft`. The expected behavior includes a round-trip transform using the inverse function, `irfft(rfft(a), n=a.shape[axis]) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the *output*. If given, the input will be either zero-padded or trimmed to `n//2+1` before computing the inverse of `rfft`. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A real-valued array transformed along the axis indicated by the `axis` keyword. The length along the transformed axis is `n` (if given) or `2 * (m - 1)`.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-rfftn)=
-### rfftn(a, /, *, s=None, axes=None, norm='backward')
-
-Computes the n-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, `irfftn(rfftn(a), s=a.shape) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the output. If given, each axis `i` will be either zero-padded or trimmed to the length `s[i]` before computing the real Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. The last element `s[-1]` is for computing `rfft(a[axes[-1]], n=s[-1])` whereas other elements for `fft(a[axes[i]], n=s[i])`. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the Fourier transform. If not specified, the last `len(s)` axes are used, or all axes if `s` is not specified either. Default: `None`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A complex-valued array transformed along the axes indicated by the `axes` keyword. The length along the last transformed axis is `s[-1]//2+1` and along other axes `s[i]`.
-
-#### Raises
-
-- If `s` and `axes` have different lengths.
-- If `axes` contains any invalid axis of `a`.
-
-(function-irfftn)=
-### irfftn(a, /, *, s=None, axes=None, norm='backward')
-
-Computes the n-dimensional inverse of `rfftn`. The expected behavior includes a round-trip transform using the inverse function, `irfftn(rfftn(a), s=a.shape) == a` within numerical accuracy.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **s**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Size of each transformed axis of the *output*. If given, the last axis will be either zero-padded or trimmed to `s[-1]//2+1`, whereas all other axes `i` are either zero-padded or trimmed to the length `s[i]`, before computing the inverse of `rfftn`. Otherwise, the last axis is either zero-padded or trimmed to `2 * (m - 1)`, where `m` is the length of the input along the axis, and all other axes use the input shape. The last element `s[-1]` is for computing `irfft(a[axes[-1]], n=s[-1])` whereas other elements for `ifft(a[axes[i]], n=s[i])`. Default: `None`.
-
-- **axes**: _Union\[ Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to compute the inverse Fourier transform. If it is not specified, the last `len(s)` axes are used or all axes if `s` is also not specified. Default: `None`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A real-valued array transformed along the axes indicated by the `axes` keyword. The length along the last transformed axis is `s[-1]` (if given) or `2 * (m - 1)`, and all other axes `s[i]`.
-
-#### Raises
-
-- If `s` and `axes` have different lengths.
-- If `axes` contains any invalid axis of `a`.
-
-(function-hfft)=
-### hfft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: No normalization.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: Normalize by `1/n`.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A transformed array.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-ihfft)=
-### ihfft(a, /, *, n=None, axis=-1, norm='backward')
-
-Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
-
-#### Parameters
-
-- **a**: _<array>_
-
- - Input array.
-
-- **n**: _int_
-
- - Length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to `2 * (m - 1)` where `m` is the length of the input along the axis given by the `axis` keyword. Default: `None`.
-
-- **axis**: _int_
-
- - Axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: `-1`.
-
-- **norm**: _str_
-
- - Specify the normalization mode. Should be one of the following modes:
-
- - `'backward'`: Normalize by `1/n`.
- - `'ortho'`: Normalize by `1/sqrt(n)`
- - `'forward'`: No normalization.
-
- Default: `'backward'`
-
-#### Returns
-
-- **out**: _<array>_
-
- - A transformed array.
-
-#### Raises
-
-- If `axis` is not a valid axis of `a`.
-
-(function-fftfreq)=
-### fftfreq(n, /, *, d=1.0)
-
-Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
-
-```
-f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
-f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
-```
-
-#### Parameters
-
-- **n**: _int_
-
- - Window length.
-
-- **d**: _float_
-
- - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array of length `n` containing the sample frequencies.
-
-(function-rfftfreq)=
-### rfftfreq(n, /, *, d=1.0)
-
-Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length `n` and length unit of `d` the frequencies are described as:
-
-```
-f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
-f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
-```
-
-The Nyquist frequency component is considered to be positive.
-
-#### Parameters
-
-- **n**: _int_
-
- - Window length.
-
-- **d**: _float_
-
- - Sample spacing between individual samples of the Fourier transform input. Default: `1.0`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - An array of length `n` containing the sample frequencies.
-
-(function-fftshift)=
-### fftshift(x, /, *, axes=None)
-
-Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that `out[0]` is the Nyquist component only if the length of the input is even.
-
-#### Parameters
-
-- **x**: _<array>_
-
- - Input array.
-
-- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to shift. If not specified, it shifts all axes. Default: `None`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - The shifted array.
-
-(function-ifftshift)=
-### ifftshift(x, /, *, axes=None)
-
-Inverse of `fftshift`.
-
-#### Parameters
-
-- **x**: _<array>_
-
- - Input array.
-
-- **axes**: _Union\[ int, Sequence\[ int ], Tuple\[ int, ... ] ]_
-
- - Axes over which to calculate. If not specified, it shifts all axes. Default: `None`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - The shifted array.
diff --git a/spec/extensions/fourier_transform_functions.rst b/spec/extensions/fourier_transform_functions.rst
new file mode 100644
index 000000000..4859c7d0c
--- /dev/null
+++ b/spec/extensions/fourier_transform_functions.rst
@@ -0,0 +1,40 @@
+Fourier transform Functions
+===========================
+
+ Array API specification for Fourier transform functions.
+
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
+
+- Positional parameters must be `positional-only <https://www.python.org/dev/peps/pep-0570/>`_ 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.
+- Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
+- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
+- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
+- Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
+
+Objects in API
+--------------
+
+.. currentmodule:: signatures.fourier_transform_functions
+
+..
+ NOTE: please keep the functions and their inverse together
+
+.. autosummary::
+ :toctree: generated
+ :template: method.rst
+
+ fft
+ ifft
+ fftn
+ ifftn
+ rfft
+ irfft
+ rfftn
+ irfftn
+ hfft
+ ihfft
+ fftfreq
+ rfftfreq
+ fftshift
+ ifftshift
From 92bbafb4b49f29c1717df1f304be335dd453190b Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 28 Jul 2022 17:28:34 -0500
Subject: [PATCH 18/30] Indicate dtypes for inputs and expected outputs
---
.../array_api/fourier_transform_functions.py | 44 +++++++++----------
1 file changed, 22 insertions(+), 22 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 7bf8ba701..6bdd41767 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -8,7 +8,7 @@ def fft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'ba
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
axis: int
@@ -25,7 +25,7 @@ def fft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'ba
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -41,7 +41,7 @@ def ifft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
axis: int
@@ -58,7 +58,7 @@ def ifft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -74,7 +74,7 @@ def fftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the Fourier transform. Otherwise, the shape of the input along the axes given by the ``axes`` keyword. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
@@ -91,7 +91,7 @@ def fftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Returns
-------
out: array
- an array transformed along the axes indicated by the ``axes`` keyword.
+ an array transformed along the axes indicated by the ``axes`` keyword. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -108,7 +108,7 @@ def ifftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length ``s[i]`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axes`` keyword. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
@@ -125,7 +125,7 @@ def ifftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Returns
-------
out: array
- an array transformed along the axes indicated by the `axes` keyword.
+ an array transformed along the axes indicated by the `axes` keyword. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -142,7 +142,7 @@ def rfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the **input**. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the ``axis`` keyword is used. Default: ``None``.
axis: int
@@ -159,7 +159,7 @@ def rfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``.
+ a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -175,7 +175,7 @@ def irfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = '
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the **output**. If given, the input will be either zero-padded or trimmed to ``n//2+1`` before computing the inverse of ``rfft``. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
axis: int
@@ -192,7 +192,7 @@ def irfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = '
Returns
-------
out: array
- a real-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``.
+ a real-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -208,7 +208,7 @@ def rfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the real Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. The last element ``s[-1]`` is for computing ``rfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``fft(a[axes[i]], n=s[i])``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
@@ -225,7 +225,7 @@ def rfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
Returns
-------
out: array
- a complex-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]//2+1`` and along other axes ``s[i]``.
+ a complex-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]//2+1`` and along other axes ``s[i]``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -242,7 +242,7 @@ def irfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
size of each transformed axis of the **output**. If given, the last axis will be either zero-padded or trimmed to ``s[-1]//2+1``, whereas all other axes ``i`` are either zero-padded or trimmed to the length ``s[i]``, before computing the inverse of ``rfftn``. Otherwise, the last axis is either zero-padded or trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis, and all other axes use the input shape. The last element ``s[-1]`` is for computing ``irfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``ifft(a[axes[i]], n=s[i])``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
@@ -259,7 +259,7 @@ def irfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes
Returns
-------
out: array
- a real-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``.
+ a real-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -276,7 +276,7 @@ def hfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
axis: int
@@ -293,7 +293,7 @@ def hfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'b
Returns
-------
out: array
- a transformed array.
+ a transformed array. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -309,7 +309,7 @@ def ihfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = '
Parameters
----------
a: array
- input array
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
axis: int
@@ -326,7 +326,7 @@ def ihfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = '
Returns
-------
out: array
- a transformed array.
+ a transformed array. The returned array must have a complex dtype with the same precision as the input ``x``.
**Raises**
@@ -392,7 +392,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] =
Parameters
----------
x: array
- input array.
+ input array. Should have a floating-point data type.
axes: Union[int, Sequence[int], Tuple[int, ...]]
axes over which to shift. If not specified, it shifts all axes. Default: ``None``.
@@ -410,7 +410,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] =
Parameters
----------
x: array
- input array.
+ input array. Should have a floating-point data type.
axes: Union[int, Sequence[int], Tuple[int, ...]]
axes over which to calculate. If not specified, it shifts all axes. Default: ``None``.
From 07730170ca2bb6264282cf897e1088108d94188a Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Thu, 28 Jul 2022 17:35:52 -0500
Subject: [PATCH 19/30] Fix current module name
---
spec/extensions/fourier_transform_functions.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/spec/extensions/fourier_transform_functions.rst b/spec/extensions/fourier_transform_functions.rst
index 4859c7d0c..d6be0634d 100644
--- a/spec/extensions/fourier_transform_functions.rst
+++ b/spec/extensions/fourier_transform_functions.rst
@@ -15,7 +15,7 @@ A conforming implementation of the array API standard must provide and support t
Objects in API
--------------
-.. currentmodule:: signatures.fourier_transform_functions
+.. currentmodule:: array_api.fourier_transform_functions
..
NOTE: please keep the functions and their inverse together
From ac64f2ec4ccdff2cc985879e12a78bbfd782e7e2 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Mon, 1 Aug 2022 15:05:02 -0500
Subject: [PATCH 20/30] Add review comments
---
.../array_api/fourier_transform_functions.py | 344 +++++++++---------
1 file changed, 181 insertions(+), 163 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 6bdd41767..94ba48fd0 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -1,337 +1,355 @@
-from ._types import Tuple, Union, Sequence, array, Optional
+from ._types import Tuple, Union, Sequence, array, Optional, Literal
-
-def fft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the one-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifft(fft(a)) == a`` within numerical accuracy.
+ 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: ``ifft(fft(x)) == x``.
Parameters
----------
- a: array
+ x: array
input array. Should have a floating-point data type.
n: int
- length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ length of the transformed axis of the output. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, 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
- axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: No normalization.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``.
- - ``'forward'``: Normalize by ``1/n``.
+ - ``'backward'``: no normalization.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``axis`` is not a valid axis of ``a``.
+ 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`.
"""
-def ifft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the one-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifft(fft(a)) == a`` within numerical accuracy.
+ Computes the one-dimensional inverse discrete Fourier transform.
Parameters
----------
- a: array
+ x: array
input array. Should have a floating-point data type.
n: int
- length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to the length ``n`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ length of the transformed axis of the output. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, 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
- axis used to compute the inverse Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: Normalize by ``1/n``.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``
- - ``'forward'``: No normalization.
+ - ``'backward'``: normalize by ``1/n``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'forward'``: no normalization.
Default: ``'backward'``.
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
+ 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`.
+ """
- **Raises**
- - If ``axis`` is not a valid axis of ``a``.
+def fftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
+ Computes the n-dimensional discrete Fourier transform.
-def fftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
- """
- Computes the n-dimensional discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifftn(fftn(a)) == a`` within numerical accuracy.
+ .. note::
+ Applying the n-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy: ``ifftn(fftn(x)) == x``.
Parameters
----------
- a: array
+ x: array
input array. Should have a floating-point data type.
+ n: int
+ length of the transformed axis of the output. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
s: Union[Sequence[int], Tuple[int, ...]]
- size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the Fourier transform. Otherwise, the shape of the input along the axes given by the ``axes`` keyword. Default: ``None``.
+ size of each transformed axis of the output. If
+
+ - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
+ - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+
+ if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
- axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axes (dimension) over which to compute the Fourier transform. If set to ``None``, the last ``len(s)`` axes are used, or all axes if ``s`` is set to ``-1``. Default: ``None``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: No normalization.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``.
- - ``'forward'``: Normalize by ``1/n``.
+ - ``'backward'``: no normalization.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
Returns
-------
out: array
- an array transformed along the axes indicated by the ``axes`` keyword. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``s`` and ``axes`` have different lengths.
- - If ``axes`` contains any invalid axis of ``a``.
+ an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determine by :ref:`type-promotion`.
"""
-def ifftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+def ifftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the n-dimensional inverse discrete Fourier transform. The expected behavior includes a round-trip transform using the inverse function, ``ifftn(fftn(a)) == a`` within numerical accuracy.
+ Computes the n-dimensional inverse discrete Fourier transform.
Parameters
----------
- a: array
+ x: array
input array. Should have a floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
- size of each transformed axis of the output. If given, each axis will be either zero-padded or trimmed to the length ``s[i]`` before computing the inverse Fourier transform. Otherwise, the length of the input along the axis given by the ``axes`` keyword. Default: ``None``.
+ size of each transformed axis of the output. If
+
+ - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
+ - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+
+ if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
- norm: str
+ norm: Literal['backward', 'ortho', 'forward']
specify the normalization mode. Should be one of the following modes:
- - ``'backward'``: Normalize by ``1/n``.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``
- - ``'forward'``: No normalization.
+ - ``'backward'``: normalize by ``1/n``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'forward'``: no normalization.
Default: ``'backward'``.
Returns
-------
out: array
- an array transformed along the axes indicated by the `axes` keyword. The returned array must have a complex dtype with the same precision as the input ``x``.
-
+ an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determine by :ref:`type-promotion`.
+ """
- **Raises**
- - If ``s`` and ``axes`` have different lengths.
- - If ``axes`` contains any invalid axis of ``a``.
+def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
+ Computes the one-dimensional discrete Fourier transform for real-valued input.
-def rfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
- """
- Computes the one-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, ``irfft(rfft(a), n=a.shape[axis]) == a`` within numerical accuracy.
+ .. 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: ``irfft(rfft(x), n=x.shape[axis]) == x``.
Parameters
----------
- a: array
- input array. Should have a floating-point data type.
+ x: array
+ input array. Should have a real-valued floating-point data type.
n: int
- length of the transformed axis of the **input**. If given, the input will be either zero-padded or trimmed to this length before computing the real Fourier transform. Otherwise, the length of the input along the axis specified by the ``axis`` keyword is used. Default: ``None``.
+ length of the transformed axis of the **input**. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, 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
- axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: No normalization.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``.
- - ``'forward'``: Normalize by ``1/n``.
+ - ``'backward'``: no normalization.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
Returns
-------
out: array
- a complex-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n//2+1``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``axis`` is not a valid axis of ``a``.
+ 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`.
"""
-def irfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the one-dimensional inverse of ``rfft``. The expected behavior includes a round-trip transform using the inverse function, ``irfft(rfft(a), n=a.shape[axis]) == a`` within numerical accuracy.
+ Computes the one-dimensional inverse of ``rfft``.
Parameters
----------
- a: array
- input array. Should have a floating-point data type.
+ x: array
+ input array. Should have a real-valued floating-point data type.
n: int
- length of the transformed axis of the **output**. If given, the input will be either zero-padded or trimmed to ``n//2+1`` before computing the inverse of ``rfft``. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ length of the transformed axis of the **output**. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n//2+1``.
+
+ if 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``. Default: ``None``.
axis: int
- axis used to compute the real Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: Normalize by ``1/n``.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``
- - ``'forward'``: No normalization.
+ - ``'backward'``: normalize by ``1/n``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'forward'``: no normalization.
Default: ``'backward'``.
Returns
-------
out: array
- a real-valued array transformed along the axis indicated by the ``axis`` keyword. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
+ an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``.
+ """
- **Raises**
- - If ``axis`` is not a valid axis of ``a``.
+def rfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
+ Computes the n-dimensional discrete Fourier transform for real-valued input.
-def rfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
- """
- Computes the n-dimensional discrete Fourier transform for real-valued input. The expected behavior includes a round-trip transform using the inverse function, ``irfftn(rfftn(a), s=a.shape) == a`` within numerical accuracy.
+ .. note::
+ Applying the n-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: ``irfftn(rfftn(x), n=x.shape[axis]) == x``.
Parameters
----------
- a: array
- input array. Should have a floating-point data type.
+ x: array
+ input array. Should have a real-valued floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
- size of each transformed axis of the output. If given, each axis ``i`` will be either zero-padded or trimmed to the length ``s[i]`` before computing the real Fourier transform. Otherwise, the shape of the input along the axes given by the `axes` keyword. The last element ``s[-1]`` is for computing ``rfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``fft(a[axes[i]], n=s[i])``. Default: ``None``.
+ size of each transformed axis of the output. If
+
+ - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
+ - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+
+ if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: No normalization.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``.
- - ``'forward'``: Normalize by ``1/n``.
+ - ``'backward'``: no normalization.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
Returns
-------
out: array
- a complex-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]//2+1`` and along other axes ``s[i]``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``s`` and ``axes`` have different lengths.
- - If ``axes`` contains any invalid axis of ``a``.
+ 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`.
"""
-def irfftn(a: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: str = 'backward') -> array:
+def irfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the n-dimensional inverse of ``rfftn``. The expected behavior includes a round-trip transform using the inverse function, ``irfftn(rfftn(a), s=a.shape) == a`` within numerical accuracy.
+ Computes the n-dimensional inverse of ``rfftn``.
Parameters
----------
- a: array
- input array. Should have a floating-point data type.
+ x: array
+ input array. Should have a real-valued floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
- size of each transformed axis of the **output**. If given, the last axis will be either zero-padded or trimmed to ``s[-1]//2+1``, whereas all other axes ``i`` are either zero-padded or trimmed to the length ``s[i]``, before computing the inverse of ``rfftn``. Otherwise, the last axis is either zero-padded or trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis, and all other axes use the input shape. The last element ``s[-1]`` is for computing ``irfft(a[axes[-1]], n=s[-1])`` whereas other elements for ``ifft(a[axes[i]], n=s[i])``. Default: ``None``.
+ size of each transformed axis of the **output**. If
+
+ - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
+ - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``. Except for the last axis is trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis.
+
+ if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
axes: Union[Sequence[int], Tuple[int, ...]]
- axes over which to compute the inverse Fourier transform. If it is not specified, the last ``len(s)`` axes are used or all axes if ``s`` is also not specified. Default: ``None``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: Normalize by ``1/n``.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``
- - ``'forward'``: No normalization.
+ - ``'backward'``: normalize by ``1/n``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'forward'``: no normalization.
Default: ``'backward'``.
Returns
-------
out: array
- a real-valued array transformed along the axes indicated by the ``axes`` keyword. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``s`` and ``axes`` have different lengths.
- - If ``axes`` contains any invalid axis of ``a``.
+ 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`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``.
"""
-def hfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the one-dimensional discrete Fourier transform of a signal with Hermitian symmetry.
Parameters
----------
- a: array
- input array. Should have a floating-point data type.
+ x: array
+ input array. Should have a complex floating-point data type.
n: int
- length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ length of the transformed axis of the output. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, 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
- axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: No normalization.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``.
- - ``'forward'``: Normalize by ``1/n``.
+ - ``'backward'``: no normalization.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
Returns
-------
out: array
- a transformed array. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``axis`` is not a valid axis of ``a``.
+ 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`.
"""
-def ihfft(a: array, /, *, n: Optional[int] = None, axis: int = -1, norm: str = 'backward') -> array:
+def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the one-dimensional inverse discrete Fourier transform of a signal with Hermitian symmetry.
Parameters
----------
- a: array
+ x: array
input array. Should have a floating-point data type.
n: int
- length of the transformed axis of the output. If given, the input will be either zero-padded or trimmed to this length before computing the Hermitian Fourier transform. Otherwise, it will default to ``2 * (m - 1)`` where ``m`` is the length of the input along the axis given by the ``axis`` keyword. Default: ``None``.
+ length of the transformed axis of the output. If
+
+ - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+
+ if not provided, 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
- axis used to compute the Fourier transform. If it is not specified, the last axis is used. Default: ``-1``.
- norm: str
- specify the normalization mode. Should be one of the following modes:
+ axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ norm: Literal['backward', 'ortho', 'forward']
+ normalization mode. Should be one of the following modes:
- - ``'backward'``: Normalize by ``1/n``.
- - ``'ortho'``: Normalize by ``1/sqrt(n)``
- - ``'forward'``: No normalization.
+ - ``'backward'``: normalize by ``1/n``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'forward'``: no normalization.
Default: ``'backward'``.
Returns
-------
out: array
- a transformed array. The returned array must have a complex dtype with the same precision as the input ``x``.
-
-
- **Raises**
-
- - If ``axis`` is not a valid axis of ``a``.
+ 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`.
"""
From 60db5b84b388bba64421e6dd6b2ee080a69011c4 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Mon, 1 Aug 2022 15:13:10 -0500
Subject: [PATCH 21/30] fix input/output data types
---
.../array_api/fourier_transform_functions.py | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 94ba48fd0..4d30a985f 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -191,7 +191,7 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Should have a complex floating-point data type.
n: int
length of the transformed axis of the **output**. If
@@ -261,7 +261,7 @@ def irfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Should have a complex floating-point data type.
s: Union[Sequence[int], Tuple[int, ...]]
size of each transformed axis of the **output**. If
@@ -283,7 +283,7 @@ def irfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes
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`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, 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 determined by :ref:`type-promotion`. The length along the last transformed axis is ``s[-1]`` (if given) or ``2 * (m - 1)``, and all other axes ``s[i]``.
"""
@@ -294,7 +294,7 @@ def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
Parameters
----------
x: array
- input array. Should have a complex floating-point data type.
+ input array. Should have a real-valued floating-point data type.
n: int
length of the transformed axis of the output. If
@@ -327,7 +327,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Parameters
----------
x: array
- input array. Should have a floating-point data type.
+ input array. Should have a real-valued floating-point data type.
n: int
length of the transformed axis of the output. If
@@ -349,7 +349,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
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 a real-valued floating-point data type determined by :ref:`type-promotion`.
"""
From 46e504a73fae643e8c7f12876be770f9f137c2b8 Mon Sep 17 00:00:00 2001
From: Stephannie Jimenez <steff456@hotmail.com>
Date: Tue, 23 Aug 2022 14:18:47 -0500
Subject: [PATCH 22/30] Add review comments
---
.../array_api/fourier_transform_functions.py | 166 ++++++++++--------
1 file changed, 96 insertions(+), 70 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 4d30a985f..9581098f2 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -4,9 +4,8 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['
"""
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: ``ifft(fft(x)) == x``.
+ 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 normalization mode.
Parameters
----------
@@ -15,19 +14,21 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['
n: int
length of the transformed axis of the output. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ If not provided, 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
axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: no normalization.
- - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -48,19 +49,21 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
n: int
length of the transformed axis of the output. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ If not provided, 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
axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: normalize by ``1/n``.
- - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -70,41 +73,42 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
"""
-def fftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
+def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the n-dimensional discrete Fourier transform.
.. note::
- Applying the n-dimensional inverse discrete Fourier transform to the output of this function must return the original (i.e., non-transformed) input array within numerical accuracy: ``ifftn(fftn(x)) == x``.
+ Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode..
Parameters
----------
x: array
input array. Should have a floating-point data type.
- n: int
- length of the transformed axis of the output. If
+ s: Sequence[int]
+ size of each transformed axis of the output. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+ - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+ - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be trimmed such that the axis has size``s[i]``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
- s: Union[Sequence[int], Tuple[int, ...]]
- size of each transformed axis of the output. If
+ If ``axes`` is ``None``, the last ``len(s)`` axes must be transformed, and, thus, ``j`` represents an axis index computed according to ``N - len(s) + i``, where ``N`` is the number of axes (e.g., if ``N = 4`` and ``s = (256, 256)``, then ``i = 0`` corresponds to axis ``2`` and ``i = 1`` corresponds to axis ``3``, the last axis).
+
+ If ``axes`` is not ``None``, size ``s[i]`` corresponds to the size of axis ``axes[j]`` where ``i == j``.
- - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
- - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+ If 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.
- if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
- axes: Union[Sequence[int], Tuple[int, ...]]
- axes (dimension) over which to compute the Fourier transform. If set to ``None``, the last ``len(s)`` axes are used, or all axes if ``s`` is set to ``-1``. Default: ``None``.
+ Default: ``None``.
+ axes: Sequence[int]
+ axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``None`` and ``s`` is specified, the last ``len(s)`` axes must be transformed. Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: no normalization.
- - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -114,7 +118,7 @@ def fftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
"""
-def ifftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
+def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the n-dimensional inverse discrete Fourier transform.
@@ -122,22 +126,24 @@ def ifftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
----------
x: array
input array. Should have a floating-point data type.
- s: Union[Sequence[int], Tuple[int, ...]]
+ s: Sequence[int]
size of each transformed axis of the output. If
- - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
- - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+ - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+ - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
- if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
- axes: Union[Sequence[int], Tuple[int, ...]]
+ If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ axes: Sequence[int]
axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
specify the normalization mode. Should be one of the following modes:
- ``'backward'``: normalize by ``1/n``.
- - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -153,7 +159,7 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
.. 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: ``irfft(rfft(x), n=x.shape[axis]) == x``.
+ 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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode..
Parameters
----------
@@ -162,19 +168,21 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
n: int
length of the transformed axis of the **input**. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ If not provided, 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
axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: no normalization.
- - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -195,19 +203,21 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
n: int
length of the transformed axis of the **output**. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n//2+1``.
- if 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``. Default: ``None``.
+ If 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``. Default: ``None``.
axis: int
axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: normalize by ``1/n``.
- - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -217,34 +227,36 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
"""
-def rfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
+def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the n-dimensional discrete Fourier transform for real-valued input.
.. note::
- Applying the n-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: ``irfftn(rfftn(x), n=x.shape[axis]) == x``.
+ Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
Parameters
----------
x: array
input array. Should have a real-valued floating-point data type.
- s: Union[Sequence[int], Tuple[int, ...]]
+ s: Sequence[int]
size of each transformed axis of the output. If
- - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
- - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+ - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+ - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
- if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
- axes: Union[Sequence[int], Tuple[int, ...]]
+ If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ axes: Sequence[int]
axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: no normalization.
- - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -254,7 +266,7 @@ def rfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes:
"""
-def irfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes: Union[Sequence[int], Tuple[int, ...]] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
+def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the n-dimensional inverse of ``rfftn``.
@@ -262,22 +274,24 @@ def irfftn(x: array, /, *, s: Union[Sequence[int], Tuple[int, ...]] = None, axes
----------
x: array
input array. Should have a complex floating-point data type.
- s: Union[Sequence[int], Tuple[int, ...]]
+ s: Sequence[int]
size of each transformed axis of the **output**. If
- - ``s`` is larger than the length of the input array, each axis ``i`` of the input array must be zero-padded.
- - ``s`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``. Except for the last axis is trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis.
+ - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+ - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``. Except for the last axis is trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis.
- if not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
- axes: Union[Sequence[int], Tuple[int, ...]]
+ If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ axes: Sequence[int]
axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: normalize by ``1/n``.
- - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -298,17 +312,17 @@ def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
n: int
length of the transformed axis of the output. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ If not provided, 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
axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: no normalization.
- - ``'ortho'``: normalize by ``1/sqrt(n)``.
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
Default: ``'backward'``.
@@ -331,19 +345,21 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
n: int
length of the transformed axis of the output. If
- - ``n`` is larger than the length of the input array, the input array must be zero-padded.
+ - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
- if not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ If not provided, 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
axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
- ``'backward'``: normalize by ``1/n``.
- - ``'ortho'``: normalize by ``1/sqrt(n)``
+ - ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
+ where ``n`` equals ``prod(s)``, the logical FFT size.
+
Default: ``'backward'``.
Returns
@@ -355,7 +371,9 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
def fftfreq(n: int, /, *, d: float = 1.0):
"""
- Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
+ Returns the discrete Fourier transform sample frequencies.
+
+ For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
.. code-block::
@@ -373,7 +391,7 @@ def fftfreq(n: int, /, *, d: float = 1.0):
Returns
-------
out: array
- an array of length ``n`` containing the sample frequencies.
+ an array of length ``n`` containing the sample frequencies. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
"""
@@ -399,43 +417,51 @@ def rfftfreq(n: int, /, *, d: float = 1.0):
Returns
-------
out: array
- an array of length ``n`` containing the sample frequencies.
+ an array of length ``n`` containing the sample frequencies. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
"""
-def fftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] = None):
+def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
"""
- Reorders n-dimensional FTT data to have negative frequency terms first. In this way, the zero-frequency component shifts to the center of the spectrum. Note that ``out[0]`` is the Nyquist component only if the length of the input is even.
+ Shift the zero-frequency component to the center of the spectrum.
+
+ This function swaps half-spaces for all axes (dimensions) specified by `axes`.
+
+ .. note::
+ ``out[0]`` is the Nyquist component only if the length of the input is even.
Parameters
----------
x: array
input array. Should have a floating-point data type.
- axes: Union[int, Sequence[int], Tuple[int, ...]]
- axes over which to shift. If not specified, it shifts all axes. Default: ``None``.
+ axes: Union[int, Sequence[int]]
+ axes over which to shift. If ``None``, the function must shift all axes. Default: ``None``.
Returns
-------
out: array
- the shifted array.
+ the shifted array. The returned array must have the same data type as ``x``.
"""
-def ifftshift(x: array, /, *, axes: Union[int, Sequence[int], Tuple[int, ...]] = None):
+def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
"""
Inverse of ``fftshift``.
+ .. note::
+ Although identical for even-length ``x``, ``fftshift`` and `ifftshift`` differ by one sample for odd-length ``x``.
+
Parameters
----------
x: array
input array. Should have a floating-point data type.
- axes: Union[int, Sequence[int], Tuple[int, ...]]
- axes over which to calculate. If not specified, it shifts all axes. Default: ``None``.
+ axes: Union[int, Sequence[int]]
+ axes over which to perform the inverse. If ``None``, the function must shift all axes. Default: ``None``.
Returns
-------
out: array
- the shifted array.
+ the shifted array. The returned array must have the same data type as ``x``.
"""
From be6330a9020c0ae9ae3abbfc4b2a458a64e1cf7e Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Wed, 5 Oct 2022 13:57:58 -0400
Subject: [PATCH 23/30] Apply suggestions from code review
---
.../array_api/fourier_transform_functions.py | 35 +++++++++----------
1 file changed, 17 insertions(+), 18 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 9581098f2..654d24589 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -88,10 +88,9 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
s: Sequence[int]
size of each transformed axis of the output. If
- - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be trimmed such that the axis has size``s[i]``.
+ - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
+ - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be trimmed such that the axis has size ``s[i]``.
- If ``axes`` is ``None``, the last ``len(s)`` axes must be transformed, and, thus, ``j`` represents an axis index computed according to ``N - len(s) + i``, where ``N`` is the number of axes (e.g., if ``N = 4`` and ``s = (256, 256)``, then ``i = 0`` corresponds to axis ``2`` and ``i = 1`` corresponds to axis ``3``, the last axis).
If ``axes`` is not ``None``, size ``s[i]`` corresponds to the size of axis ``axes[j]`` where ``i == j``.
@@ -99,7 +98,7 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
Default: ``None``.
axes: Sequence[int]
- axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``None`` and ``s`` is specified, the last ``len(s)`` axes must be transformed. Default: ``None``.
+ axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -203,8 +202,8 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
n: int
length of the transformed axis of the **output**. If
- - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n//2+1``.
+ - ``n//2+1`` is greater than the length of the input array, the input array must be zero-padded.
+ - ``n//2+1`` is less than the length of the input array, the input array must be trimmed.
If 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``. Default: ``None``.
axis: int
@@ -343,7 +342,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
x: array
input array. Should have a real-valued floating-point data type.
n: int
- length of the transformed axis of the output. If
+ length of the transformed axis of the **input**. If
- ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
@@ -365,7 +364,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
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 a complex-valued floating-point data type determined by :ref:`type-promotion`.
"""
@@ -375,11 +374,10 @@ def fftfreq(n: int, /, *, d: float = 1.0):
For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
-
.. code-block::
- f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
- f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+ f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) # if n is even
+ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) # if n is odd
Parameters
----------
@@ -397,13 +395,14 @@ def fftfreq(n: int, /, *, d: float = 1.0):
def rfftfreq(n: int, /, *, d: float = 1.0):
"""
- Returns the discrete Fourier transform sample frequencies. For a Fourier transform of length ``n`` and length unit of ``d`` the frequencies are described as:
-
+ Returns 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:
.. code-block::
- f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) if n is even
- f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) if n is odd
+ f = [0, 1, ..., n/2-1, n/2] / (d*n) # if n is even
+ f = [0, 1, ..., (n-1)/2-1, (n-1)/2] / (d*n) # if n is odd
The Nyquist frequency component is considered to be positive.
@@ -417,7 +416,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0):
Returns
-------
out: array
- an array of length ``n`` containing the sample frequencies. The returned array must have a 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 a floating-point data type determined by :ref:`type-promotion`.
"""
@@ -425,7 +424,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
"""
Shift the zero-frequency component to the center of the spectrum.
- This function swaps half-spaces for all axes (dimensions) specified by `axes`.
+ This function swaps half-spaces for all axes (dimensions) specified by ``axes``.
.. note::
``out[0]`` is the Nyquist component only if the length of the input is even.
@@ -449,7 +448,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
Inverse of ``fftshift``.
.. note::
- Although identical for even-length ``x``, ``fftshift`` and `ifftshift`` differ by one sample for odd-length ``x``.
+ Although identical for even-length ``x``, ``fftshift`` and ``ifftshift`` differ by one sample for odd-length ``x``.
Parameters
----------
From c030c0c358ede634d215dd0010d39ff409812be1 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Thu, 6 Oct 2022 13:01:43 -0400
Subject: [PATCH 24/30] add round-trip note to relevant fft pairs
---
.../array_api/fourier_transform_functions.py | 20 ++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 654d24589..86b2aee8b 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -1,5 +1,6 @@
from ._types import Tuple, Union, Sequence, array, Optional, Literal
+
def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
Computes the one-dimensional discrete Fourier transform.
@@ -42,6 +43,9 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
"""
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 normalization mode.
+
Parameters
----------
x: array
@@ -77,9 +81,8 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
"""
Computes the n-dimensional discrete Fourier transform.
-
.. note::
- Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode..
+ Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
Parameters
----------
@@ -121,6 +124,9 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
"""
Computes the n-dimensional inverse discrete Fourier transform.
+ .. note::
+ Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+
Parameters
----------
x: array
@@ -156,9 +162,8 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
"""
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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode..
+ 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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
Parameters
----------
@@ -195,6 +200,9 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
"""
Computes the one-dimensional inverse of ``rfft``.
+ .. 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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+
Parameters
----------
x: array
@@ -230,7 +238,6 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
"""
Computes the n-dimensional discrete Fourier transform for real-valued input.
-
.. note::
Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
@@ -269,6 +276,9 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
"""
Computes the n-dimensional inverse of ``rfftn``.
+ .. note::
+ Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+
Parameters
----------
x: array
From 29da2cdb9b8f8f96ce9d9c79afd86a80eb206618 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Thu, 6 Oct 2022 13:54:20 -0400
Subject: [PATCH 25/30] fix s & axes requirement
---
.../array_api/fourier_transform_functions.py | 45 +++++++++++++++----
1 file changed, 36 insertions(+), 9 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 86b2aee8b..6be779e1c 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -94,14 +94,17 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
- ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be trimmed such that the axis has size ``s[i]``.
-
- If ``axes`` is not ``None``, size ``s[i]`` corresponds to the size of axis ``axes[j]`` where ``i == j``.
+ 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 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.
Default: ``None``.
axes: Sequence[int]
- axes (dimension) over which to compute the Fourier transform. If ``None`` and ``s`` is not specified, all axes must be transformed. If ``s`` is specified, the corresponding ``axes`` to be transformed must be explicitly specified too. Default: ``None``.
+ 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.
+
+ Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -137,9 +140,17 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
- If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ 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 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.
+
+ Default: ``None``.
axes: Sequence[int]
- axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ 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.
+
+ Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
specify the normalization mode. Should be one of the following modes:
@@ -251,9 +262,17 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
- If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ 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 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.
+
+ Default: ``None``.
axes: Sequence[int]
- axes over which to compute the Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ 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.
+
+ Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -289,9 +308,17 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
- ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``. Except for the last axis is trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis.
- If not provided, the length of the transformed axes of the output must equal the length of the input along the axes specified by ``axes``. Default: ``None``.
+ 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 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.
+
+ Default: ``None``.
axes: Sequence[int]
- axes over which to compute the inverse Fourier transform. If not specified, the last ``len(s)`` axes are used, or all axes if ``s`` is not specified either. Default: ``None``.
+ 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.
+
+ Default: ``None``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
From c0c25a1cb00d8f3527f58bed7c9021753d7aa08f Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Thu, 6 Oct 2022 22:33:22 -0400
Subject: [PATCH 26/30] improve wording
---
.../array_api/fourier_transform_functions.py | 128 ++++++++++--------
1 file changed, 71 insertions(+), 57 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 6be779e1c..dde4a4e9c 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -15,12 +15,15 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['
n: int
length of the transformed axis of the output. If
- - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+ - ``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``.
- If not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -53,12 +56,15 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
n: int
length of the transformed axis of the output. If
- - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+ - ``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``.
- If not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -91,13 +97,12 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
s: Sequence[int]
size of each transformed axis of the output. If
- - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- - ``s[i]`` is less than the size of the input array along a corresponding axis (dimension) ``i``, the corresponding axis of the input array must be trimmed such that the axis has size ``s[i]``.
+ - ``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`` 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.
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 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.
-
Default: ``None``.
axes: Sequence[int]
axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed.
@@ -119,7 +124,7 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
Returns
-------
out: array
- an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determine 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 determined by :ref:`type-promotion`.
"""
@@ -137,13 +142,12 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
s: Sequence[int]
size of each transformed axis of the output. If
- - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+ - ``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`` 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.
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 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.
-
Default: ``None``.
axes: Sequence[int]
axes (dimensions) over which to compute the Fourier transform. If ``None``, all axes must be transformed.
@@ -165,7 +169,7 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
Returns
-------
out: array
- an array transformed along the axes (dimension) indicated by ``axes``. The returned array must have a complex floating-point data type determine 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 determined by :ref:`type-promotion`.
"""
@@ -183,12 +187,15 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
n: int
length of the transformed axis of the **input**. If
- - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
-
- If not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ - ``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``.
+
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -209,7 +216,7 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the one-dimensional inverse of ``rfft``.
+ 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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
@@ -221,12 +228,15 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
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 must be zero-padded.
- - ``n//2+1`` is less than the length of the input array, the input array must be trimmed.
-
- If 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``. Default: ``None``.
+ - ``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``.
+
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the inverse Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the inverse Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -241,7 +251,7 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Returns
-------
out: array
- an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2 * (m - 1)``.
+ an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real floating-point data type determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` otherwise.
"""
@@ -257,14 +267,13 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
x: array
input array. Should have a real-valued floating-point data type.
s: Sequence[int]
- size of each transformed axis of the output. If
-
- - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``.
+ size of each transformed axis of the **input**. If
- 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]``.
+ - ``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`` 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.
- If 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.
+ 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]``.
Default: ``None``.
axes: Sequence[int]
@@ -293,7 +302,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, norm: Literal['backward', 'ortho', 'forward'] = 'backward') -> array:
"""
- Computes the n-dimensional inverse of ``rfftn``.
+ Computes the n-dimensional inverse of ``rfftn`` for complex-valued input.
.. note::
Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
@@ -303,14 +312,13 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
x: array
input array. Should have a complex floating-point data type.
s: Sequence[int]
- size of each transformed axis of the **output**. If
-
- - ``s[i]`` is greater than the size of the input array along a corresponding axis (dimension) ``j``, the corresponding axis of the input array must be zero-padded such that the axis has size ``s[i]``.
- - ``s[i]`` is less than the length of the input array, each axis ``i`` of the input array must be trimmed to the length ``s[i]``. Except for the last axis is trimmed to ``2 * (m - 1)``, where `m` is the length of the input along the axis.
+ 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
- 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]``.
+ - ``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``.
+ - ``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.
- If 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.
+ 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]``.
Default: ``None``.
axes: Sequence[int]
@@ -333,7 +341,7 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
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)``, 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 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]``.
"""
@@ -346,14 +354,17 @@ def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
x: array
input array. Should have a real-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 must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
+ length of the transformed axis of the **output**. If
- If not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ - ``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``.
+
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -381,12 +392,15 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
n: int
length of the transformed axis of the **input**. If
- - ``n`` is greater than the length of the input array, the input array must be zero-padded such that the input array has length ``n``.
- - ``n`` is less than the length of the input array, the input array must be trimmed to length ``n``.
-
- If not provided, the length of the transformed axis of the output must equal the length of the input along the axis specified by ``axis``. Default: ``None``.
+ - ``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``.
+
+ Default: ``None``.
axis: int
- axis (dimension) over which to compute the Fourier transform. If set to ``-1``, the function must compute the Fourier transform over the last axis (dimension). Default: ``-1``.
+ axis (dimension) over which to compute the Fourier transform. If not set, the last axis (dimension) is used.
+
+ Default: ``-1``.
norm: Literal['backward', 'ortho', 'forward']
normalization mode. Should be one of the following modes:
@@ -413,8 +427,8 @@ def fftfreq(n: int, /, *, d: float = 1.0):
.. code-block::
- f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) # if n is even
- f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) # if n is odd
+ f = [0, 1, ..., n/2-1, -n/2, ..., -1] / (d*n) # if n is even
+ f = [0, 1, ..., (n-1)/2, -(n-1)/2, ..., -1] / (d*n) # if n is odd
Parameters
----------
From fd66e4405bd9e887ab398f1805f911c9144af981 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Thu, 6 Oct 2022 22:38:50 -0400
Subject: [PATCH 27/30] fix input dtype limit
---
.../array_api/fourier_transform_functions.py | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index dde4a4e9c..ad6a6829b 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -210,7 +210,7 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
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 a complex-valued floating-point data type determined by :ref:`type-promotion`.
"""
@@ -224,7 +224,7 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Parameters
----------
x: array
- input array. Should have a complex 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
@@ -251,7 +251,7 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Returns
-------
out: array
- an array transformed along the axis (dimension) indicated by ``axis``. The returned array must have a real 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 determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` otherwise.
"""
@@ -296,7 +296,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
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 a complex-valued floating-point data type determined by :ref:`type-promotion`.
"""
@@ -310,7 +310,7 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
Parameters
----------
x: array
- input array. Should have a complex 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**. ``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
@@ -352,7 +352,7 @@ def hfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Should have a floating-point data type.
n: int
length of the transformed axis of the **output**. If
From 211fa3a91991c48d4509befc7060214cac914522 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Sat, 15 Oct 2022 16:29:09 -0400
Subject: [PATCH 28/30] add placeholder & address nits
---
.../array_api/fourier_transform_functions.py | 50 ++++++++-----------
1 file changed, 22 insertions(+), 28 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index ad6a6829b..e43930748 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -6,7 +6,7 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['
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 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 (length, axis, and normalization mode).
Parameters
----------
@@ -31,8 +31,6 @@ def fft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal['
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
- where ``n`` equals ``prod(s)``, the logical FFT size.
-
Default: ``'backward'``.
Returns
@@ -47,7 +45,7 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
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 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 (length, axis, and normalization mode).
Parameters
----------
@@ -72,8 +70,6 @@ def ifft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
- where ``n`` equals ``prod(s)``, the logical FFT size.
-
Default: ``'backward'``.
Returns
@@ -88,7 +84,7 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
Computes the n-dimensional discrete Fourier transform.
.. note::
- Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode).
Parameters
----------
@@ -99,6 +95,7 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
- ``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 ``-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.
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]``.
@@ -117,7 +114,7 @@ def fftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, no
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
- where ``n`` equals ``prod(s)``, the logical FFT size.
+ where ``n = prod(s)`` is the logical FFT size.
Default: ``'backward'``.
@@ -133,7 +130,7 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
Computes the n-dimensional inverse discrete Fourier transform.
.. note::
- Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ Applying the n-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., ``ifftn(fftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (sizes, axes, and normalization mode).
Parameters
----------
@@ -144,6 +141,7 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``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 ``-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.
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]``.
@@ -162,7 +160,7 @@ def ifftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
- where ``n`` equals ``prod(s)``, the logical FFT size.
+ where ``n = prod(s)`` is the logical FFT size.
Default: ``'backward'``.
@@ -178,7 +176,7 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ 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.
Parameters
----------
@@ -203,8 +201,6 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
- where ``n`` equals ``prod(s)``, the logical FFT size.
-
Default: ``'backward'``.
Returns
@@ -219,7 +215,7 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
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), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ 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.
Parameters
----------
@@ -244,14 +240,12 @@ def irfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
- where ``n`` equals ``prod(s)``, the logical FFT size.
-
Default: ``'backward'``.
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 determined by :ref:`type-promotion`. The length along the transformed axis is ``n`` (if given) or ``2*(m-1)`` (otherwise).
"""
@@ -260,7 +254,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
Computes the n-dimensional discrete Fourier transform for real-valued input.
.. note::
- Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ Applying the n-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., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes.
Parameters
----------
@@ -271,6 +265,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``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 ``-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.
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]``.
@@ -289,7 +284,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: normalize by ``1/n``.
- where ``n`` equals ``prod(s)``, the logical FFT size.
+ where ``n = prod(s)``, the logical FFT size.
Default: ``'backward'``.
@@ -305,7 +300,7 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
Computes the n-dimensional inverse of ``rfftn`` for complex-valued input.
.. note::
- Applying the n-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., ``irfftn(rfftn(x), n=x.shape[axis]) == x``), provided that the transform and inverse transform are performed with the same normalization mode.
+ Applying the n-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., ``irfftn(rfftn(x)) == x``), provided that the transform and inverse transform are performed with the same arguments (axes and normalization mode) and consistent sizes.
Parameters
----------
@@ -316,7 +311,8 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
- ``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``.
- - ``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[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.
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]``.
@@ -334,14 +330,14 @@ def irfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None,
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
- where ``n`` equals ``prod(s)``, the logical FFT size.
+ where ``n = prod(s)`` is the logical FFT size.
Default: ``'backward'``.
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 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]``.
"""
@@ -408,8 +404,6 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
- ``'ortho'``: normalize by ``1/sqrt(n)`` (i.e., make the FFT orthonormal).
- ``'forward'``: no normalization.
- where ``n`` equals ``prod(s)``, the logical FFT size.
-
Default: ``'backward'``.
Returns
@@ -440,7 +434,7 @@ def fftfreq(n: int, /, *, d: float = 1.0):
Returns
-------
out: array
- an array of length ``n`` containing the sample frequencies. The returned array must have a floating-point data type determined by :ref:`type-promotion`.
+ 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`.
"""
@@ -467,7 +461,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0):
Returns
-------
out: array
- an array of length ``n//2+1`` containing the sample frequencies. The returned array must have a 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 a real-valued floating-point data type determined by :ref:`type-promotion`.
"""
@@ -506,7 +500,7 @@ def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
x: array
input array. Should have a floating-point data type.
axes: Union[int, Sequence[int]]
- axes over which to perform the inverse. If ``None``, the function must shift all axes. Default: ``None``.
+ axes over which to perform the inverse shift. If ``None``, the function must shift all axes. Default: ``None``.
Returns
-------
From e8e0f1bc471c002c6f777f36fd30e7b432294aa0 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Mon, 17 Oct 2022 00:15:05 -0400
Subject: [PATCH 29/30] add missing return type annotation
---
.../array_api/fourier_transform_functions.py | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index e43930748..971b4d8b6 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -413,7 +413,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
"""
-def fftfreq(n: int, /, *, d: float = 1.0):
+def fftfreq(n: int, /, *, d: float = 1.0) -> array:
"""
Returns the discrete Fourier transform sample frequencies.
@@ -438,7 +438,7 @@ def fftfreq(n: int, /, *, d: float = 1.0):
"""
-def rfftfreq(n: int, /, *, d: float = 1.0):
+def rfftfreq(n: int, /, *, d: float = 1.0) -> array:
"""
Returns the discrete Fourier transform sample frequencies (for ``rfft`` and ``irfft``).
@@ -465,7 +465,7 @@ def rfftfreq(n: int, /, *, d: float = 1.0):
"""
-def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
+def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array:
"""
Shift the zero-frequency component to the center of the spectrum.
@@ -488,7 +488,7 @@ def fftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
"""
-def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None):
+def ifftshift(x: array, /, *, axes: Union[int, Sequence[int]] = None) -> array:
"""
Inverse of ``fftshift``.
From 18bea1550285ef2e8ad5d22ee28b702a49eca509 Mon Sep 17 00:00:00 2001
From: Leo Fang <leo80042@gmail.com>
Date: Mon, 17 Oct 2022 09:49:44 -0400
Subject: [PATCH 30/30] Change "should" to "must" for R2C transforms
---
.../array_api/fourier_transform_functions.py | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/spec/API_specification/array_api/fourier_transform_functions.py b/spec/API_specification/array_api/fourier_transform_functions.py
index 971b4d8b6..4eef946ab 100644
--- a/spec/API_specification/array_api/fourier_transform_functions.py
+++ b/spec/API_specification/array_api/fourier_transform_functions.py
@@ -181,7 +181,7 @@ def rfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal[
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Must have a real-valued floating-point data type.
n: int
length of the transformed axis of the **input**. If
@@ -259,7 +259,7 @@ def rfftn(x: array, /, *, s: Sequence[int] = None, axes: Sequence[int] = None, n
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Must have a real-valued floating-point data type.
s: Sequence[int]
size of each transformed axis of the **input**. If
@@ -384,7 +384,7 @@ def ihfft(x: array, /, *, n: Optional[int] = None, axis: int = -1, norm: Literal
Parameters
----------
x: array
- input array. Should have a real-valued floating-point data type.
+ input array. Must have a real-valued floating-point data type.
n: int
length of the transformed axis of the **input**. If