# FreeBSD Manual Pages

HARMINV(1) harminv HARMINV(1)NAMEharminv - extract mode frequencies from time-series dataSYNOPSISharminv[OPTION]... [freq-min-freq-max]...DESCRIPTIONharminvis a program designed to solve the problem of "harmonic inver- sion": given a time series consisting of a sum of sinusoids ("modes"), extract their frequencies and amplitudes. It can also handle the case of exponentially-decaying sinusoids, in which case it extracts their decay rates as well.harminvis often able to achieve much greater accuracy and robustness than Fourier-transform methods, essentially because it assumes a spe- cific form for the input. It uses a low-storage "filter-diagonalization method" (FDM), as de- scribed in V. A. Mandelshtam and H. S. Taylor, "Harmonic inversion of time signals,"J.Chem.Phys.107, 6756 (1997). See also erratum,ibid109, 4128 (1998).INPUTharminvreads in a sequence of whitespace-separated real or complex numbers from standard input, as well as command-line arguments indicat- ing one or more frequency ranges to search, and outputs the modes that it extracts from the data. (It preferentially finds modes in the fre- quency range you specify, but may sometimes find additional modes out- side of that range.) The data should correspond to equally-spaced time intervals, but there is no constraint on the number of points. Complex numbers in the input should be expressed in the formatRE+IMi (no whitespace). Otherwise, whitespace is ignored. Also, comments be- ginning with "#" and extending to the end of the line are ignored. A typical invocation is something like harminv -t 0.02 1-5 < input.dat which reads a sequence of samples, spaced at 0.02 time intervals (in ms, say, corresponding to 50 kHz), and searches for modes in the fre- quency range 1-5 kHz. (See below on units.)OUTPUTharminvwrites six comma-delimited columns to standard output, one line for each mode: frequency, decay constant, Q, amplitude, phase, and er- ror. Each mode corresponds to a function of the form:amplitude* exp[-i (2 pifrequencyt -phase) -decayt] Here, i is sqrt(-1), t is the time (see below for units), and the other parameters in the output columns are:frequencyThe frequency of the mode. If you don't recognize that from the expression above, you should recall Euler's formula: exp(i x) = cos(x) + i sin(x). Note that for complex data, there is a dis- tinction between positive and negative frequencies.decayconstantThe exponential decay constant, indicated bydecayin the above formula. The inverse of this is often called the "lifetime" of the mode. The "half-life" is ln(2)/decay.QA conventional, dimensionless expression of the decay lifetime: Q = pi |frequency|/decay. Q, which stands for "quality fac- tor", is the number of periods for the "energy" in the mode (the squared amplitude) to decay by exp(-2 pi). Equivalently, if you look at the power spectrum (|Fourier transform|^2), 1/Q is the fractional width of the peak at half maximum.amplitudeThe (real, positive) amplitude of the sinusoids. The amplitude (and phase) information generally seems to be less accurate than the frequency and decay constant.phaseThe phase shift (in radians) of the sinusoids, as given by the formula above.errorA crude estimate of the relative error in the (complex) fre- quency. This is not really an error bar, however, so you should treat it more as a figure of merit (smaller is better) for each mode.SPURIOUS MODESTypically, harminv will find a number of spurious solutions in addition to the desired solutions, especially if your data are noisy. Such so- lutions are characterized by large errors, small amplitudes, and/or small Q (large decay rates / broad linewidths). You can omit these from the output by the error/Q/amplitude screening options defined be- low. By default, modes with error > 0.1 and Q < 10 are automatically omit- ted, but it is likely that you will need to set stricter limits.UNITSThe frequency (and decay) values, both input and output, are specified in units of 1/time, where the units of time are determined by the sam- pling intervaldt(the time between consecutive inputs).dtis by de- fault 1, unless you specify it with the-tdtoption. In other words, pick some units (e.g. ms in the example above) and use them to express the time step. Then, be consistent and use the inverse of those units (e.g. kHz = 1/ms) for frequency. Note that the frequency is the usual 1/period definition; it is not the angular frequency.OPTIONS-hDisplay help on the command-line options and usage.-VPrint the version number and copyright info forharminv.-vEnable verbose output, printed to standard output as comment lines (starting with a "#" character). Also, any "#" comments in the input are echoed to the output.-TSpecify period-ranges instead of frequency-ranges on the command line (in units of time corresponding to those specified by-t). The output is still frequency and not period, however.-wSpecify angular frequencies instead of frequencies, and output angular frequency instead of frequency. (Angular frequency is frequency multiplied by 2 pi).-nFlip the sign of the frequency (and phase) convention used in harminv. (The sign of the frequency is only important if you have complex-valued input data, in which case the positive and negative frequency amplitudes can differ.)-tdtSpecify the sampling intervaldt; this determines the units of time used throughout the input and output. Defaults to 1.0.-ddSpecify the spectral "density"dto search for modes, where a density of 1 indicates the usual Fourier resolution. That is, the number of basis functions (which sets an upper bound on the number of modes) is given bydtimes (freq-max-freq-min) timesdttimes the number of samples in your dataset. A maximum of 300 is used, however, to prevent the matrices from getting too big (you can force a larger number with-f, below). Note that the frequency resolution of the outputs isnotlimited by the spectral density, and can generally be much greater than the Fourier resolution. The density determines how many modes, at most, to search for, and in some sense is the density with which the bandwidth is initially "searched" for modes. The default density is 0.0, which means that the number of basis functions is determined by -f (which defaults to 100). This of- ten corresponds to a much larger density than the usual Fourier resolution, but the resulting singularities in the system matri- ces are automatically removed by harminv.-fnfSpecify a lower boundnfon the number of spectral basis func- tions (defaults to 100), setting a lower bound on the number of modes to search for. This option is often a more convenient way to specify the number of basis functions than the-doption, above, which is why it is the default.-falso allows you to employ more than 300 basis functions, but careful: the computation time scales as O(N nf) + O(nf^3), where N is the number of samples, and very large matrices can also have degraded accuracy.-ssortSpecify how the outputs are sorted, wheresortis one of fre- quency/error/Q/decay/amplitude. (Only the first character ofsortmatters.) All sorts are in ascending order. The default is to sort by frequency.-eerrOmit any modes with error (see above) greater thanerrtimes the largest error among the computed modes. Defaults to no limit.-EerrOmit any modes with error (see above) greater thanerr. De- faults to 0.1.-FOmit any modes with frequencies outside the specified range. (Such modes are not necessarily spurious, however.)-aampOmit any modes with amplitude (see above) less thanamptimes the largest amplitude among the computed modes. Defaults to no limit.-AampOmit any modes with amplitude (see above) less thanamp. De- faults to no limit.-QqOmit any modes with |Q| (see above) less thanq. Defaults to 10.BUGSSend bug reports to S. G. Johnson, stevenj@alum.mit.edu.AUTHORSWritten by Steven G. Johnson. Copyright (c) 2005 by the Massachusetts Institute of Technology. harminv June 4, 2005 HARMINV(1)

NAME | SYNOPSIS | DESCRIPTION | INPUT | OUTPUT | SPURIOUS MODES | UNITS | OPTIONS | BUGS | AUTHORS

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=harminv&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>