Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

DFTI_INPUT_DISTANCE, DFTI_OUTPUT_DISTANCE

The FFT interface in Intel® oneAPI Math Kernel Library (oneMKL) enables computation of multiple transforms. To compute multiple transforms, you need to specify the data distribution of the multiple sets of data. The distance between the first data elements of consecutive data sets, DFTI_INPUT_DISTANCE for input data or DFTI_OUTPUT_DISTANCE for output data, specifies the distribution. The configuration setting is a value of INTEGER data type.

The default value for both configuration settings is one. You must set this parameter explicitly if the number of transforms is greater than one (see DFTI_NUMBER_OF_TRANSFORMS).

The distance is counted in elements of the data type defined by the descriptor configuration (rather than by the type of the variable passed to the computation functions). Specifically, the DFTI_FORWARD_DOMAIN, DFTI_COMPLEX_STORAGE, and DFTI_CONJUGATE_EVEN_STORAGE configuration parameters define the type of the elements as shown in Table "Assumed Element Types of the Input/Output Data".

NOTE:

The configuration parameters DFTI_INPUT_DISTANCE and DFTI_OUTPUT_DISTANCE define the distance within input and output data, and not within the forward-domain and backward-domain data. If the distances in the forward and backward domains differ, set DFTI_INPUT_DISTANCE and DFTI_OUTPUT_DISTANCE explicitly and then commit the descriptor before calling computation functions.

For in-place transforms (DFTI_PLACEMENT=DFTI_INPLACE), the configuration set by DFTI_OUTPUT_DISTANCE is ignored when the element types in the forward and backward domains are the same. If they are different, set DFTI_OUTPUT_DISTANCE explicitly (even though the transform is in-place). Ensure a consistent configuration for in-place transforms, that is, the locations of the data sets on input and output must coincide.

This example illustrates setting of the DFTI_INPUT_DISTANCE configuration parameter:

INTEGER :: dims(d) = [n1, n2, …, nd]
INTEGER :: distance = n1*n2*…*nd
status = DftiCreateDescriptor( hand, precision, DFTI_COMPLEX, d, dims)
status = DftiSetValue( hand, DFTI_NUMBER_OF_TRANSFORMS, howmany )
status = DftiSetValue( hand, DFTI_INPUT_DISTANCE,  distance );

To better understand configuration of the distances, see these code examples in your Intel® oneAPI Math Kernel Library (oneMKL) directory:

./examples/dftf/source/config_number_of_transforms.f90