include/fftw.h

   1 /*
   2  * $Id$
   3  *
   4  *       This source code is part of
   5  *
   6  *        G   R   O   M   A   C   S
   7  *
   8  * GROningen MAchine for Chemical Simulations
   9  *
  10  *               VERSION 2.0
  11  *
  12  * Copyright (c) 1991-1999
  13  * BIOSON Research Institute, Dept. of Biophysical Chemistry
  14  * University of Groningen, The Netherlands
  15  *
  16  * Please refer to:
  17  * GROMACS: A message-passing parallel molecular dynamics implementation
  18  * H.J.C. Berendsen, D. van der Spoel and R. van Drunen
  19  * Comp. Phys. Comm. 91, 43-56 (1995)
  20  *
  21  * Also check out our WWW page:
  22  * http://md.chem.rug.nl/~gmx
  23  * or e-mail to:
  24  * gromacs@chem.rug.nl
  25  *
  26  * And Hey:
  27  * Green Red Orange Magenta Azure Cyan Skyblue
  28  */
  29
  30 #ifndef _fftw_h
  31 #define _fftw_h
  32
  33 static char *SRCID_fftw_h = "$Id$";
  34
  35 #include <stdlib.h>
  36 #include <stdio.h>
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif                          /* __cplusplus */
  41
  42 #define FFTW_VERSION "2.1.2"
  43 /* Define for using single precision */
  44 /*
  45  * If you can, use configure --enable-float instead of changing this
  46  * flag directly
  47  */
  48 /* #undef FFTW_ENABLE_FLOAT */
  49
  50 /* our real numbers */
  51 #ifdef DOUBLE
  52 typedef double fftw_real;
  53 #else
  54 typedef float fftw_real;
  55 #endif
  56
  57 /*********************************************
  58  * Complex numbers and operations
  59  *********************************************/
  60 typedef struct {
  61      fftw_real re, im;
  62 } fftw_complex;
  63
  64 #define c_re(c)  ((c).re)
  65 #define c_im(c)  ((c).im)
  66
  67 typedef enum {
  68      FFTW_FORWARD = -1, FFTW_BACKWARD = 1
  69 } fftw_direction;
  70
  71 /* backward compatibility with FFTW-1.3 */
  72 typedef fftw_complex FFTW_COMPLEX;
  73 typedef fftw_real FFTW_REAL;
  74
  75 #ifndef FFTW_1_0_COMPATIBILITY
  76 #define FFTW_1_0_COMPATIBILITY 0
  77 #endif
  78
  79 #if FFTW_1_0_COMPATIBILITY
  80 /* backward compatibility with FFTW-1.0 */
  81 #define REAL fftw_real
  82 #define COMPLEX fftw_complex
  83 #endif
  84
  85 /*********************************************
  86  * Success or failure status
  87  *********************************************/
  88
  89 typedef enum {
  90      FFTW_SUCCESS = 0, FFTW_FAILURE = -1
  91 } fftw_status;
  92
  93 /*********************************************
  94  *              Codelets
  95  *********************************************/
  96 typedef void (fftw_notw_codelet)
  97      (const fftw_complex *, fftw_complex *, int, int);
  98 typedef void (fftw_twiddle_codelet)
  99      (fftw_complex *, const fftw_complex *, int,
 100       int, int);
 101 typedef void (fftw_generic_codelet)
 102      (fftw_complex *, const fftw_complex *, int,
 103       int, int, int);
 104 typedef void (fftw_real2hc_codelet)
 105      (const fftw_real *, fftw_real *, fftw_real *,
 106       int, int, int);
 107 typedef void (fftw_hc2real_codelet)
 108      (const fftw_real *, const fftw_real *,
 109       fftw_real *, int, int, int);
 110 typedef void (fftw_hc2hc_codelet)
 111      (fftw_real *, const fftw_complex *,
 112       int, int, int);
 113 typedef void (fftw_rgeneric_codelet)
 114      (fftw_real *, const fftw_complex *, int,
 115       int, int, int);
 116
 117 /*********************************************
 118  *     Configurations
 119  *********************************************/
 120 /*
 121  * A configuration is a database of all known codelets
 122  */
 123
 124 enum fftw_node_type {
 125      FFTW_NOTW, FFTW_TWIDDLE, FFTW_GENERIC, FFTW_RADER,
 126      FFTW_REAL2HC, FFTW_HC2REAL, FFTW_HC2HC, FFTW_RGENERIC
 127 };
 128
 129 /* description of a codelet */
 130 typedef struct {
 131      const char *name;          /* name of the codelet */
 132      void (*codelet) ();        /* pointer to the codelet itself */
 133      int size;                  /* size of the codelet */
 134      fftw_direction dir;        /* direction */
 135      enum fftw_node_type type;  /* TWIDDLE or NO_TWIDDLE */
 136      int signature;             /* unique id */
 137      int ntwiddle;              /* number of twiddle factors */
 138      const int *twiddle_order;  /*
 139                                  * array that determines the order
 140                                  * in which the codelet expects
 141                                  * the twiddle factors
 142                                  */
 143 } fftw_codelet_desc;
 144
 145 /* On Win32, you need to do funny things to access global variables
 146    in shared libraries.  Thanks to Andrew Sterian for this hack. */
 147 #if defined(__WIN32__) || defined(WIN32) || defined(_WINDOWS)
 148 #  if defined(BUILD_FFTW_DLL)
 149 #    define DL_IMPORT(type) __declspec(dllexport) type
 150 #  elif defined(USE_FFTW_DLL)
 151 #    define DL_IMPORT(type) __declspec(dllimport) type
 152 #  else
 153 #    define DL_IMPORT(type) type
 154 #  endif
 155 #else
 156 #  define DL_IMPORT(type) type
 157 #endif
 158
 159 extern DL_IMPORT(const char *) fftw_version;
 160
 161 /*****************************
 162  *        Plans
 163  *****************************/
 164 /*
 165  * A plan is a sequence of reductions to compute a FFT of
 166  * a given size.  At each step, the FFT algorithm can:
 167  *
 168  * 1) apply a notw codelet, or
 169  * 2) recurse and apply a twiddle codelet, or
 170  * 3) apply the generic codelet.
 171  */
 172
 173 /* structure that contains twiddle factors */
 174 typedef struct fftw_twiddle_struct {
 175      int n;
 176      const fftw_codelet_desc *cdesc;
 177      fftw_complex *twarray;
 178      struct fftw_twiddle_struct *next;
 179      int refcnt;
 180 } fftw_twiddle;
 181
 182 typedef struct fftw_rader_data_struct {
 183      struct fftw_plan_struct *plan;
 184      fftw_complex *omega;
 185      int g, ginv;
 186      int p, flags, refcount;
 187      struct fftw_rader_data_struct *next;
 188      fftw_codelet_desc *cdesc;
 189 } fftw_rader_data;
 190
 191 typedef void (fftw_rader_codelet)
 192      (fftw_complex *, const fftw_complex *, int,
 193       int, int, fftw_rader_data *);
 194
 195 /* structure that holds all the data needed for a given step */
 196 typedef struct fftw_plan_node_struct {
 197      enum fftw_node_type type;
 198
 199      union {
 200           /* nodes of type FFTW_NOTW */
 201           struct {
 202                int size;
 203                fftw_notw_codelet *codelet;
 204                const fftw_codelet_desc *codelet_desc;
 205           } notw;
 206
 207           /* nodes of type FFTW_TWIDDLE */
 208           struct {
 209                int size;
 210                fftw_twiddle_codelet *codelet;
 211                fftw_twiddle *tw;
 212                struct fftw_plan_node_struct *recurse;
 213                const fftw_codelet_desc *codelet_desc;
 214           } twiddle;
 215
 216           /* nodes of type FFTW_GENERIC */
 217           struct {
 218                int size;
 219                fftw_generic_codelet *codelet;
 220                fftw_twiddle *tw;
 221                struct fftw_plan_node_struct *recurse;
 222           } generic;
 223
 224           /* nodes of type FFTW_RADER */
 225           struct {
 226                int size;
 227                fftw_rader_codelet *codelet;
 228                fftw_rader_data *rader_data;
 229                fftw_twiddle *tw;
 230                struct fftw_plan_node_struct *recurse;
 231           } rader;
 232
 233           /* nodes of type FFTW_REAL2HC */
 234           struct {
 235                int size;
 236                fftw_real2hc_codelet *codelet;
 237                const fftw_codelet_desc *codelet_desc;
 238           } real2hc;
 239
 240           /* nodes of type FFTW_HC2REAL */
 241           struct {
 242                int size;
 243                fftw_hc2real_codelet *codelet;
 244                const fftw_codelet_desc *codelet_desc;
 245           } hc2real;
 246
 247           /* nodes of type FFTW_HC2HC */
 248           struct {
 249                int size;
 250                fftw_direction dir;
 251                fftw_hc2hc_codelet *codelet;
 252                fftw_twiddle *tw;
 253                struct fftw_plan_node_struct *recurse;
 254                const fftw_codelet_desc *codelet_desc;
 255           } hc2hc;
 256
 257           /* nodes of type FFTW_RGENERIC */
 258           struct {
 259                int size;
 260                fftw_direction dir;
 261                fftw_rgeneric_codelet *codelet;
 262                fftw_twiddle *tw;
 263                struct fftw_plan_node_struct *recurse;
 264           } rgeneric;
 265      } nodeu;
 266
 267      int refcnt;
 268 } fftw_plan_node;
 269
 270 struct fftw_plan_struct {
 271      int n;
 272      int refcnt;
 273      fftw_direction dir;
 274      int flags;
 275      int wisdom_signature;
 276      enum fftw_node_type wisdom_type;
 277      struct fftw_plan_struct *next;
 278      fftw_plan_node *root;
 279      double cost;
 280 };
 281
 282 /* a plan is just an array of instructions */
 283 typedef struct fftw_plan_struct *fftw_plan;
 284
 285 /* flags for the planner */
 286 #define  FFTW_ESTIMATE (0)
 287 #define  FFTW_MEASURE  (1)
 288
 289 #define FFTW_OUT_OF_PLACE (0)
 290 #define FFTW_IN_PLACE (8)
 291 #define FFTW_USE_WISDOM (16)
 292
 293 #define FFTW_THREADSAFE (128)  /* guarantee plan is read-only so that the
 294                                   same plan can be used in parallel by
 295                                   multiple threads */
 296
 297 #define FFTWND_FORCE_BUFFERED (256)     /* internal, undocumented flag */
 298
 299 extern fftw_plan fftw_create_plan_specific(int n, fftw_direction dir,
 300                                            int flags,
 301                                            fftw_complex *in, int istride,
 302                                          fftw_complex *out, int ostride);
 303 #define FFTW_HAS_PLAN_SPECIFIC
 304 extern fftw_plan fftw_create_plan(int n, fftw_direction dir, int flags);
 305 extern void fftw_print_plan(fftw_plan plan);
 306 extern void fftw_destroy_plan(fftw_plan plan);
 307 extern void fftw(fftw_plan plan, int howmany, fftw_complex *in, int istride,
 308                  int idist, fftw_complex *out, int ostride, int odist);
 309 extern void fftw_one(fftw_plan plan, fftw_complex *in, fftw_complex *out);
 310 extern void fftw_die(const char *s);
 311 extern void *fftw_malloc(size_t n);
 312 extern void fftw_free(void *p);
 313 extern void fftw_check_memory_leaks(void);
 314 extern void fftw_print_max_memory_usage(void);
 315
 316 typedef void *(*fftw_malloc_type_function) (size_t n);
 317 typedef void  (*fftw_free_type_function) (void *p);
 318 typedef void  (*fftw_die_type_function) (const char *errString);
 319 extern DL_IMPORT(fftw_malloc_type_function) fftw_malloc_hook;
 320 extern DL_IMPORT(fftw_free_type_function) fftw_free_hook;
 321 extern DL_IMPORT(fftw_die_type_function) fftw_die_hook;
 322
 323 extern size_t fftw_sizeof_fftw_real(void);
 324
 325 /* Wisdom: */
 326 /*
 327  * define this symbol so that users know we are using a version of FFTW
 328  * with wisdom
 329  */
 330 #define FFTW_HAS_WISDOM
 331 extern void fftw_forget_wisdom(void);
 332 extern void fftw_export_wisdom(void (*emitter) (char c, void *), void *data);
 333 extern fftw_status fftw_import_wisdom(int (*g) (void *), void *data);
 334 extern void fftw_export_wisdom_to_file(FILE *output_file);
 335 extern fftw_status fftw_import_wisdom_from_file(FILE *input_file);
 336 extern char *fftw_export_wisdom_to_string(void);
 337 extern fftw_status fftw_import_wisdom_from_string(const char *input_string);
 338
 339 /*
 340  * define symbol so we know this function is available (it is not in
 341  * older FFTWs)
 342  */
 343 #define FFTW_HAS_FPRINT_PLAN
 344 extern void fftw_fprint_plan(FILE *f, fftw_plan plan);
 345
 346 /*****************************
 347  *    N-dimensional code
 348  *****************************/
 349 typedef struct {
 350      int is_in_place;           /* 1 if for in-place FFTs, 0 otherwise */
 351
 352      int rank;                  /*
 353                                  * the rank (number of dimensions) of the
 354                                  * array to be FFTed
 355                                  */
 356      int *n;                    /*
 357                                  * the dimensions of the array to the
 358                                  * FFTed
 359                                  */
 360      fftw_direction dir;
 361
 362      int *n_before;             /*
 363                                  * n_before[i] = product of n[j] for j < i
 364                                  */
 365      int *n_after;              /* n_after[i] = product of n[j] for j > i */
 366
 367      fftw_plan *plans;          /* 1d fftw plans for each dimension */
 368
 369      int nbuffers, nwork;
 370      fftw_complex *work;        /*
 371                                  * work array big enough to hold
 372                                  * nbuffers+1 of the largest dimension
 373                                  * (has nwork elements)
 374                                  */
 375 } fftwnd_data;
 376
 377 typedef fftwnd_data *fftwnd_plan;
 378
 379 /* Initializing the FFTWND plan: */
 380 extern fftwnd_plan fftw2d_create_plan(int nx, int ny, fftw_direction dir,
 381                                       int flags);
 382 extern fftwnd_plan fftw3d_create_plan(int nx, int ny, int nz,
 383                                       fftw_direction dir, int flags);
 384 extern fftwnd_plan fftwnd_create_plan(int rank, const int *n,
 385                                       fftw_direction dir,
 386                                       int flags);
 387
 388 extern fftwnd_plan fftw2d_create_plan_specific(int nx, int ny,
 389                                                fftw_direction dir,
 390                                                int flags,
 391                                            fftw_complex *in, int istride,
 392                                          fftw_complex *out, int ostride);
 393 extern fftwnd_plan fftw3d_create_plan_specific(int nx, int ny, int nz,
 394                                            fftw_direction dir, int flags,
 395                                            fftw_complex *in, int istride,
 396                                          fftw_complex *out, int ostride);
 397 extern fftwnd_plan fftwnd_create_plan_specific(int rank, const int *n,
 398                                                fftw_direction dir,
 399                                                int flags,
 400                                            fftw_complex *in, int istride,
 401                                          fftw_complex *out, int ostride);
 402
 403 /* Freeing the FFTWND plan: */
 404 extern void fftwnd_destroy_plan(fftwnd_plan plan);
 405
 406 /* Printing the plan: */
 407 extern void fftwnd_fprint_plan(FILE *f, fftwnd_plan p);
 408 extern void fftwnd_print_plan(fftwnd_plan p);
 409 #define FFTWND_HAS_PRINT_PLAN
 410
 411 /* Computing the N-Dimensional FFT */
 412 extern void fftwnd(fftwnd_plan plan, int howmany,
 413                    fftw_complex *in, int istride, int idist,
 414                    fftw_complex *out, int ostride, int odist);
 415 extern void fftwnd_one(fftwnd_plan p, fftw_complex *in, fftw_complex *out);
 416
 417 #ifdef __cplusplus
 418 }                               /* extern "C" */
 419
 420 #endif                          /* __cplusplus */
 421 #endif                          /* FFTW_H */