sddsfft

• description: sddsfft takes Fast Fourier Transforms of real data in columns. It will transform any number of columns simultaneously as a function of a single independent variable. Strictly speaking, the independent variable values should be equispaced; if they are not, sddsfft uses the average spacing. The number of data points need not be a power of two. Output of the magnitude only is the default, but phase and complex values are available.
• examples: Take the FFT of time series samples of PAR x beam-position-monitor readouts:
  sddsfft par.bpm par.fft -column=Time,'P?P?x'
• synopsis:
  sddsfft [-pipe=[input][,output]] [inputFile] [outputFile] -columns=indepVariable[,depenQuantityList] [-padWithZeroes | -truncate] [-sparse=integer] [-window[={hanning | welch | parzen}]] [-complexInput[=folded|unfolded]] [-normalize] [-suppressAverage] [-fullOutput[=folded|unfolded]] [-psdOutput] [-inverse]
• files: inputFile contains the data to be FFT'd. One column from this file must be chosen as the independent variable. By default, all other columns are taken as dependent variables. If inputFile contains multiple pages, each is treated separately and is delivered to a separate page of outputFile.

  outputFile contains a column f for the frequency, along with one or more columns for each independent variable. By default, outputFile has one column named FFTindepName containing the magnitude of the FFT for each independent variable. If -fullOutput is specified, outputFile contains additional columns for, respectively, the phase (or argument), real part, and imaginary part of the FFT: ArgindepName, RealindepName, and ImagindepName. If power-spectral-density output is requested, then a column PSDindepName is also created.

  outputFile also contains two parameters, fftFrequencies and fftFrequencySpacing, giving the number of frequencies and the frequency spacing, respectively.

• switches:
  • pipe[=input][,output] -- The standard SDDS Toolkit pipe option.
  • -columns=indepVariable[,depenQuantityList] -- Specifies the name of the independent variable column. Optionally, specifies a list of comma-separated, optionally wildcard-containing names of dependent quantities to be FFT'd as a function of the independent variable. By default, all numerical columns except the independent column are FFT'd.
  • -exclude=depenQuantity,... -- Specifies optionally wildcarded names of columns to exclude from analysis.
  • -padWithZeros -- Specifies that the independent data should be padded with zeros to make the number of points equal to the nearest power of two. In some cases, this will result in significantly greater speed.
  • -truncate -- Specifies that the data should be truncated so that the number of points is the largest product of primes from 2 to 19 not greater than the original number of points. In some cases, this will result in significantly greater speed.
  • sparse=integer -- Specifies that the data should be uniformly sampled at the given integer interval. While this reduces frequency span of the FFT, it may result in greater speed.
  • window[={hanning | welch | parzen} -- Specifies that data windowing should be performed prior to taking FFT's, and optionally specifies the type of window. The default is hanning. Usually used to improve visibility of small features or accuracy of amplitudes for data that is not periodic in the total sampling time or a submultiple thereof.
  • normalize -- Specifies that FFT's will be normalized to give a maximum magnitude of 1.
  • suppressAverage -- Specifies that the average value of the data will be subtracted from every point prior to taking the FFT. This may improve accuracy and visibility of small components.
  • complexInput -- Specifies that the names of the input columns are of the form Real<rootname> and Imag<rootname>, giving the real and imaginary part of a function to be analyzed. In this case, the <depen-quantity> entries in the -columns option give the rootname, not the full quantity name. It has options folded and unfolded, unfolded means the input frequency space input is unfolded and it must have negative frequency. default is "folded", If no option is given, and if the input file has "SpectrumFolded" parameter, then it will be defined by this parameter.
  • fullOutput -- Specifies that in addition to the magnitude, the phase, real part, and imaginary part of each FFT will be included in the output. It also has folded and unfolded options, while the unfold option outputs the unfolded frequency-space (full FFT spectrum), but the folded option outputs the folded spectrum (half FFT).
  • inverse -- produce inverse fourier transform. when it is given, the output is always unfolded spectrum and it only works with complexInput that has imaginary data.
  • psdOutput -- Specifies that in in addition to ordinary FFT data, the power-spectral-densities will also be included in the output. The units of the PSD are of the form ${\rm x^2/t}$, where x (t) represents the units of the independent (dependent) variable. These units are conventional with PSDs, which are normalized to the frequency spacing so that integrating the PSD gives the signal power.
• How to use the folded and unfolded options There are three cases as listed in the following:
  • real input without inverse option
    

    Table 1: real input without inverse option

    Input	Output
    Real Number	Real Number	Imaginary Number	output option
    N	N/2	N/2	folded
    N	N	N	unfolded

    
    
  • complexInput without inverse option
    

    Table 2: complexInput without inverse option

    ComplexInput				Output
    Real Number	Imaginary Number	Condition	Input option	Real Number	Imaginary Number	output option
    N	N		folded N	N	N	folded
    N	N	last imag=0	folded	2*(N-1)	2*(N-1)	unfolded
    N	N	last imag!=0	folded	2*(N-1)+1)	2*(N-1)+1	unfolded
    N	N		unfolded	N/2	N/2	folded
    N	N		unfolded	N	N	unfolded

    
    
  • with inverse option, since inverse only works with complexInptut, and inverse spectrum is always unfolded, so -fullOutput=folded will be changed to -fullOutput=unfolded with -inverse option.
    

    Table 3: complexInput with inverse option

    ComplexInput				Inverse Output
    Real Number	Imaginary Number	Condition	Input option	Real Number	Imaginary Number
    N	N	last imag=0	folded	2*(N-1)	2*(N-1)
    N	N	last imag!=0	folded	2*(N-1)+1)	2*(N-1)+1
    N	N		unfolded	N	N

    
    
• see also:
  • Data for Examples
  • sddsdigfilter
  • sddsnaff
• author: M. Borland, ANL/APS.