Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 7/13/2023
Public

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

Document Table of Contents

DftiComputeForward

Computes the forward FFT.

Syntax

status = DftiComputeForward( desc_handle, x_inout )

status = DftiComputeForward( desc_handle, x_in, y_out )

status = DftiComputeForward( desc_handle, xre_inout, xim_inout )

status = DftiComputeForward( desc_handle, xre_in, xim_in, yre_out, yim_out )

Input Parameters

Name

Type

Description

desc_handle

DFTI_DESCRIPTOR

FFT descriptor.

x_inout, x_in

Array REAL(KIND=WP) or COMPLEX(KIND=WP), DIMENSION(*), where type and working precision WP must be consistent with the forward domain and precision specified in the descriptor.

Data to be transformed in case of a real forward domain or, in the case of a complex forward domain in association with FTI_COMPLEX_COMPLEX, set for DFTI_COMPLEX_STORAGE.

xre_inout, xim_inout, xre_in, xim_in

Array REAL(KIND=WP), DIMENSION(*), where type and working precision WP must be consistent with the forward domain and precision specified in the descriptor.

Real and imaginary parts of the data to be transformed in the case of a complex forward domain.

The suffix in parameter names corresponds to the value of the configuration parameter DFTI_PLACEMENT as follows:

  • _inout to DFTI_INPLACE
  • _in to DFTI_NOT_INPLACE

Output Parameters

Name

Type

Description

y_out

Array REAL(KIND=WP) or COMPLEX(KIND=WP), DIMENSION(*), where type and working precision WP must be consistent with the forward domain and precision specified in the descriptor.

The transformed data in case of a real backward domain or, in the case of a complex forward domain in association with DFTI_COMPLEX_COMPLEX, set for DFTI_COMPLEX_STORAGE.

xre_inout, xim_inout, yre_out, yim_out

Array REAL(KIND=WP), DIMENSION(*), where type and working precision WP must be consistent with the forward domain and precision specified in the descriptor.

Real and imaginary parts of the transformed data in the case of a complex forward domain in association with DFTI_REAL_REAL set for DFTI_COMPLEX_STORAGE.

status

INTEGER

Function completion status.

The suffix in parameter names corresponds to the value of the configuration parameter DFTI_PLACEMENT as follows:

  • _inout to DFTI_INPLACE
  • _out to DFTI_NOT_INPLACE

Include Files

  • mkl_dfti.f90

Description

The DftiComputeForward function accepts the descriptor handle parameter and one or more data parameters. Given a successfully configured and committed descriptor, this function computes the forward FFT, that is, the transform with the minus sign in the exponent, δ = -1.

The DFTI_COMPLEX_STORAGE, DFTI_REAL_STORAGE, and DFTI_CONJUGATE_EVEN_STORAGE configuration parameters define the layout of the input and output data and must be properly set in a call to the DftiSetValue function. The forward domain and the precision of the transform are determined by the configuration settings DFTI_FORWARD_DOMAIN and DFTI_PRECISION, which are during construction of the descriptor.

The FFT descriptor must be properly configured prior to the function call. Function calls needed to configure an FFT descriptor for a particular call to an FFT computation function are summarized in Configuring and Computing an FFT in Fortran.

The number and types of the data parameters that the function requires may vary depending on the configuration of the descriptor. This variation is accommodated by the generic interface. The generic Fortran interface to the computation functions is based on a set of specific functions. These functions can check for inconsistency between the required and actual number of parameters. However, the specific functions disregard the type of the actual parameters and instead use the interpretation defined in the descriptor by configuration parameters DFTI_FORWARD_DOMAIN, DFTI_INPUT_STRIDES, DFTI_INPUT_DISTANCE, and so on.

The function returns zero when it completes successfully. See Status Checking Functions for more information on the returned status.

Interface

 
! Note that the body provided below only illustrates the list of different
! parameters and the types of dummy parameters. You can rely only on the function
! name following keyword INTERFACE. For the precise definition of the
! interface, see the include/mkl_dfti.f90 file in the Intel MKL directory.
INTERFACE DftiComputeForward
 
  FUNCTION some_actual_function_1(desc,sSrcDst)
    INTEGER some_actual_function_1
    REAL(4), INTENT(INOUT), DIMENSION(*) :: sSrcDst
    ...
  END FUNCTION some_actual_function_1
 
  FUNCTION some_actual_function_2(desc,cSrcDst)
    INTEGER some_actual_function_2
    COMPLEX(8), INTENT(INOUT), DIMENSION(*) :: cSrcDst
    ...
  END FUNCTION some_actual_function_2
 
  FUNCTION some_actual_function_3(desc,sSrcDstRe,sSrcDstIm)
    INTEGER some_actual_function_3
    REAL(4), INTENT(INOUT), DIMENSION(*) :: sSrcDstRe
    REAL(4), INTENT(INOUT), DIMENSION(*) :: sSrcDstIm
    ...
  END FUNCTION some_actual_function_3
  ...
END INTERFACE DftiComputeForward
 

The Fortran interface requires that the data parameters have the type of assumed-size rank-1 array, even for multidimensional transforms. The implementations of the FFT interface require the data stored linearly in memory with a regular stride pattern capable of describing multidimensional array layout (see also [3] and the more detailed discussion in DFTI_INPUT_STRIDES, DFTI_OUTPUT_STRIDES), and the function requires that the data parameters refer to the first element of the data. Consequently, the data arrays should be specified with the DIMENSION(*) attribute and the storage associated with the actual multidimensional arrays via the EQUIVALENCE statement.