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

?_commit_trig_transform

Checks consistency and correctness of user's data as well as initializes certain data structures required to perform the Trigonometric Transform.

Syntax

void d_commit_trig_transform(double f[], DFTI_DESCRIPTOR_HANDLE *handle, MKL_INT ipar[], double dpar[], MKL_INT *stat);

void s_commit_trig_transform(float f[], DFTI_DESCRIPTOR_HANDLE *handle, MKL_INT ipar[], float spar[], MKL_INT *stat);

Include Files

  • mkl_trig_transforms.f90

Input Parameters

f

double for d_commit_trig_transform,

float for s_commit_trig_transform,

array of size n for staggered2 transforms and of size n+1 for all other transforms, where n is the size of the problem. Contains data vector to be transformed. Note that the following values should be 0.0 up to rounding errors:

  • f[0] and f[n] for sine transforms
  • f[n] for staggered cosine transforms
  • f[0] for staggered sine transforms.

Otherwise, the routine will produce a warning, and the result of the computations for sine transforms may be wrong. These restrictions meet the requirements of the Intel® oneAPI Math Kernel Library (oneMKL) Poisson Solver, which the TT interface is primarily designed for (for details, seeFast Poisson Solver Routines).

ipar

MKL_INT array of size 128. Contains integer data needed for Trigonometric Transform computations.

dpar

double array of size 5n/2+2. Contains double-precision data needed for Trigonometric Transform computations. The routine initializes most elements of this array.

spar

float array of size 5n/2+2. Contains single-precision data needed for Trigonometric Transform computations. The routine initializes most elements of this array.

Output Parameters

handle

DFTI_DESCRIPTOR_HANDLE*. The data structure used by Intel® oneAPI Math Kernel Library (oneMKL) FFT interface (for details, refer toFFT Functions).

ipar

Contains integer data needed for Trigonometric Transform computations. On output, ipar[6] is updated with the stat value.

dpar

Contains double-precision data needed for Trigonometric Transform computations. On output, the entire array is initialized.

spar

Contains single-precision data needed for Trigonometric Transform computations. On output, the entire array is initialized.

stat

MKL_INT*. Contains the routine completion status, which is also written to ipar[6].

Description

The routine ?_commit_trig_transform checks consistency and correctness of the parameters to be passed to the transform routines ?_forward_trig_transform and/or ?_backward_trig_transform. The routine also initializes the following data structures: handle, dpar in case of d_commit_trig_transform, and spar in case of s_commit_trig_transform. The ?_commit_trig_transform routine initializes only those elements of dpar or spar that depend upon the type of transform, defined in the ?_init_trig_transform routine and passed to ?_commit_trig_transform with the ipar array. The size of the problem n, which determines sizes of the array parameters, is also passed to the routine with the ipar array and defined in the previously called ?_init_trig_transform routine. For a detailed description of arrays ipar, dpar and spar, refer to Common Parameters. The routine performs only a basic check for correctness and consistency of the parameters. If you are going to modify parameters of TT routines, see Caveat on Parameter Modifications. Unlike ?_init_trig_transform, you must call the ?_commit_trig_transform routine in your code.

Return Values

stat= 11

The routine produced some warnings and made some changes in the parameters to achieve their correctness and/or consistency. You may proceed with computations by assigning ipar[6]=0 if you are sure that the parameters are correct.

stat= 10

The routine made some changes in the parameters to achieve their correctness and/or consistency. You may proceed with computations by assigning ipar[6]=0 if you are sure that the parameters are correct.

stat= 1

The routine produced some warnings. You may proceed with computations by assigning ipar[6]=0 if you are sure that the parameters are correct.

stat= 0

The routine completed the task normally.

stat= -100

The routine stopped for any of the following reasons:

  • An error in the user's data was encountered.
  • Data in ipar, dpar or spar parameters became incorrect and/or inconsistent as a result of modifications.

stat= -1000

The routine stopped because of an FFT interface error.

stat= -10000

The routine stopped because the initialization failed to complete or the parameter ipar[0] was altered by mistake.

NOTE:

Although positive values of stat usually indicate minor problems with the input data and Trigonometric Transform computations can be continued, you are highly recommended to investigate the problem first and achieve stat=0.