pod/FFT.pod

   1 %perlcode %{
   2 @EXPORT_complex = qw/
   3                gsl_fft_complex_radix2_forward
   4                gsl_fft_complex_radix2_backward
   5                gsl_fft_complex_radix2_inverse
   6                gsl_fft_complex_radix2_transform
   7                gsl_fft_complex_radix2_dif_forward
   8                gsl_fft_complex_radix2_dif_backward
   9                gsl_fft_complex_radix2_dif_inverse
  10                gsl_fft_complex_radix2_dif_transform
  11                gsl_fft_complex_wavetable_alloc
  12                gsl_fft_complex_wavetable_free
  13                gsl_fft_complex_workspace_alloc
  14                gsl_fft_complex_workspace_free
  15                gsl_fft_complex_memcpy
  16                gsl_fft_complex_forward
  17                gsl_fft_complex_backward
  18                gsl_fft_complex_inverse
  19                gsl_fft_complex_transform
  20                /;
  21 @EXPORT_halfcomplex = qw/
  22                gsl_fft_halfcomplex_radix2_backward
  23                gsl_fft_halfcomplex_radix2_inverse
  24                gsl_fft_halfcomplex_radix2_transform
  25                gsl_fft_halfcomplex_wavetable_alloc
  26                gsl_fft_halfcomplex_wavetable_free
  27                gsl_fft_halfcomplex_backward
  28                gsl_fft_halfcomplex_inverse
  29                gsl_fft_halfcomplex_transform
  30                gsl_fft_halfcomplex_unpack
  31                gsl_fft_halfcomplex_radix2_unpack
  32                /;
  33 @EXPORT_real = qw/
  34                gsl_fft_real_radix2_transform
  35                gsl_fft_real_wavetable_alloc
  36                gsl_fft_real_wavetable_free
  37                gsl_fft_real_workspace_alloc
  38                gsl_fft_real_workspace_free
  39                gsl_fft_real_transform
  40                gsl_fft_real_unpack
  41              /;
  42 @EXPORT_vars = qw/
  43                 $gsl_fft_forward
  44                 $gsl_fft_backward
  45                 /;
  46 @EXPORT_OK =   (
  47                 @EXPORT_real,
  48                 @EXPORT_complex,
  49                 @EXPORT_halfcomplex,
  50                 @EXPORT_vars,
  51                 );
  52 %EXPORT_TAGS = (
  53                 all         => \@EXPORT_OK,
  54                 real        => \@EXPORT_real,
  55                 complex     => \@EXPORT_complex,
  56                 halfcomplex => \@EXPORT_halfcomplex,
  57                 vars        => \@EXPORT_vars,
  58                );
  59 __END__
  60
  61 =head1 NAME
  62
  63 Math::GSL::FFT - Fast Fourier Transforms (FFT)
  64
  65 =head1 SYNOPSIS
  66
  67     use Math::GSL::FFT qw /:all/;
  68     # alternating elements are real/imaginary part, hence 256 element array
  69     my $data = [ (1) x 10, (0) x 236, (1) x 10 ];
  70
  71     # use every element of the array
  72     my $stride = 1;
  73
  74     # But it contains 128 complex numbers
  75     my ($status, $fft) = gsl_fft_complex_radix2_forward ($data, $stride, 128);
  76
  77 =head1 DESCRIPTION
  78
  79 This module and this documentation is still in a very early state. Danger Will Robinson!
  80 An OO interface will evolve soon.
  81
  82 =over
  83
  84 =item * C<gsl_fft_complex_radix2_forward($data, $stride, $n) >
  85
  86 This function computes the forward FFTs of length $n with stride $stride, on
  87 the array reference $data using an in-place radix-2 decimation-in-time
  88 algorithm. The length of the transform $n is restricted to powers of two. For
  89 the transform version of the function the sign argument can be either forward
  90 (-1) or backward (+1). The functions return a value of $GSL_SUCCESS if no
  91 errors were detected, or $GSL_EDOM if the length of the data $n is not a power
  92 of two. The complex functions of the FFT module are not yet fully implemented.
  93
  94 =item * C<gsl_fft_complex_radix2_backward >
  95
  96 =item * C<gsl_fft_complex_radix2_inverse >
  97
  98 =item * C<gsl_fft_complex_radix2_transform >
  99
 100 =item * C<gsl_fft_complex_radix2_dif_forward >
 101
 102 =item * C<gsl_fft_complex_radix2_dif_backward >
 103
 104 =item * C<gsl_fft_complex_radix2_dif_inverse >
 105
 106 =item * C<gsl_fft_complex_radix2_dif_transform >
 107
 108 =item * C<gsl_fft_complex_wavetable_alloc($n)>
 109
 110 This function prepares a trigonometric lookup table for a complex FFT of length
 111 $n. The function returns a pointer to the newly allocated
 112 gsl_fft_complex_wavetable if no errors were detected, and a null pointer in the
 113 case of error. The length $n is factorized into a product of subtransforms, and
 114 the factors and their trigonometric coefficients are stored in the wavetable.
 115 The trigonometric coefficients are computed using direct calls to sin and cos,
 116 for accuracy. Recursion relations could be used to compute the lookup table
 117 faster, but if an application performs many FFTs of the same length then this
 118 computation is a one-off overhead which does not affect the final throughput.
 119 The wavetable structure can be used repeatedly for any transform of the same
 120 length. The table is not modified by calls to any of the other FFT functions.
 121 The same wavetable can be used for both forward and backward (or inverse)
 122 transforms of a given length.
 123
 124 =item * C<gsl_fft_complex_wavetable_free($wavetable)>
 125
 126 This function frees the memory associated with the wavetable $wavetable. The
 127 wavetable can be freed if no further FFTs of the same length will be needed.
 128
 129 =item * C<gsl_fft_complex_workspace_alloc($n)>
 130
 131 This function allocates a workspace for a complex transform of length $n.
 132
 133 =item * C<gsl_fft_complex_workspace_free($workspace) >
 134
 135 This function frees the memory associated with the workspace $workspace. The
 136 workspace can be freed if no further FFTs of the same length will be needed.
 137
 138 =item * C<gsl_fft_complex_memcpy >
 139
 140 =item * C<gsl_fft_complex_forward >
 141
 142 =item * C<gsl_fft_complex_backward >
 143
 144 =item * C<gsl_fft_complex_inverse >
 145
 146 =item * C<gsl_fft_complex_transform >
 147
 148 =item * C<gsl_fft_halfcomplex_radix2_backward($data, $stride, $n)>
 149
 150 This function computes the backwards in-place radix-2 FFT of length $n and
 151 stride $stride on the half-complex sequence data stored according the output
 152 scheme used by gsl_fft_real_radix2. The result is a real array stored in
 153 natural order.
 154
 155 =item * C<gsl_fft_halfcomplex_radix2_inverse($data, $stride, $n)>
 156
 157 This function computes the inverse in-place radix-2 FFT of length $n and stride
 158 $stride on the half-complex sequence data stored according the output scheme
 159 used by gsl_fft_real_radix2. The result is a real array stored in natural
 160 order.
 161
 162 =item * C<gsl_fft_halfcomplex_radix2_transform>
 163
 164 =item * C<gsl_fft_halfcomplex_wavetable_alloc($n)>
 165
 166 This function prepares trigonometric lookup tables for an FFT of size $n real
 167 elements. The functions return a pointer to the newly allocated struct if no
 168 errors were detected, and a null pointer in the case of error. The length $n is
 169 factorized into a product of subtransforms, and the factors and their
 170 trigonometric coefficients are stored in the wavetable. The trigonometric
 171 coefficients are computed using direct calls to sin and cos, for accuracy.
 172 Recursion relations could be used to compute the lookup table faster, but if an
 173 application performs many FFTs of the same length then computing the wavetable
 174 is a one-off overhead which does not affect the final throughput.  The
 175 wavetable structure can be used repeatedly for any transform of the same
 176 length. The table is not modified by calls to any of the other FFT functions.
 177 The appropriate type of wavetable must be used for forward real or inverse
 178 half-complex transforms.
 179
 180 =item * C<gsl_fft_halfcomplex_wavetable_free($wavetable)>
 181
 182 This function frees the memory associated with the wavetable $wavetable. The
 183 wavetable can be freed if no further FFTs of the same length will be needed.
 184
 185 =item * C<gsl_fft_halfcomplex_backward >
 186
 187 =item * C<gsl_fft_halfcomplex_inverse >
 188
 189 =item * C<gsl_fft_halfcomplex_transform >
 190
 191 =item * C<gsl_fft_halfcomplex_unpack >
 192
 193 =item * C<gsl_fft_halfcomplex_radix2_unpack >
 194
 195 =item * C<gsl_fft_real_radix2_transform($data, $stride, $n) >
 196
 197 This function computes an in-place radix-2 FFT of length $n and stride $stride
 198 on the real array reference $data. The output is a half-complex sequence, which
 199 is stored in-place. The arrangement of the half-complex terms uses the
 200 following scheme: for k < N/2 the real part of the k-th term is stored in
 201 location k, and the corresponding imaginary part is stored in location N-k.
 202 Terms with k > N/2 can be reconstructed using the symmetry z_k = z^*_{N-k}. The
 203 terms for k=0 and k=N/2 are both purely real, and count as a special case.
 204 Their real parts are stored in locations 0 and N/2 respectively, while their
 205 imaginary parts which are zero are not stored. The following table shows the
 206 correspondence between the output data and the equivalent results obtained by
 207 considering the input data as a complex sequence with zero imaginary part,
 208
 209           complex[0].real    =    data[0]
 210           complex[0].imag    =    0
 211           complex[1].real    =    data[1]
 212           complex[1].imag    =    data[N-1]
 213           ...............         ................
 214           complex[k].real    =    data[k]
 215           complex[k].imag    =    data[N-k]
 216           ...............         ................
 217           complex[N/2].real  =    data[N/2]
 218           complex[N/2].imag  =    0
 219           ...............         ................
 220           complex[k'].real   =    data[k]        k' = N - k
 221           complex[k'].imag   =   -data[N-k]
 222           ...............         ................
 223           complex[N-1].real  =    data[1]
 224           complex[N-1].imag  =   -data[N-1]
 225
 226 =for notyou #'
 227
 228 Note that the output data can be converted into the full complex sequence using
 229 the function gsl_fft_halfcomplex_unpack.
 230
 231 =item * C<gsl_fft_real_wavetable_alloc($n)>
 232
 233 This function prepares trigonometric lookup tables for an FFT of size $n real
 234 elements. The functions return a pointer to the newly allocated struct if no
 235 errors were detected, and a null pointer in the case of error. The length $n is
 236 factorized into a product of subtransforms, and the factors and their
 237 trigonometric coefficients are stored in the wavetable. The trigonometric
 238 coefficients are computed using direct calls to sin and cos, for accuracy.
 239 Recursion relations could be used to compute the lookup table faster, but if an
 240 application performs many FFTs of the same length then computing the wavetable
 241 is a one-off overhead which does not affect the final throughput.  The
 242 wavetable structure can be used repeatedly for any transform of the same
 243 length. The table is not modified by calls to any of the other FFT functions.
 244 The appropriate type of wavetable must be used for forward real or inverse
 245 half-complex transforms.
 246
 247 =item * C<gsl_fft_real_wavetable_free($wavetable)>
 248
 249 This function frees the memory associated with the wavetable $wavetable. The
 250 wavetable can be freed if no further FFTs of the same length will be needed.
 251
 252 =item * C<gsl_fft_real_workspace_alloc($n)>
 253
 254 This function allocates a workspace for a real transform of length $n. The same
 255 workspace can be used for both forward real and inverse halfcomplex transforms.
 256
 257 =item * C<gsl_fft_real_workspace_free($workspace)>
 258
 259 This function frees the memory associated with the workspace $workspace. The
 260 workspace can be freed if no further FFTs of the same length will be needed.
 261
 262 =item * C<gsl_fft_real_transform >
 263
 264 =item * C<gsl_fft_real_unpack >
 265
 266 =back
 267
 268 This module also includes the following constants :
 269
 270 =over
 271
 272 =item * C<$gsl_fft_forward>
 273
 274 =item * C<$gsl_fft_backward>
 275
 276 =back
 277
 278 For more informations on the functions, we refer you to the GSL offcial
 279 documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
 280
 281  Tip : search on google: site:http://www.gnu.org/software/gsl/manual/html_node/ name_of_the_function_you_want
 282
 283
 284 =head1 AUTHORS
 285
 286 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 287
 288 =head1 COPYRIGHT AND LICENSE
 289
 290 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 291
 292 This program is free software; you can redistribute it and/or modify it
 293 under the same terms as Perl itself.
 294
 295 =cut
 296
 297 %}