SLEEF - DFT library reference

Tutorial

In this section, how to use the DFT library is explained with an example source code shown below. This source code is included in the distribution package under src/dft-tester directory.

// gcc tutorial.c -lsleefdft -lsleef -ltlfloat -lm -lstdc++
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <math.h>
#include <complex.h>

#include "sleef.h"
#include "sleefdft.h"

#define THRES 1e-4

typedef double complex cmpl;

cmpl omega(double n, double kn) {
  return cexp((-2 * M_PI * _Complex_I / n) * kn);
}

void forward(cmpl *ts, cmpl *fs, int len) {
  for(int k=0;k<len;k++) {
    fs[k] = 0;
    for(int n=0;n<len;n++) fs[k] += ts[n] * omega(len, n*k);
  }
}

int main(int argc, char **argv) {
  int n = 256;
  if (argc == 2) n = 1 << atoi(argv[1]);

  SleefDFT_setPlanFilePath("tut.plan", NULL, SLEEF_PLAN_AUTOMATIC);

  double *sx = (double *)Sleef_malloc(n*2 * sizeof(double));
  double *sy = (double *)Sleef_malloc(n*2 * sizeof(double));

  struct SleefDFT *p = SleefDFT_double_init1d(n, sx, sy, SLEEF_MODE_FORWARD);

  if (p == NULL) {
    printf("SleefDFT initialization failed\n");
    exit(-1);
  }

  cmpl *ts = (cmpl *)malloc(sizeof(cmpl)*n);
  cmpl *fs = (cmpl *)malloc(sizeof(cmpl)*n);

  for(int i=0;i<n;i++) {
    ts[i] =
      (2.0 * (rand() / (double)RAND_MAX) - 1) * 1.0 +
      (2.0 * (rand() / (double)RAND_MAX) - 1) * _Complex_I;

    sx[(i*2+0)] = creal(ts[i]);
    sx[(i*2+1)] = cimag(ts[i]);
  }

  forward(ts, fs, n);

  SleefDFT_double_execute(p, NULL, NULL);

  int success = 1;

  for(int i=0;i<n;i++) {
    if ((fabs(sy[(i*2+0)] - creal(fs[i])) > THRES) ||
        (fabs(sy[(i*2+1)] - cimag(fs[i])) > THRES)) {
      success = 0;
    }
  }

  printf("%s\n", success ? "OK" : "NG");

  free(fs); free(ts);
  Sleef_free(sy); Sleef_free(sx);

  SleefDFT_dispose(p);

  exit(success);
}

Fig. 4.1: Test code for DFT subroutines

You can compile the source code with the following command. Note that you need to link with libstdc++.

$ gcc tutorial.c -lsleefdft -lsleef -ltlfloat -lm -lstdc++

This program takes one integer argument n, and executes forward complex transform with size 2ⁿ. It then compares the results of a naive transform and the transform performed by the library. If the two results match, it prints OK.

For the first execution, this program takes a few seconds to finish. This is because the library constructs an execution plan by measuring computation time with many different configurations. The best plan is saved to "tut.plan", which is specified at line 30. Later executions will finish instantly as the library reads the plan from this file. Instead of specifying the file name in the program, the file can be specified by SLEEFDFTPLAN environment variable. Instead of constructing a plan, the library can estimate a modestly good configuration, if you specify SLEEF_MODE_ESTIMATE flag at line 30.

This library executes transforms using the most suitable SIMD instructions available on the computer and utilizing multi-threading. The library requires the input and output arrays to be aligned to certain boundaries so that the data in the arrays can be accessed efficiently by SIMD instructions. You can allocate arrays with Sleef_malloc to make them aligned to the boundaries, as seen in line 32 and 33. Arrays allocated with Sleef_malloc have to be freed with Sleef_free, as seen in line 70. Instead of allocating arrays with Sleef_malloc, you can allocate an aligned memory region yourself, and pass the pointer to the library.

The real and imaginary parts of the k-th number are stored in (2k)-th and (2k+1)-th elements of the input and output array, respectively. At line 56, the transform is executed by the library. You can specify the same array as the input and output.

Under src/dft-tester directory, there are other examples showing how to execute transforms in a way that you get equivalent results to other libraries. The API of this library is designed to be easy to migrate from FFTW, and you do not need to change the contents of the input or output arrays upon migration.

Function reference

Sleef_malloc - allocate aligned memory

#include <stdlib.h>
#include <sleef.h>

void * Sleef_malloc(size_t z);

Link with -lsleef -ltlfloat.

Sleef_malloc allocates z bytes of aligned memory region, and return the pointer to the allocated region. The returned pointer points the address of a memory region that can be effciently accessed by all SIMD load and store instructions available on that computer. Memory regions allocated by Sleef_malloc have to be freed with Sleef_free.

Sleef_free - free memory allocated by Sleef_malloc

#include <stdlib.h>
#include <sleef.h>

void Sleef_free(void *ptr);

Link with -lsleef -ltlfloat.

