replace fwd_scale with norm kwarg in mkl_fft

Author: Vahid Tavanashad

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Enabled support of Python 3.13 [gh-164](https://github.com/IntelPython/mkl_fft/pull/164)
 
 ### Changed
+* Replaced `fwd_scale` parameter with `norm` in `mkl_fft` [gh-189](https://github.com/IntelPython/mkl_fft/pull/189)
 
 ### Fixed
 

README.md

@@ -51,21 +51,21 @@ While using the interfaces module is the recommended way to leverage `mk_fft`, o
 
 ### complex-to-complex (c2c) transforms:
 
-`fft(x, n=None, axis=-1, overwrite_x=False, fwd_scale=1.0, out=None)` - 1D FFT, similar to `scipy.fft.fft`
+`fft(x, n=None, axis=-1, overwrite_x=False, norm=None, out=None)` - 1D FFT, similar to `scipy.fft.fft`
 
-`fft2(x, s=None, axes=(-2, -1), overwrite_x=False, fwd_scale=1.0, out=None)` - 2D FFT, similar to `scipy.fft.fft2`
+`fft2(x, s=None, axes=(-2, -1), overwrite_x=False, norm=None, out=None)` - 2D FFT, similar to `scipy.fft.fft2`
 
-`fftn(x, s=None, axes=None, overwrite_x=False, fwd_scale=1.0, out=None)` - ND FFT, similar to `scipy.fft.fftn`
+`fftn(x, s=None, axes=None, overwrite_x=False, norm=None, out=None)` - ND FFT, similar to `scipy.fft.fftn`
 
 and similar inverse FFT (`ifft*`) functions.
 
 ### real-to-complex (r2c) and complex-to-real (c2r) transforms:
 
-`rfft(x, n=None, axis=-1, fwd_scale=1.0, out=None)` - r2c 1D FFT, similar to `numpy.fft.rfft`
+`rfft(x, n=None, axis=-1, norm=None, out=None)` - r2c 1D FFT, similar to `numpy.fft.rfft`
 
-`rfft2(x, s=None, axes=(-2, -1), fwd_scale=1.0, out=None)` - r2c 2D FFT, similar to `numpy.fft.rfft2`
+`rfft2(x, s=None, axes=(-2, -1), norm=None, out=None)` - r2c 2D FFT, similar to `numpy.fft.rfft2`
 
-`rfftn(x, s=None, axes=None, fwd_scale=1.0, out=None)` - r2c ND FFT, similar to `numpy.fft.rfftn`
+`rfftn(x, s=None, axes=None, norm=None, out=None)` - r2c ND FFT, similar to `numpy.fft.rfftn`
 
 and similar inverse c2r FFT (`irfft*`) functions.
 

mkl_fft/_fft_utils.py

@@ -198,16 +198,12 @@ def _init_nd_shape_and_axes(x, shape, axes):
         raise ValueError("when given, shape values must be integers")
     if axes.shape != shape.shape:
         raise ValueError(
-            "when given, axes and shape arguments"
-            " have to be of the same length"
+            "when given, axes and shape arguments have to be of the same length"
         )
 
     shape = np.where(shape == -1, np.array(x.shape)[axes], shape)
-
     if shape.size != 0 and (shape < 1).any():
-        raise ValueError(
-            "invalid number of data points ({0}) specified".format(shape)
-        )
+        raise ValueError(f"invalid number of data points ({shape}) specified")
 
     return shape, axes
 
@@ -299,7 +295,7 @@ def _pad_array(arr, s, axes):
         try:
             shp_i = arr_shape[ai]
         except IndexError:
-            raise ValueError("Invalid axis (%d) specified" % ai)
+            raise ValueError(f"Invalid axis {ai} specified")
         if si > shp_i:
             no_padding = False
             pad_widths[ai] = (0, si - shp_i)
@@ -335,7 +331,7 @@ def _trim_array(arr, s, axes):
         try:
             shp_i = arr_shape[ai]
         except IndexError:
-            raise ValueError("Invalid axis (%d) specified" % ai)
+            raise ValueError(f"Invalid axis {ai} specified")
         if si < shp_i:
             no_trim = False
             ind[ai] = slice(None, si, None)

mkl_fft/_mkl_fft.py

@@ -24,7 +24,12 @@
 # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-from ._fft_utils import _c2c_fftnd_impl, _c2r_fftnd_impl, _r2c_fftnd_impl
+from ._fft_utils import (
+    _c2c_fftnd_impl,
+    _c2r_fftnd_impl,
+    _compute_fwd_scale,
+    _r2c_fftnd_impl,
+)
 
 # pylint: disable=no-name-in-module
 from ._pydfti import _c2c_fft1d_impl, _c2r_fft1d_impl, _r2c_fft1d_impl
@@ -45,85 +50,103 @@
 ]
 
 
-def fft(x, n=None, axis=-1, out=None, overwrite_x=False, fwd_scale=1.0):
+def fft(x, n=None, axis=-1, norm=None, out=None, overwrite_x=False):
+    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
     return _c2c_fft1d_impl(
         x,
         n=n,
         axis=axis,
         out=out,
         overwrite_x=overwrite_x,
         direction=+1,
-        fsc=fwd_scale,
+        fsc=fsc,
     )
 
 
-def ifft(x, n=None, axis=-1, out=None, overwrite_x=False, fwd_scale=1.0):
+def ifft(x, n=None, axis=-1, norm=None, out=None, overwrite_x=False):
+    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
     return _c2c_fft1d_impl(
         x,
         n=n,
         axis=axis,
         out=out,
         overwrite_x=overwrite_x,
         direction=-1,
-        fsc=fwd_scale,
+        fsc=fsc,
     )
 
 
-def fft2(x, s=None, axes=(-2, -1), out=None, overwrite_x=False, fwd_scale=1.0):
+def fft2(x, s=None, axes=(-2, -1), norm=None, out=None, overwrite_x=False):
     return fftn(
-        x, s=s, axes=axes, out=out, overwrite_x=overwrite_x, fwd_scale=fwd_scale
+        x,
+        s=s,
+        axes=axes,
+        norm=norm,
+        out=out,
+        overwrite_x=overwrite_x,
     )
 
 
-def ifft2(x, s=None, axes=(-2, -1), out=None, overwrite_x=False, fwd_scale=1.0):
+def ifft2(x, s=None, axes=(-2, -1), norm=None, out=None, overwrite_x=False):
     return ifftn(
-        x, s=s, axes=axes, out=out, overwrite_x=overwrite_x, fwd_scale=fwd_scale
+        x,
+        s=s,
+        axes=axes,
+        norm=norm,
+        out=out,
+        overwrite_x=overwrite_x,
     )
 
 
-def fftn(x, s=None, axes=None, out=None, overwrite_x=False, fwd_scale=1.0):
+def fftn(x, s=None, axes=None, norm=None, out=None, overwrite_x=False):
+    fsc = _compute_fwd_scale(norm, s, x.shape)
     return _c2c_fftnd_impl(
         x,
         s=s,
         axes=axes,
         out=out,
         overwrite_x=overwrite_x,
         direction=+1,
-        fsc=fwd_scale,
+        fsc=fsc,
     )
 
 
-def ifftn(x, s=None, axes=None, out=None, overwrite_x=False, fwd_scale=1.0):
+def ifftn(x, s=None, axes=None, norm=None, out=None, overwrite_x=False):
+    fsc = _compute_fwd_scale(norm, s, x.shape)
     return _c2c_fftnd_impl(
         x,
         s=s,
         axes=axes,
         out=out,
         overwrite_x=overwrite_x,
         direction=-1,
-        fsc=fwd_scale,
+        fsc=fsc,
     )
 
 
-def rfft(x, n=None, axis=-1, out=None, fwd_scale=1.0):
-    return _r2c_fft1d_impl(x, n=n, axis=axis, out=out, fsc=fwd_scale)
+def rfft(x, n=None, axis=-1, norm=None, out=None):
+    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
+    return _r2c_fft1d_impl(x, n=n, axis=axis, out=out, fsc=fsc)
 
 
-def irfft(x, n=None, axis=-1, out=None, fwd_scale=1.0):
-    return _c2r_fft1d_impl(x, n=n, axis=axis, out=out, fsc=fwd_scale)
+def irfft(x, n=None, axis=-1, norm=None, out=None):
+    fsc = _compute_fwd_scale(norm, n, 2 * (x.shape[axis] - 1))
+    return _c2r_fft1d_impl(x, n=n, axis=axis, out=out, fsc=fsc)
 
 
-def rfft2(x, s=None, axes=(-2, -1), out=None, fwd_scale=1.0):
-    return rfftn(x, s=s, axes=axes, out=out, fwd_scale=fwd_scale)
+def rfft2(x, s=None, axes=(-2, -1), norm=None, out=None):
+    return rfftn(x, s=s, axes=axes, norm=norm, out=out)
 
 
-def irfft2(x, s=None, axes=(-2, -1), out=None, fwd_scale=1.0):
-    return irfftn(x, s=s, axes=axes, out=out, fwd_scale=fwd_scale)
+def irfft2(x, s=None, axes=(-2, -1), norm=None, out=None):
+    return irfftn(x, s=s, axes=axes, norm=norm, out=out)
 
 
-def rfftn(x, s=None, axes=None, out=None, fwd_scale=1.0):
-    return _r2c_fftnd_impl(x, s=s, axes=axes, out=out, fsc=fwd_scale)
+def rfftn(x, s=None, axes=None, norm=None, out=None):
+    fsc = _compute_fwd_scale(norm, s, x.shape)
+    return _r2c_fftnd_impl(x, s=s, axes=axes, out=out, fsc=fsc)
 
 
-def irfftn(x, s=None, axes=None, out=None, fwd_scale=1.0):
-    return _c2r_fftnd_impl(x, s=s, axes=axes, out=out, fsc=fwd_scale)
+def irfftn(x, s=None, axes=None, norm=None, out=None):
+    fsc = _compute_fwd_scale(norm, s, x.shape)
+    return _c2r_fftnd_impl(x, s=s, axes=axes, out=out, fsc=fsc)

mkl_fft/interfaces/_numpy_fft.py

@@ -36,7 +36,7 @@
 
 import mkl_fft
 
-from .._fft_utils import _compute_fwd_scale, _swap_direction
+from .._fft_utils import _swap_direction
 from ._float_utils import _downcast_float128_array
 
 __all__ = [
@@ -120,10 +120,9 @@ def fft(a, n=None, axis=-1, norm=None, out=None):
 
     """
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
 
     return _trycall(
-        mkl_fft.fft, (x,), {"n": n, "axis": axis, "fwd_scale": fsc, "out": out}
+        mkl_fft.fft, (x,), {"n": n, "axis": axis, "norm": norm, "out": out}
     )
 
 
@@ -135,10 +134,9 @@ def ifft(a, n=None, axis=-1, norm=None, out=None):
 
     """
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
 
     return _trycall(
-        mkl_fft.ifft, (x,), {"n": n, "axis": axis, "fwd_scale": fsc, "out": out}
+        mkl_fft.ifft, (x,), {"n": n, "axis": axis, "norm": norm, "out": out}
     )
 
 
@@ -171,10 +169,9 @@ def fftn(a, s=None, axes=None, norm=None, out=None):
     """
     x = _downcast_float128_array(a)
     s, axes = _cook_nd_args(x, s, axes)
-    fsc = _compute_fwd_scale(norm, s, x.shape)
 
     return _trycall(
-        mkl_fft.fftn, (x,), {"s": s, "axes": axes, "fwd_scale": fsc, "out": out}
+        mkl_fft.fftn, (x,), {"s": s, "axes": axes, "norm": norm, "out": out}
     )
 
 
@@ -187,12 +184,11 @@ def ifftn(a, s=None, axes=None, norm=None, out=None):
     """
     x = _downcast_float128_array(a)
     s, axes = _cook_nd_args(x, s, axes)
-    fsc = _compute_fwd_scale(norm, s, x.shape)
 
     return _trycall(
         mkl_fft.ifftn,
         (x,),
-        {"s": s, "axes": axes, "fwd_scale": fsc, "out": out},
+        {"s": s, "axes": axes, "norm": norm, "out": out},
     )
 
 
@@ -204,10 +200,9 @@ def rfft(a, n=None, axis=-1, norm=None, out=None):
 
     """
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
 
     return _trycall(
-        mkl_fft.rfft, (x,), {"n": n, "axis": axis, "fwd_scale": fsc, "out": out}
+        mkl_fft.rfft, (x,), {"n": n, "axis": axis, "norm": norm, "out": out}
     )
 
 
@@ -219,12 +214,11 @@ def irfft(a, n=None, axis=-1, norm=None, out=None):
 
     """
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, 2 * (x.shape[axis] - 1))
 
     return _trycall(
         mkl_fft.irfft,
         (x,),
-        {"n": n, "axis": axis, "fwd_scale": fsc, "out": out},
+        {"n": n, "axis": axis, "norm": norm, "out": out},
     )
 
 
@@ -257,12 +251,11 @@ def rfftn(a, s=None, axes=None, norm=None, out=None):
     """
     x = _downcast_float128_array(a)
     s, axes = _cook_nd_args(x, s, axes)
-    fsc = _compute_fwd_scale(norm, s, x.shape)
 
     return _trycall(
         mkl_fft.rfftn,
         (x,),
-        {"s": s, "axes": axes, "fwd_scale": fsc, "out": out},
+        {"s": s, "axes": axes, "norm": norm, "out": out},
     )
 
 
@@ -276,12 +269,11 @@ def irfftn(a, s=None, axes=None, norm=None, out=None):
 
     x = _downcast_float128_array(a)
     s, axes = _cook_nd_args(x, s, axes, invreal=True)
-    fsc = _compute_fwd_scale(norm, s, x.shape)
 
     return _trycall(
         mkl_fft.irfftn,
         (x,),
-        {"s": s, "axes": axes, "fwd_scale": fsc, "out": out},
+        {"s": s, "axes": axes, "norm": norm, "out": out},
     )
 
 
@@ -295,12 +287,10 @@ def hfft(a, n=None, axis=-1, norm=None, out=None):
     """
     norm = _swap_direction(norm)
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, 2 * (x.shape[axis] - 1))
-
     return _trycall(
         mkl_fft.irfft,
         (np.conjugate(x),),
-        {"n": n, "axis": axis, "fwd_scale": fsc, "out": out},
+        {"n": n, "axis": axis, "norm": norm, "out": out},
     )
 
 
@@ -313,10 +303,9 @@ def ihfft(a, n=None, axis=-1, norm=None, out=None):
     """
     norm = _swap_direction(norm)
     x = _downcast_float128_array(a)
-    fsc = _compute_fwd_scale(norm, n, x.shape[axis])
 
     result = _trycall(
-        mkl_fft.rfft, (x,), {"n": n, "axis": axis, "fwd_scale": fsc, "out": out}
+        mkl_fft.rfft, (x,), {"n": n, "axis": axis, "norm": norm, "out": out}
     )
 
     np.conjugate(result, out=result)