- description: sddsnaff is an implementation of Laskar’s Numerical Analysis of Fundamental
Frequencies (NAFF) algorithm. This algorithm provides a way of determining the frequency
components of a signal that is more accurate than Fast Fourier Transforms (FFT). FFTs are
used as part of the analysis, so if an FFT is sufficient for an application, sddsfft should be
used as it will be much faster.
The algorithm starts by removing the average value of the signal and applying a Hanning window. Next, the signal is FFT’d and the frequency at which the maximum FFT amplitude occurs is found. This is taken as the starting frequency for a numerical optimization of the “overlap” between the signal and e

^{iωt}, which allows determining ω to resolution greater than the frequency spacing of the FFT. Once ω is determined, the overlap is subtracted from the original signal and the process is repeated, if desired. - examples: Find the first fundamental frequency for each of the BPM signals in par.bpm.
sddsnaff par.bpm par.naff -column=Time,’P?P?x’ -terminateSearch=frequencies=1

- synopsis:
sddsnaff [inputfile] [outputfile] [-pipe=[input][,output]] [-columns=indep-variable[,depen-quantity[,...]]] [-pair=<column1>,<column2>] [-exclude=depen-quantity[,...]] [-terminateSearch=changeLimit=fraction[,maxFrequencies=number] | frequencies=number] [-iterateFrequency=[cycleLimit=number][,accuracyLimit=fraction]] [-truncate] [-noWarnings]

- files:
inputFile contains the data to be NAFF’d. One column from this file must be chosen as the independent variable. If inputFile contains multiple pages, each is treated separately and is delivered to a separate page of outputFile.

outputFile contains two columns for each selected column in inputFile. These columns have names like origColumnFrequency and origColumnAmplitude, giving the frequency and amplitude for origColumn.

- switches:
- pipe[=input][,output] — The standard SDDS Toolkit pipe option.
- -columns=indepVariable[,depenQuantityList] — Specifies the name of the independent variable column. Optionally if no -pair options given, specifies a list of comma-separated, optionally wildcard-containing names of dependent quantities to be NAFF’d as a function of the independent variable. By default, all numerical columns except the independent column are NAFF’d.
- -pair=<column1>,<column2>] — Specifies the names of the conjugate pairs to give double the frequency range. ¡column1¿ is used to obtain the basic frequency, ¡column2¿ is used to obtain the phase at the frequency of the first column. The relative phase between them will expand the resulting frequency from 0 - Fn to 0 - 2*Fn. Multiple -pair options may be provided. The indepentdent column is provided by -columns option. The dependent columns may be provided by either -columns or -pair option.
- -exclude=depenQuantity,... — Specifies optionally wildcarded names of columns to exclude from analysis.
- -terminateSearch={changeLimit=fraction[maxFrequencies=number] | frequencies=number} — Specifies when to stop searching for frequency components. If changeLimit is given, then the program stops when the RMS change in the signal is less than the specified fraction of the original RMS value of the signal. The maximum number of frequencies that will be returned in this mode is specified with maxFrequencies (default is 4). If frequencies is given, then the program finds the given number of frequencies, if possible. By default, the program finds one frequency for each signal.
- -iterateFrequency=[cycleLimit=number][,accuracyLimit=fraction] — This option controls the optimization procedure that searches for the best frequency. By default, the procedure executes 100 passes and attempts to determine the frequency to a precision of 0.00001 of the Nyquist frequency. cycleLimit is used to change the number of passes, while accuracyLimit is used to specify the desired precision.
- -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, by making the FFTs faster.
- -noWarnings — Suppresses warning messages.

- see also:
- author: M. Borland, ANL/APS.