A memory region pointed by ptr that is allocated by Sleef_malloc can be freed with Sleef_free.

SleefDFT_setPlanFilePath - set the file path for storing execution plans

#include <stdint.h>
#include <sleefdft.h>

void SleefDFT_setPlanFilePath(const char *path, const char *arch, uint64_t mode);

Link with -lsleefdft -lsleef -ltlfloat.

File name for storing execution plan can be specified by this function. If NULL is specified as path, the file name is read from SLEEFDFTPLAN environment variable. A string for identifying system micro architecture can be also given. The library will try to automatically detect the micro architecture if NULL is given as arch. Management options for the plan file can be specified by the mode parameter, as shown below.

Table 4.2: Mode flags for SleefFT_setPlanFilePath


Flag	Meaning

SLEEF_PLAN_AUTOMATIC	Execution plans are automatically loaded and saved. Plans are generated if it does not exist.
SLEEF_PLAN_READONLY	Execution plans are automatically loaded, but not saved.
SLEEF_PLAN_RESET	Existing execution plans are reset and constructed from the beginning.

SleefDFT_savePlan - save plan to the specified file

#include <sleef.h>

void SleefDFT_savePlan(const char *path);

Link with -lsleefdft -lsleef -ltlfloat.

By calling this function, the generated plan is saved to the file specified by path. You can use this function to manually save the plan when SLEEF_PLAN_AUTOMATIC is not specified as the mode with SleefDFT_setPlanFilePath.

SleefDFT_double_init1d, SleefDFT_float_init1d - initialize the tables for 1D transform

#include <stdint.h>
#include <sleefdft.h>

struct SleefDFT * SleefDFT_double_init1d(uint32_t n, const double *in, double *out, uint64_t mode);
struct SleefDFT * SleefDFT_float_init1d(uint32_t n, const float *in, float *out, uint64_t mode);

Link with -lsleefdft -lsleef -ltlfloat.

These functions generate and initialize the tables that are used for 1D transform, and return the pointer. The size of transform can be specified by n. Currently, power-of-two sizes can be only specified. The list of the flags that can be passed to mode is shown below.

Table 4.3: Mode flags for SleefDFT_double_init


Flag	Meaning

SLEEF_MODE_FORWARD	Tables are initialized for forward transforms.
SLEEF_MODE_BACKWARD	Tables are initialized for backward transforms.
SLEEF_MODE_COMPLEX	Tables are initialized for complex transforms.
SLEEF_MODE_REAL	Tables are initialized for real transforms.
SLEEF_MODE_ALT	Tables are initialized for alternative real transforms.
SLEEF_MODE_ESTIMATE	Execution plans are estimated.
SLEEF_MODE_MEASURE	Execution plans are measured when they are needed.
SLEEF_MODE_VERBOSE	Messages are displayed.
SLEEF_MODE_NO_MT	Multithreading will be disabled in the computation for transforms.

These functions return a pointer to the data that is used for 1D DFT computation, or NULL if an error occurred.

SleefDFT_double_init2d, SleefDFT_float_init2d - initialize the tables for 2D transform

#include <stdint.h>
#include <sleefdft.h>

struct SleefDFT * SleefDFT_double_init2d(uint32_t n, uint32_t m, const double *in, double *out, uint64_t mode);
struct SleefDFT * SleefDFT_float_init2d(uint32_t n, uint32_t m, const float *in, float *out, uint64_t mode);

Link with -lsleefdft -lsleef -ltlfloat.

These functions generate and initilize the tables that are used for 2D transform, and return the pointer. The size of transform can be specified by n and m. Currently, power-of-two sizes can be only specified. The flags that can be passed to mode are the same as the flags listed in the section for SleefDFT_double_init1d.

These functions return a pointer to the data that is used for 2D DFT computation, or NULL if an error occurred.

SleefDFT_double_execute, SleefDFT_float_execute, SleefDFT_execute - execute a transform

#include <stdint.h>
#include <sleefdft.h>

void SleefDFT_double_execute(struct SleefDFT *ptr, const double *in, double *out);
void SleefDFT_float_execute(struct SleefDFT *ptr, const float *in, float *out);
void SleefDFT_execute(struct SleefDFT *ptr, const void *in, void *out);

Link with -lsleefdft -lsleef -ltlfloat.

By calling these functions, the transform with the plan specified by ptr is executed. If in or out is NULL, the pointer specified upon initialization is used. Otherwise, the pointers must be pointers returned from Sleef_malloc function. You can specify the same pointer to in and out.

SleefDFT_dispose - dispose the tables for transforms

#include <stdint.h>
#include <sleefdft.h>

void SleefDFT_dispose(struct SleefDFT *ptr);

Link with -lsleefdft -lsleef -ltlfloat.

This function frees a plan returned by SleefDFT_double_init1d, SleefDFT_float_init1d, SleefDFT_double_init2d, or SleefDFT_float_init2d functions.

SLEEF - DFT library reference

Table of contents

Tutorial

Function reference