Merge pull request #582 from amd-jnovotny/rocfft-refactor-rocmrel64

Auto-submit by Jenkins

Author: rocm-ci

LICENSE.md

@@ -1,4 +1,4 @@
-# LICENSE
+# License
 
 Copyright (C) 2016 - 2025 Advanced Micro Devices, Inc. All rights reserved.
 

README.md

@@ -70,14 +70,14 @@ You can install rocFFT using pre-built packages or building from source.
 
     ```bash
     mkdir build && cd build
-    cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_C_COMPILER=amdclang_PREFIX_PATH=/path/to/rocFFT-lib ..
+    cmake -DCMAKE_CXX_COMPILER=amdclang++ -DCMAKE_PREFIX_PATH=/path/to/rocFFT-lib ..
     make -j
     ```
 
     To install client dependencies on Ubuntu, run:
 
     ```bash
-    sudo apt install libgtest-dev libfftw3-dev
+    sudo apt install libgtest-dev libfftw3-dev libboost-dev
     ```
 
     We use version 1.11 of GoogleTest.

docs/conceptual/fft-computation.rst

@@ -0,0 +1,39 @@
+.. meta::
+  :description: rocFFT computations
+  :keywords: rocFFT, ROCm, API, documentation, install, computation, fft
+
+.. _fft-computation:
+
+********************************************************************
+FFT computation
+********************************************************************
+
+rocFFT is an implementation of the Discrete Fourier Transform (DFT) that makes use of symmetries in the DFT definition to
+reduce the mathematical complexity from :math:`O(N^2)` to :math:`O(N \log N)`.
+
+How does the library compute DFTs?
+==================================
+
+Here are the formulas for 1D, 2D, and 3D complex DFTs:
+
+For a 1D complex DFT:
+
+:math:`{\tilde{x}}_j = \sum_{k=0}^{n-1}x_k\exp\left({\pm i}{{2\pi jk}\over{n}}\right)\hbox{ for } j=0,1,\ldots,n-1`
+
+Where :math:`x_k` is the complex data to be transformed, :math:`\tilde{x}_j` is the transformed data,
+and the sign :math:`\pm`
+determines the direction of the transform: :math:`-` for forward and :math:`+` for backward.
+
+For a 2D complex DFT:
+
+:math:`{\tilde{x}}_{jk} = \sum_{q=0}^{m-1}\sum_{r=0}^{n-1}x_{rq}\exp\left({\pm i} {{2\pi jr}\over{n}}\right)\exp\left({\pm i}{{2\pi kq}\over{m}}\right)`
+
+For :math:`j=0,1,\ldots,n-1\hbox{ and } k=0,1,\ldots,m-1`, where :math:`x_{rq}` is the complex data to be transformed,
+:math:`\tilde{x}_{jk}` is the transformed data, and the sign :math:`\pm` determines the direction of the transform.
+
+For a 3D complex DFT:
+
+:math:`\tilde{x}_{jkl} = \sum_{s=0}^{p-1}\sum_{q=0}^{m-1}\sum_{r=0}^{n-1}x_{rqs}\exp\left({\pm i} {{2\pi jr}\over{n}}\right)\exp\left({\pm i}{{2\pi kq}\over{m}}\right)\exp\left({\pm i}{{2\pi ls}\over{p}}\right)`
+
+For :math:`j=0,1,\ldots,n-1\hbox{ and } k=0,1,\ldots,m-1\hbox{ and } l=0,1,\ldots,p-1`, where :math:`x_{rqs}` is the complex data to
+be transformed, :math:`\tilde{x}_{jkl}` is the transformed data, and the sign :math:`\pm` determines the direction of the transform.

docs/how-to/distributed-transforms.rst

@@ -1,70 +1,73 @@
+.. meta::
+  :description: Distributed transforms in rocFFT
+  :keywords: rocFFT, ROCm, API, documentation, distributed transform
+
+
 .. _distributed-transforms:
 
 ********************************************************************
 Distributed transforms
 ********************************************************************
 
 rocFFT can optionally distribute FFTs across multiple devices in a
-single process, or across multiple MPI ranks.  To perform distributed
-transforms, users must describe their input and output data layouts
+single process or across multiple Message Passing Interface (MPI) ranks. To perform distributed
+transforms, describe the input and output data layouts
 as :ref:`fields<input_output_fields>`.
 
 Multiple devices in a single process
 ====================================
 
-A transform may be distributed across multiple devices in a single
+A transform can be distributed across multiple devices in a single
 process by passing distinct device IDs to
-:cpp:func:`rocfft_brick_create` for bricks in the input and output
+:cpp:func:`rocfft_brick_create` to create bricks in the input and output
 fields.
 
 Support for single-process multi-device transforms was introduced in
 ROCm 6.0 with rocFFT 1.0.25.
 
