../lib/numru/gphys/gphys_fft.rb

# extention of class NumRu::GPhys -- Fast Fourier transformation and its applications

This manual documents the methods of NumRu::GPhys defined in gphys_fft.rb

# methods

#### `fft(backward=false, *dims)`

  Fast Fourier Transformation (FFT) by using (FFTW) ver 3 or ver 2. A FFTW ver.2 interface is included in NArray, while to use FFTW ver.3, you have to install separately. Dimension specification by the argument dims is available only with ver.3. By default, FFT is applied to all dimensions.

  The transformation is complex. If the input data is not complex, it will be coerced to complex before transformation.

  When the FT is forward, the result is normalized (i.e., divided by the data number), unlike the default behavior of FFTW.

  Each coordinate is assumed to be equally spaced without checking. The new coordinate variables will be set equal to wavenumbers, derived as 2*PI/(length of the axis)*[0,1,2,..], where the length of the axis is derieved as (coord.val.max - coord.val.min)*(n+1)/n.

  ARGUMENTS

  - backward (true of false) : when true, backward FT is done; otherwise forward FT is done.
  - dims (integers) : dimensions to apply FFT

  RETURN VALUE

  - a GPhys

  EXAMPLE

      gphy.fft           # forward, for all dimensions
      gphy.fft(true)     # backward, for all dimensions
      gphy.fft(nil, 0,1) # forward, for the first and second dimensions.
      gphy.fft(true, -1) # backward, for the last dimension.

#### `detrend(dim1[,dim2[,...]])`

  Remove means and linear trends along dimension(s) specified. Algorithm: 1st order polynomial fitting.

  ARGUMENTS

  - dim? (Integer of String): the dimension along which you want to remove trends.

  RETURN VALUE

  - a GPhys

#### `cos_taper(dim1[,dim2[,...]])`

  Cosine tapering along dimension(s) specified.

  Algorithm: to multiply with the half cosine curves at the both 1/10 ends of the data.

      cos taper shape:
               _____________
             _/             \_
           ->   <-       ->   <-
            T/10           T/10
         half-cosine     half-cosine
           shaped         shaped

  The spectra of tapered data should be multilied by 1/0.875, which is stored as GPhys::COS_TAPER_SP_FACTOR (==1/0.875).

  ARGUMENTS

  - dim? (Integer of String): the dimension along which you want to remove trends.

  RETURN VALUE

  - a GPhys

#### `spect_zero_centering(dim)`

  Shifts the waveneumber axis to cover from -K/2 to K/2 instead of from 0 to K-1, where the wavenumber is simbolically treated as integer, which is actually not the case, though. Since the first (-K/2) and the last (K/2) elements are duplicated, both are divided by 2. Therefore, this method is to be used for spectra (squared quantity) rather than the raw Fourier coefficients. (That is why the method name is prefixed by "spect_").

  The method is applied for a single dimension (specified by the argument dim). If you need to apply for multiple dimensions, use it for multiple times.

  ARGUMENTS

  - dim (integer): the dimension you want to shift spectra elements. Count starts from zero.

  RETURN VALUE

  - a GPhys

  EXAMPLE

  - To get a spectra of a variable var along the 1st and 2nd dimensions:

        fc = var.fft(nil, 0,1)    # --> Fourier coef
        sp = ( fc.abs**2 ).spect_zero_centering(0).spect_zero_centering(1)

    Note that spect_zero_centering is applied after taking |fc|^2.

  - Same but if you want to have the 2nd dimension one-sided:

        fc = var.fft(nil, 0,1)
        sp = ( fc.abs**2 ).spect_zero_centering(0).spect_one_sided(1)

  - Similar to the first example but for cross spectra:

        fc1 = var1.fft(nil, 0,1)
        fc2 = var2.fft(nil, 0,1)
        xsp = (fc1 * fc2.conj).spect_zero_centering(0).spect_zero_centering(1)

#### `spect_one_sided(dim)`

  Similar to spect_zero_centering but to make one-sided spectra. Namely, to convert from 0..K-1 to 0..K/2. To be applied for spectra; wavenumber 2..K/2-1 are multiplied by 2.

  ARGUMENTS

  - dim (integer): the dimension you want to shift spectra elements. Count starts from zero.

  RETURN VALUE

  - a GPhys

  EXAMPLE

  - See the 2nd example of spect_zero_centering.

#### `rawspect2powerspect(*dims)`

  Converts raw spectra obtained by gphys.fft.abs**2 into power spectra by dividing by wavenumber increments along the dimensions spcified by dims.

  ARGUMENTS

  - dims (integers): the dimensions corresponding to wavenumbers.

  RETURN VALUE

  - a GPhys

  EXAMPLE

  - Suppose a 2 (or more) dimensional data gphys.

        fc = gphys.fft(nil, 0, 1)
        sp = fc.abs**2
        ps = sp.rawspect2powerspect(0,1)

    Here, sp is the raw spectum of gphys, and ps is the power spectrum. The Parseval relation for them are as follows:

        (gphys**2).mean == sp.sum
                        == pw.sum*dk*dl (== \int pw dk dl, mathematically),

    where, dk = (pw.coord(0)[1] - pw.coord(0)[0]), and dl = (pw.coord(1)[1] - pw.coord(1)[0]).