add support for out keyword (#157)

* add support for out keyword

* update docstring

* use NumpyVersion

* update README.md

* fix typos

Author: vtavana

CHANGELOG.md

@@ -1,13 +1,17 @@
 # changelog
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [dev] (MM/DD/YY)
 
 ### Added
-* SciPy interface `mkl_fft.interfaces.scipy_fft` now includes Hermitian FFT functions: `hfft`, `ihfft`, `hfftn`, `ihfftn`, `hfft2`, and `ihfft2` [gh-161](https://github.com/IntelPython/mkl_fft/pull/161)
+* Added Hermitian FFT functions to SciPy interface `mkl_fft.interfaces.scipy_fft`: `hfft`, `ihfft`, `hfftn`, `ihfftn`, `hfft2`, and `ihfft2` [gh-161](https://github.com/IntelPython/mkl_fft/pull/161)
+* Added support for `out` kwarg to all FFT functions in `mkl_fft` and `mkl_fft.interfaces.numpy_fft` [gh-157](https://github.com/IntelPython/mkl_fft/pull/157)
+
+### Changed
+* NumPy interface `mkl_fft.interfaces.numpy_fft` is aligned with numpy-2.* [gh-139](https://github.com/IntelPython/mkl_fft/pull/139), [gh-157](https://github.com/IntelPython/mkl_fft/pull/157)
 
 ## [1.3.14] (04/10/2025)
 

README.md

@@ -1,11 +1,11 @@
-## `mkl_fft` --  a NumPy-based Python interface to Intel (R) MKL FFT functionality
+## `mkl_fft` --  a NumPy-based Python interface to Intel® oneAPI Math Kernel Library (OneMKL) FFT functionality
 [![Conda package](https://github.com/IntelPython/mkl_fft/actions/workflows/conda-package.yml/badge.svg)](https://github.com/IntelPython/mkl_fft/actions/workflows/conda-package.yml)
 [![Editable build using pip and pre-release NumPy](https://github.com/IntelPython/mkl_fft/actions/workflows/build_pip.yaml/badge.svg)](https://github.com/IntelPython/mkl_fft/actions/workflows/build_pip.yaml)
 [![Conda package with conda-forge channel only](https://github.com/IntelPython/mkl_fft/actions/workflows/conda-package-cf.yml/badge.svg)](https://github.com/IntelPython/mkl_fft/actions/workflows/conda-package-cf.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/IntelPython/mkl_fft/badge)](https://securityscorecards.dev/viewer/?uri=github.com/IntelPython/mkl_fft)
 
-`mkl_fft` started as a part of Intel (R) Distribution for Python* optimizations to NumPy, and is now being released
-as a stand-alone package. It can be installed into conda environment using
+`mkl_fft` started as a part of Intel® Distribution for Python* optimizations to NumPy, and is now being released
+as a stand-alone package. It can be installed into conda environment from Intel's channel using:
 
 ```
    conda install -c https://software.repos.intel.com/python/conda mkl_fft
@@ -19,13 +19,13 @@ or from conda-forge channel:
 
 ---
 
-To install mkl_fft Pypi package please use following command:
+To install `mkl_fft` PyPI package please use following command:
 
 ```
    python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_fft
 ```
 
-If command above installs NumPy package from the Pypi, please use following command to install Intel optimized NumPy wheel package from Intel Pypi Cloud:
+If command above installs NumPy package from the PyPI, please use following command to install Intel optimized NumPy wheel package from Intel PyPI Cloud:
 
 ```
    python -m pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_fft numpy==<numpy_version>
@@ -35,7 +35,7 @@ Where `<numpy_version>` should be the latest version from https://software.repos
 
 ---
 
-Since MKL FFT supports performing discrete Fourier transforms over non-contiguously laid out arrays, MKL can be directly
+Since MKL FFT supports performing discrete Fourier transforms over non-contiguously laid out arrays, OneMKL can be directly
 used on any well-behaved floating point array with no internal overlaps for both in-place and not in-place transforms of
 arrays in single and double floating point precision.
 
@@ -50,38 +50,47 @@ More details can be found in SciPy 2017 conference proceedings:
 
 `mkl_fft` implements the following functions:
 
-### Complex transforms, similar to those in `scipy.fft`:
+### complex-to-complex (c2c) transforms:
 
-`fft(x, n=None, axis=-1, overwrite_x=False)`
+`fft(x, n=None, axis=-1, overwrite_x=False, fwd_scale=1.0, out=out)` - 1D FFT, similar to `scipy.fft.fft`
 
-`ifft(x, n=None, axis=-1, overwrite_x=False)`
+`fft2(x, s=None, axes=(-2, -1), overwrite_x=False, fwd_scale=1.0, out=out)` - 2D FFT, similar to `scipy.fft.fft2`
 
-`fft2(x, shape=None, axes=(-2,-1), overwrite_x=False)`
+`fftn(x, s=None, axes=None, overwrite_x=False, fwd_scale=1.0, out=out)` - ND FFT, similar to `scipy.fft.fftn`
 
-`ifft2(x, shape=None, axes=(-2,-1), overwrite_x=False)`
+and similar inverse FFT (`ifft*`) functions.
 
-`fftn(x, n=None, axes=None, overwrite_x=False)`
+### real-to-complex (r2c) and complex-to-real (c2r) transforms:
 
-`ifftn(x, n=None, axes=None, overwrite_x=False)`
+`rfft(x, n=None, axis=-1, fwd_scale=1.0, out=out)` - r2c 1D FFT, similar to `numpy.fft.rfft`
 
-### Real transforms
+`rfft2(x, s=None, axes=(-2, -1), fwd_scale=1.0, out=out)` - r2c 2D FFT, similar to `numpy.fft.rfft2`
 
-`rfftpack(x, n=None, axis=-1, overwrite_x=False)` - real 1D Fourier transform, like `scipy.fftpack.rfft`
+`rfftn(x, s=None, axes=None, fwd_scale=1.0, out=out)` - r2c ND FFT, similar to `numpy.fft.rfftn`
 
-`rfft(x, n=None, axis=-1)` - real 1D Fourier transform, like `numpy.fft.rfft`
+and similar inverse c2r FFT (`irfft*`) functions.
 
-`rfft2(x, s=None, axes=(-2,-1))` - real 2D Fourier transform, like `numpy.fft.rfft2`
-
-`rfftn(x, s=None, axes=None)` - real ND Fourier transform, like `numpy.fft.rfftn`
-
-... and similar `irfft*` functions.
-
-
-The package also provides `mkl_fft.interfaces.numpy_fft` and `mkl_fft.interfaces.scipy_fft` interfaces which provide drop-in replacements for equivalent functions in NumPy and SciPy respectively.
+The package also provides `mkl_fft.interfaces.numpy_fft` and `mkl_fft.interfaces.scipy_fft` interfaces which provide drop-in replacements for equivalent functions in NumPy and SciPy, respectively.
 
 ---
 
-To build `mkl_fft` from sources on Linux:
-  - install a recent version of MKL, if necessary;
-  - execute `source /path_to_oneapi/mkl/latest/env/vars.sh`;
-  - execute `python -m pip install .`
+To build `mkl_fft` from sources on Linux with Intel® OneMKL:
+  - create a virtual environment: `python3 -m venv fft_env`
+  - activate the environment: `source fft_env/bin/activate`
+  - install a recent version of OneMKL, if necessary
+  - execute `source /path_to_oneapi/mkl/latest/env/vars.sh`
+  - `git clone https://github.com/IntelPython/mkl_fft.git mkl_fft`
+  - `cd mkl_fft`
+  - `python -m pip install .`
+  - `cd ..`
+  - `python -c "import mkl_fft"`
+
+To build `mkl_fft` from sources on Linux with conda follow these steps:
+  - `conda create -n fft_env python=3.12 mkl-devel`
+  - `conda activate fft_env`
+  - `export MKLROOT=$CONDA_PREFIX`
+  - `git clone https://github.com/IntelPython/mkl_fft.git mkl_fft`
+  - `cd mkl_fft`
+  - `python -m pip install .`
+  - `cd ..`
+  - `python -c "import mkl_fft"`

conda-recipe-cf/meta.yaml

@@ -43,4 +43,4 @@ about:
     home: http://github.com/IntelPython/mkl_fft
     license: BSD-3-Clause
     license_file: LICENSE.txt
-    summary: NumPy-based implementation of Fast Fourier Transform using Intel (R) Math Kernel Library
+    summary: NumPy-based implementation of Fast Fourier Transform using Intel® oneAPI Math Kernel Library (OneMKL)

conda-recipe/meta.yaml

@@ -43,4 +43,4 @@ about:
     home: http://github.com/IntelPython/mkl_fft
     license: BSD-3-Clause
     license_file: LICENSE.txt
-    summary: NumPy-based implementation of Fast Fourier Transform using Intel (R) Math Kernel Library
+    summary: NumPy-based implementation of Fast Fourier Transform using Intel® oneAPI Math Kernel Library (OneMKL)