-Message Passing Interface (MPI)
+Message Passing Interface
 ===============================
 
-MPI allows for distributing the transform across multiple processes,
+MPI lets you distribute the transform across multiple processes,
 organized into MPI ranks.
 
+To turn on rocFFT MPI support, enable the ``ROCFFT_MPI_ENABLE`` CMake option
+when building the library. By default, this option
+is off. To use Cray MPI, enable the ``ROCFFT_CRAY_MPI_ENABLE`` CMake option.
+
+Additionally, rocFFT MPI support requires a GPU-aware MPI library
+that supports transferring data to and from HIP devices.
+
 Support for MPI transforms was introduced in ROCm 6.3 with rocFFT
 1.0.29.
 
 .. note::
 
-   rocFFT MPI support is only available when the library is built
-   with the `ROCFFT_MPI_ENABLE` CMake option enabled.  By default it
-   is off.
-
-   Additionally, rocFFT MPI support requires a GPU-aware MPI library
-   with support for transferring data to/from HIP devices.
-
-   Finally, rocFFT API calls made on different ranks may return
-   different values.  Users must take care to ensure that all ranks
+   rocFFT API calls made on different ranks might return
+   different values. Application developers must ensure that all ranks
    have successfully created their plans before attempting to execute
-   a distributed transform, and it is possible for one rank to fail
-   to create/execute a plan while the others succeed.
+   a distributed transform. One rank can fail
+   to create or execute a plan while the others succeed.
 
-To perform a transform across multiple MPI ranks, additional steps
-are required to distribute the computation:
+To distribute a transform across multiple MPI ranks, the
+following additional steps are required:
 
 #. Each rank calls :cpp:func:`rocfft_plan_description_set_comm` to
-   add an MPI communicator to an allocated plan description.  rocFFT
-   will distribute the computation across all ranks in the
+   add an MPI communicator to an allocated plan description. rocFFT
+   distributes the computation across all ranks in the
    communicator.
 
 #. Each rank allocates the same fields and calls
    :cpp:func:`rocfft_plan_description_add_infield` and
    :cpp:func:`rocfft_plan_description_add_outfield` on the plan
-   description.  However, each rank must only call
+   description. However, each rank must only call
    :cpp:func:`rocfft_brick_create` and
    :cpp:func:`rocfft_field_add_brick` for bricks that reside on that
-   rank.
-
-   A brick resides on exactly one rank, but each rank may have zero
-   or more bricks on it.
+   rank. A brick resides on exactly one rank. Each rank can have zero
+   or more bricks associated to it.
 
 #. Each rank in the communicator calls
-   :cpp:func:`rocfft_plan_create`.  At this time rocFFT will distribute
+   :cpp:func:`rocfft_plan_create`. rocFFT then uses this information to distribute
    the supplied brick information between all of the ranks.
 
 #. Each rank in the communicator calls :cpp:func:`rocfft_execute`.
@@ -73,8 +76,8 @@ are required to distribute the computation:
    of the current rank.
 
    The pointers must be provided in the same order in which the bricks were
-   added to the field (via calls to :cpp:func:`rocfft_field_add_brick`), and
-   must point to memory on the device that was specified at that time.
+   added to the field (using calls to :cpp:func:`rocfft_field_add_brick`) and
+   must point to the memory on the device that was specified at that time.
 
-   For in-place transforms, only pass input pointers and pass an
+   For in-place transforms, only pass the input pointers and use an
    empty array of output pointers.

docs/how-to/load-store-callbacks.rst

@@ -1,103 +1,86 @@
 .. meta::
-  :description: rocFFT documentation and API reference library
-  :keywords: rocFFT, ROCm, API, documentation
+  :description: How to load and store callbacks in rocFFT
+  :keywords: rocFFT, ROCm, API, documentation, callbacks
 
 .. _load-store-callbacks:
 
 ********************************************************************
-Load and Store Callbacks
+Load and store callbacks
 ********************************************************************
 
 rocFFT includes experimental functionality to call user-defined device functions
-when loading input from global memory at the start of a transform, or
-when storing output to global memory at the end of a transform.
+when loading input from global memory at the transform start or
+when storing output to global memory at the transform end.
 
-These user-defined callback functions may be optionally supplied
+These optional user-defined callback functions can be supplied
 to the library using
 :cpp:func:`rocfft_execution_info_set_load_callback` and
 :cpp:func:`rocfft_execution_info_set_store_callback`.
 
 Device functions supplied as callbacks must load and store element
