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_STRIDES, DFTI_OUTPUT_STRIDES

The FFT interface provides configuration parameters that define the layout of multidimensional data in the computer memory. For d-dimensional data set X defined by dimensions N1 x N2 x ... x Nd, the layout describes where a particular element X(k1, k2, ..., kd) of the data set is located. The memory address of the element X(k1, k2 , ..., kd) is expressed by the formula,

address of X(k1, k2, ..., kd) = the address stored in the pointer supplied to the compute function + (s0 + k1*s1 + k2*s2 + ...+ kd*sd) * u,

Where u is the number of bytes per element of the desired precision for the assumed data type in the corresponding domain (see Table "Assumed Element Types of the Input/Output Data" below), where s0 is the displacement, and s1, ..., sd are generalized strides. The configuration parameters DFTI_INPUT_STRIDES and DFTI_OUTPUT_STRIDES enable you to get and set these values. The configuration value is an array of values (s0, s1, ..., sd) of INTEGER data type.

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":

Assumed Element Types of the Input/Output Data

Descriptor Configuration

Element Type in the Forward Domain

Element Type in the Backward Domain

DFTI_FORWARD_DOMAIN=DFTI_COMPLEX
DFTI_COMPLEX_STORAGE=DFTI_COMPLEX_COMPLEX

Complex

Complex

DFTI_FORWARD_DOMAIN=DFTI_COMPLEX
DFTI_COMPLEX_STORAGE=DFTI_REAL_REAL

Real

Real

DFTI_FORWARD_DOMAIN=DFTI_REAL
DFTI_CONJUGATE_EVEN_STORAGE=DFTI_COMPLEX_REAL

Real

Real

DFTI_FORWARD_DOMAIN=DFTI_REAL
DFTI_CONJUGATE_EVEN_STORAGE=DFTI_COMPLEX_COMPLEX

Real

Complex

The DFTI_INPUT_STRIDES configuration parameter defines the layout of the input data, while the element type is defined by the forward domain for the DftiComputeForward function and by the backward domain for the DftiComputeBackward function. The DFTI_OUTPUT_STRIDES configuration parameter defines the layout of the output data, while the element type is defined by the backward domain for the DftiComputeForward function and by the forward domain for DftiComputeBackward function.

NOTE:

The DFTI_INPUT_STRIDES and DFTI_OUTPUT_STRIDES configuration parameters define the layout of input and output data, and not the forward-domain and backward-domain data. If the data layouts in forward domain and backward domain differ, set DFTI_INPUT_STRIDES and DFTI_OUTPUT_STRIDES explicitly and then commit the descriptor before calling computation functions.

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

The FFT interface supports both positive and negative stride values. If you use negative strides, set the displacement of the data as follows:

The default setting of strides in a general multi-dimensional case assumes that the array that contains the data has no padding. The order of the strides depends on the programming language. For example:

INTEGER :: dims(d) = [n1, n2, …, nd]
status = DftiCreateDescriptor( hand, precision, domain, d, dims)
! The above call assumes data declaration:  type X(n1,n2,…,nd-1) 
! Default strides are [ 0, 1, n1, n1*n2, …, n1*n2*…*nd-1]

Note that in case of a real FFT (DFTI_FORWARD_DOMAIN=DFTI_REAL), where different data layouts in the backward domain are available (see DFTI_PACKED_FORMAT), the default value of the strides is not intuitive for the recommended CCE format (configuration setting DFTI_CONJUGATE_EVEN_STORAGE=DFTI_COMPLEX_COMPLEX). In case of an in-place real transform with the CCE format, set the strides explicitly, as follows:

INTEGER :: dims(d) = [n1, n2, …, nd]
INTEGER :: rstrides(1+d) = [0, 1, 2*(n1/2+1), 2*(n1/2+1)*n2, …, 2*nd-1*…*n2*(n1/2+1)]
INTEGER :: cstrides(1+d) = [0, 1, (n1/2+1), (n1/2+1)*n2, …, nd-1*…*n2*(n1/2+1) ]
status = DftiCreateDescriptor( hand, precision, domain, d, dims)
status = DftiSetValue( hand, DFTI_CONJUGATE_EVEN_STORAGE, DFTI_COMPLEX_COMPLEX)
! Set the strides appropriately for forward/backward transform
Limitation Note:
Transforms with the number of points N of a non-unit stride dimension exceeding 2^(27−p) −1 for N a power-of-two, or 2^(23−p) − 1 for N not a power-of-two, are currently not supported, where p=0 for single precision and p=1 for double precision. If a descriptor is created (for example, using DftiCreateDescriptor) and set (for example, using DftiSetValue) to do such a transform, a DFTI_1D_MEMORY_EXCEEDS_INT32 error is returned at commit time (for example, by DftiCommitDescriptor).

To better understand configuration of strides, you can also refer to these examples in your Intel® oneAPI Math Kernel Library (oneMKL) directory:

./examples/dftf/source/basic_sp_complex_dft_2d.f90

./examples/dftf/source/basic_sp_complex_dft_3d.f90

./examples/dftf/source/basic_dp_complex_dft_2d.f90

./examples/dftf/source/basic_dp_complex_dft_3d.f90

./examples/dftf/source/basic_sp_real_dft_2d.f90

./examples/dftf/source/basic_sp_real_dft_3d.f90

./examples/dftf/source/basic_dp_real_dft_2d.f90

./examples/dftf/source/basic_dp_real_dft_3d.f90