Add Intel mkl_fft support for fft module and GitHub Action with Intel Python

.github/workflows/build-mkl.yaml

@@ -0,0 +1,41 @@
+name: PyLops Testing with Intel oneAPI Math Kernel Library(oneMKL)
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        platform: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    runs-on: ${{ matrix.platform }}
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Get history and tags for SCM versioning to work
+      run: |
+        git fetch --prune --unshallow
+        git fetch --depth=1 origin +refs/tags/*:refs/tags/*
+    - uses: conda-incubator/setup-miniconda@v3.2.0
+      with:
+        use-mamba: true
+        channels: https://software.repos.intel.com/python/conda, conda-forge
+        conda-remove-defaults: true
+        python-version: ${{ matrix.python-version }}
+        activate-environment: mkl-test-env
+    - name: Install dependencies
+      run: |
+        conda install -y pyfftw
+        pip install -r requirements-intel-mkl.txt
+        pip install -r requirements-dev.txt
+        pip install -r requirements-torch.txt
+    - name: Install pylops
+      run: |
+        python -m setuptools_scm
+        pip install .
+    - name: Tests with pytest
+      run: |
+        pytest

.github/workflows/build.yaml

@@ -25,6 +25,7 @@ jobs:
         python -m pip install --upgrade pip setuptools
         pip install flake8 pytest
         pip install -r requirements-dev.txt
+        pip install -r requirements-pyfftw.txt
         pip install -r requirements-torch.txt
     - name: Install pylops
       run: |

.github/workflows/codacy-coverage-reporter.yaml

@@ -27,6 +27,7 @@ jobs:
         python -m pip install --upgrade pip
         pip install flake8 pytest
         pip install -r requirements-dev.txt
+        pip install -r requirements-pyfftw.txt
         pip install -r requirements-torch.txt
     - name: Install pylops
       run: |

Makefile

@@ -1,7 +1,7 @@
 PIP := $(shell command -v pip3 2> /dev/null || command which pip 2> /dev/null)
 PYTHON := $(shell command -v python3 2> /dev/null || command which python 2> /dev/null)
 
-.PHONY: install dev-install dev-install_gpu install_conda dev-install_conda dev-install_conda_arm tests tests_cpu_ongpu tests_gpu doc docupdate servedoc lint typeannot coverage
+.PHONY: install dev-install dev-install_intel_mkl dev-install_gpu install_conda dev-install_conda dev-install_conda_intel_mkl dev-install_conda_arm tests tests_cpu_ongpu tests_gpu doc docupdate servedoc lint typeannot coverage
 
 pipcheck:
 ifndef PIP
@@ -22,6 +22,13 @@ install:
 dev-install:
 	make pipcheck
 	$(PIP) install -r requirements-dev.txt &&\
+	$(PIP) install -r requirements-pyfftw.txt &&\
+	$(PIP) install -r requirements-torch.txt && $(PIP) install -e .
+
+dev-install_intel_mkl:
+	make pipcheck
+	$(PIP) install -r requirements-intel-mkl.txt &&\
+	$(PIP) install -r requirements-dev.txt &&\
 	$(PIP) install -r requirements-torch.txt && $(PIP) install -e .
 
 dev-install_gpu:
@@ -35,6 +42,9 @@ install_conda:
 dev-install_conda:
 	conda env create -f environment-dev.yml && source ${CONDA_PREFIX}/etc/profile.d/conda.sh && conda activate pylops && pip install -e .
 
+dev-install_conda_intel_mkl:
+	conda env create -f environment-dev-intel-mkl.yml && source ${CONDA_PREFIX}/etc/profile.d/conda.sh && conda activate pylops && pip install -e .
+
 dev-install_conda_arm:
 	conda env create -f environment-dev-arm.yml && source ${CONDA_PREFIX}/etc/profile.d/conda.sh && conda activate pylops && pip install -e .
 

azure-pipelines.yml

@@ -62,6 +62,7 @@ jobs:
   - script: |
       python -m pip install --upgrade pip setuptools wheel django
       pip install -r requirements-dev.txt
+      pip install -r requirements-pyfftw.txt
       pip install -r requirements-torch.txt
       pip install .
     displayName: 'Install prerequisites and library'
@@ -92,6 +93,7 @@ jobs:
   - script: |
       python -m pip install --upgrade pip setuptools wheel django
       pip install -r requirements-dev.txt
+      pip install -r requirements-pyfftw.txt
       pip install -r requirements-torch.txt
       pip install .
     displayName: 'Install prerequisites and library'

docs/source/installation.rst

@@ -209,7 +209,7 @@ library will ensure optimal performance of PyLops when using only *required depe
 
 We strongly encourage using the Anaconda Python distribution as
 NumPy and SciPy will, when available, be automatically linked to `Intel MKL <https://software.intel.com/en-us/mkl>`_, the most performant library for basic linear algebra
-operations to date (see `Markus Beuckelmann's benchmarks <http://markus-beuckelmann.de/blog/boosting-numpy-blas.html>`_).
+operations to date.
 The PyPI version installed with ``pip``, however, will default to `OpenBLAS <https://www.openblas.net/>`_.
 For more information, see `NumPy's section on BLAS <https://numpy.org/install/#numpy-packages--accelerated-linear-algebra-libraries>`_.
 
@@ -224,14 +224,13 @@ run the following commands in a Python interpreter:
    print(sp.__config__.show())
 
 
-Intel also provides `NumPy <https://pypi.org/project/intel-numpy/>`__ and `SciPy <https://pypi.org/project/intel-scipy/>`__ replacement packages in PyPI ``intel-numpy`` and ``intel-scipy``, respectively, which link to Intel MKL.
+Intel also provides `NumPy <https://pypi.org/project/intel-numpy/>`__ and `SciPy <https://pypi.org/project/intel-scipy/>`__ replacement packages in PyPI, namely ``intel-numpy`` and ``intel-scipy``, which link to Intel MKL.
 These are an option for an environment without ``conda`` that needs Intel MKL without requiring manual compilation.
 
 .. warning::
 
    ``intel-numpy`` and ``intel-scipy`` not only link against Intel MKL, but also substitute NumPy and
-   SciPy FFTs for `Intel MKL FFT <https://pypi.org/project/mkl-fft/>`_. **MKL FFT is not supported
-   and may break PyLops**.
+   SciPy FFTs with `Intel MKL FFT <https://pypi.org/project/mkl-fft/>`_.
 
 
 Multithreading
@@ -297,25 +296,27 @@ of PyLops in such a way that if an *optional* dependency is not present in your
 a safe fallback to one of the required dependencies will be enforced.
 
 When available in your system, we recommend using the Conda package manager and install all the
-required and optional dependencies of PyLops at once using the command:
+required and some of the optional dependencies of PyLops at once using the command:
 
 .. code-block:: bash
 
    >> conda install --channel conda-forge pylops
 
 in this case all dependencies will be installed from their Conda distributions.
 
-Alternatively, from version ``1.4.0`` optional dependencies can also be installed as
-part of the pip installation via:
+Alternatively, from version ``1.4.0`` some of the optional dependencies can also be 
+installed as part of the pip installation via:
 
 .. code-block:: bash
 
    >> pip install pylops[advanced]
 
 Dependencies are however installed from their PyPI wheels.
-An exception is however represented by CuPy. This library is **not** installed
+
+Finally, note that CuPy and JAX are not **not** installed
 automatically. Users interested to accelerate their computations with the aid
-of GPUs should install it prior to installing PyLops as described in :ref:`OptionalGPU`.
+of GPUs should install either or both of them prior to installing PyLops as 
+described in :ref:`OptionalGPU`.
 
 .. note::
 
@@ -324,11 +325,13 @@ of GPUs should install it prior to installing PyLops as described in :ref:`Optio
    PyLops via ``make dev-install_conda`` (``conda``) or ``make dev-install`` (``pip``).
 
 
-In alphabetic order:
+More details about the installation process for the different optional dependencies are described 
+in the following (an asterisc is used to indicate those dependencies that are automatically installed
+when installing PyLops from conda-forge or via ``pip install pylops[advanced]``):
 
 
-dtcwt
------
+dtcwt*
+------
 
 `dtcwt <https://dtcwt.readthedocs.io/en/0.12.0/>`_ is a library used to implement the DT-CWT operators.
 
@@ -356,13 +359,16 @@ Install it via ``pip`` with
    >> pip install devito
 
 
-FFTW
-----
-Three different "engines" are provided by the :py:class:`pylops.signalprocessing.FFT` operator:
-``engine="numpy"`` (default), ``engine="scipy"`` and ``engine="fftw"``.
+FFTW* and MKL-FFT
+-----------------
+Four different "engines" are provided by the :py:class:`pylops.signalprocessing.FFT` operator:
+``engine="numpy"`` (default), ``engine="scipy"``, ``engine="fftw"`` and ``engine="mkl_fft"``.
+Similarly, the :py:class:`pylops.signalprocessing.FFT2D` and 
+the :py:class:`pylops.signalprocessing.FFTND` operators come with three "engines", namely
+``engine="numpy"`` (default), ``engine="scipy"``, and ``engine="mkl_fft"``.
 
 The first two engines are part of the required PyLops dependencies.
-The latter implements the well-known `FFTW <http://www.fftw.org>`_
+The third implements the well-known `FFTW <http://www.fftw.org>`_
 via the Python wrapper :py:class:`pyfftw.FFTW`. While this optimized FFT tends to
 outperform the other two in many cases, it is not included by default.
 To use this library, install it manually either via ``conda``:
@@ -377,16 +383,52 @@ or via pip:
 
    >> pip install pyfftw
 
+The fourth implements **Intel MKL FFT** via the Python interface `mkl_fft <https://github.com/IntelPython/mkl_fft>`_.
+This provides access to Intel’s oneMKL Fourier Transform routines, enabling efficient FFT computations with performance
+close to native C/Intel® oneMKL
+
+To use this library, you can install it using ``conda``:
+
+.. code-block:: bash
+
+   >> conda install --channel https://software.repos.intel.com/python/conda --channel conda-forge mkl_fft
+
+or via pip:
+
+.. code-block:: bash
+
+   >> pip install --index-url https://software.repos.intel.com/python/pypi --extra-index-url https://pypi.org/simple mkl_fft
+
+Installing ``mkl-fft`` triggers the installation of Intel-optimized versions of `NumPy <https://pypi.org/project/intel-numpy/>`__ and
+`SciPy <https://pypi.org/project/intel-scipy/>`__, which redirects ``numpy.fft`` and ``scipy.fft`` to use MKL FFT routines.
+As a result, all FFT operations and computational backends leverage Intel MKL for optimal performance.
+
+Although the library can run without Intel-optimized NumPy and SciPy, maximum performance is achieved when using NumPy and
+SciPy built with Intel’s Math Kernel Library (MKL) alongside Intel Python.
+
 .. note::
-   FFTW is only available for :py:class:`pylops.signalprocessing.FFT`,
-   not :py:class:`pylops.signalprocessing.FFT2D` or :py:class:`pylops.signalprocessing.FFTND`.
+   `mkl_fft` is not supported on macOS
 
 .. warning::
-   Intel MKL FFT is not supported.
 
+   ``pyFFTW`` may not work correctly with NumPy + MKL. To avoid issues, it is recommended to build ``pyFFTW`` from
+   source after setting the ``STATIC_FFTW_DIR`` environment variable to the absolute path of the static FFTW
+   libraries.
 
-Numba
------
+   If the following environment variables are set before installing ``pyFFTW``, compatibility problems with MKL
+   should not occur:
+
+   1. ``export STATIC_FFTW_DIR=${PREFIX}/lib``
+      (where ``${PREFIX}`` is the base of the current Anaconda environment with
+      the ``fftw`` package installed)
+
+   2. ``export CFLAGS="$CFLAGS -Wl,-Bsymbolic"``
+
+   Alternatively, you can install ``pyFFTW`` directly with ``conda``, since the updated recipe is already available
+   and works without any manual adjustments.
+
+Numba*
+------
 Although we always strive to write code for forward and adjoint operators that takes advantage of
 the perks of NumPy and SciPy (e.g., broadcasting, ufunc), in some case we may end up using for loops
 that may lead to poor performance. In those cases we may decide to implement alternative (optional)
@@ -445,7 +487,6 @@ It can also be checked dynamically with ``numba.config.NUMBA_DEFAULT_NUM_THREADS
 
 PyMC and PyTensor
 -----------------
-
 `PyTensor <https://pytensor.readthedocs.io/en/latest/>`_ is used to allow seamless integration between PyLops and 
 `PyMC <https://www.pymc.io/welcome.html>`_ operators.
 Install both of them via ``conda`` with:
@@ -464,8 +505,8 @@ or via ``pip`` with
    OSX users may experience a ``CompileError`` error when using PyTensor. This can be solved by adding 
    ``pytensor.config.gcc__cxxflags = "-Wno-c++11-narrowing"`` after ``import pytensor``.
 
-PyWavelets
-----------
+PyWavelets*
+-----------
 `PyWavelets <https://pywavelets.readthedocs.io/en/latest/>`_ is used to implement the wavelet operators.
 Install it via ``conda`` with:
 
@@ -480,8 +521,8 @@ or via ``pip`` with
    >> pip install PyWavelets
 
 
-scikit-fmm
-----------
+scikit-fmm*
+-----------
 `scikit-fmm <https://github.com/scikit-fmm/scikit-fmm>`_ is a library which implements the
 fast marching method. It is used in PyLops to compute traveltime tables in the
 initialization of :py:class:`pylops.waveeqprocessing.Kirchhoff`
@@ -499,8 +540,8 @@ or with ``pip`` via
    >> pip install scikit-fmm
 
 
-SPGL1
------
+SPGL1*
+------
 `SPGL1 <https://spgl1.readthedocs.io/en/latest/>`_ is used to solve sparsity-promoting
 basis pursuit, basis pursuit denoise, and Lasso problems
 in :py:func:`pylops.optimization.sparsity.SPGL1` solver.

environment-dev-intel-mkl.yml

@@ -0,0 +1,45 @@
+name: pylops
+channels:
+  - https://software.repos.intel.com/python/conda
+  - conda-forge
+  - defaults
+  - numba
+dependencies:
+  - python>=3.10.0
+  - pip
+  - numpy>=2.0.0
+  - scipy>=1.13.0
+  - pyfftw
+  - pywavelets
+  - sympy
+  - pymc>=5
+  - pytensor
+  - matplotlib
+  - ipython
+  - pytest
+  - Sphinx
+  - numpydoc
+  - numba
+  - icc_rt
+  - pre-commit
+  - autopep8
+  - isort
+  - black
+  - mkl_fft
+  - pip:
+    - torch
+    - devito
+    # - dtcwt (until numpy>=2.0.0 is supported)
+    - scikit-fmm
+    - spgl1
+    - jax
+    - pytest-runner
+    - setuptools_scm
+    - pydata-sphinx-theme
+    - pooch
+    - sphinx-gallery
+    - nbsphinx
+    - sphinxemoji
+    - image
+    - flake8
+    - mypy