-data types that are appropriate for the transform being performed.
-
-+-------------------------+--------------------+----------------------+
-|Transform type           | Load element type  | Store element type   |
-+=========================+====================+======================+
-|Complex-to-complex,      | `_Float16_2`       | `_Float16_2`         |
-|half-precision           |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Complex-to-complex,      | `float2`           | `float2`             |
-|single-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Complex-to-complex,      | `double2`          | `double2`            |
-|double-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Real-to-complex,         | `float`            | `float2`             |
-|single-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Real-to-complex,         | `_Float16`         | `_Float16_2`         |
-|half-precision           |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Real-to-complex,         | `double`           | `double2`            |
-|double-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Complex-to-real,         | `_Float16_2`       | `_Float16`           |
-|half-precision           |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Complex-to-real,         | `float2`           | `float`              |
-|single-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
-|Complex-to-real,         | `double2`          | `double`             |
-|double-precision         |                    |                      |
-+-------------------------+--------------------+----------------------+
+data types appropriate for the transform being executed.
+
++-------------------------+----------------------+------------------------+
+|Transform type           | Load element type    | Store element type     |
++=========================+======================+========================+
+|Complex-to-complex,      | ``_Float16_2``       | ``_Float16_2``         |
+|half-precision           |                      |                        |
++-------------------------+----------------------+------------------------+
+|Complex-to-complex,      | ``float2``           | ``float2``             |
+|single-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
+|Complex-to-complex,      | ``double2``          | ``double2``            |
+|double-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
+|Real-to-complex,         | ``float``            | ``float2``             |
+|single-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
+|Real-to-complex,         | ``_Float16``         | ``_Float16_2``         |
+|half-precision           |                      |                        |
++-------------------------+----------------------+------------------------+
+|Real-to-complex,         | ``double``           | ``double2``            |
+|double-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
+|Complex-to-real,         | ``_Float16_2``       | ``_Float16``           |
+|half-precision           |                      |                        |
++-------------------------+----------------------+------------------------+
+|Complex-to-real,         | ``float2``           | ``float``              |
+|single-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
+|Complex-to-real,         | ``double2``          | ``double``             |
+|double-precision         |                      |                        |
++-------------------------+----------------------+------------------------+
 
 The callback function signatures must match the specifications
 below.
 
 .. code-block:: c
 
-  T load_callback(T* buffer, size_t offset, void* callback_data, void* shared_memory);
-  void store_callback(T* buffer, size_t offset, T element, void* callback_data, void* shared_memory);
+  Tdata load_callback(Tdata* buffer, size_t offset, void* callback_data, void* shared_memory);
+  void store_callback(Tdata* buffer, size_t offset, Tdata element, void* callback_data, void* shared_memory);
 
-The parameters for the functions are defined as:
+The parameters for the functions are as follows:
 
-* `T`: The data type of each element being loaded or stored from the
+* ``Tdata``: The data type of each element being loaded or stored from the
   input or output.
-* `buffer`: Pointer to the input (for load callbacks) or
+* ``buffer``: Pointer to the input (for load callbacks) or
   output (for store callbacks) in device memory that was passed to
   :cpp:func:`rocfft_execute`.
-* `offset`: The offset of the location being read from or written
-  to.  This counts in elements, from the `buffer` pointer.
-* `element`: For store callbacks only, the element to be stored.
-* `callback_data`: A pointer value accepted by
+* ``offset``: The offset of the location being read from or written
+  to. This counts by elements from the ``buffer`` pointer.
+* ``element``: For store callbacks only, the element to be stored.
+* ``callback_data``: A pointer value accepted by
   :cpp:func:`rocfft_execution_info_set_load_callback` and
   :cpp:func:`rocfft_execution_info_set_store_callback` which is passed
   through to the callback function.
-* `shared_memory`: A pointer to an amount of shared memory requested
-  when the callback is set.  Shared memory is not supported,
-  and this parameter is always null.
+* ``shared_memory``: A pointer to an amount of shared memory requested
+  when the callback is set. Shared memory is not supported,
+  so this parameter is always null.
 
 Callback functions are called exactly once for each element being
-loaded or stored in a transform.  Note that multiple kernels may be
+loaded or stored in a transform. Multiple kernels can be
 launched to decompose a transform, which means that separate kernels
-may call the load and store callbacks for a transform if both are
+might call the load and store callbacks for a transform if both are
 specified.
 
 Callbacks functions are only supported for transforms that do not use planar format for input or output.
-
-Runtime compilation
-===================
-
-rocFFT includes many kernels for common FFT problems.  Some plans may
-require additional kernels aside from what is built in to the
-library.  In these cases, rocFFT will compile optimized kernels for
-the plan when the plan is created.
-
-Compiled kernels are stored in memory by default and will be reused
-if they are required again for plans in the same process.
-
-If the ``ROCFFT_RTC_CACHE_PATH`` environment variable is set to a
-writable file location, rocFFT will write compiled kernels to this
-location.  rocFFT will read kernels from this location for plans in
-other processes that need runtime-compiled kernels.  rocFFT will
-create the specified file if it does not already exist.