Merge pull request #2035 from leofang/fft_plan_arg

document new features in `cupy.fft` and `cupyx.scipy.fftpack`

docs/source/reference/fft.rst

@@ -69,3 +69,7 @@ Code compatibility features
 ---------------------------
 FFT functions of NumPy alway return numpy.ndarray which type is ``numpy.complex128`` or ``numpy.float64``.
 CuPy functions do not follow the behavior, they will return ``numpy.complex64`` or ``numpy.float32`` if the type of the input is ``numpy.float16``, ``numpy.float32``, or ``numpy.complex64``.
+
+Internally, ``cupy.fft`` always generates a *cuFFT plan* (see the `cuFFT documentation`_ for detail) corresponding to the desired transform. When possible, an n-dimensional plan will be used, as opposed to applying separate 1D plans for each axis to be transformed. Using n-dimensional planning can provide better performance for multidimensional transforms, but requires more GPU memory than separable 1D planning. The user can disable n-dimensional planning by setting ``cupy.fft.config.enable_nd_planning = False``. This ability to adjust the planning type is a deviation from the NumPy API, which does not use precomputed FFT plans.
+
+.. _cuFFT documentation: https://docs.nvidia.com/cuda/cufft/index.html

docs/source/reference/fftpack.rst

@@ -24,4 +24,8 @@ Fast Fourier Transforms
 
 Code compatibility features
 ---------------------------
-The ``get_fft_plan`` function has no counterpart in ``scipy.fftpack``. It returns a cuFFT plan that can be passed to the FFT functions in this module (using the argument ``plan``) to accelarate the computation.
+1. The ``get_fft_plan`` function has no counterpart in ``scipy.fftpack``. It returns a cuFFT plan that can be passed to the FFT functions in this module (using the argument ``plan``) to accelarate the computation. The argument ``plan`` is currently experimental and the interface may be changed in the future version.
+
+2. The boolean switch ``cupy.fft.config.enable_nd_planning`` also affects the FFT functions in this module, see :doc:`./fft`. This switch is neglected when planning manually using ``get_fft_plan``.
+
+3. Like in ``scipy.fftpack``, all FFT functions in this module have an optional argument ``overwrite_x`` (default is ``False``), which has the same semantics as in ``scipy.fftpack``: when it is set to ``True``, the input array ``x`` *can* (not *will*) be destroyed and replaced by the output. For this reason, when an in-place FFT is desired, the user should always reassign the input in the following manner: ``x = cupyx.scipy.fftpack.fft(x, ..., overwrite_x=True, ...)``.