HARMINV(1)							      harminv								HARMINV(1)

NAME

       harminv - extract mode frequencies from time-series data

SYNOPSIS

       harminv [OPTION]... [freq-min-freq-max]...

DESCRIPTION

       harminv is a program designed to solve the problem of "harmonic inversion": 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.

       harminv is 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 described in V. A. Mandelshtam and H. S.  Taylor,  "Harmonic  inversion	of
       time signals," J. Chem. Phys. 107, 6756 (1997).	See also erratum, ibid 109, 4128 (1998).

INPUT

       harminv reads 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
       frequency  range you specify, but may sometimes find additional modes outside 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 format RE+IMi (no whitespace).  Otherwise, whitespace is ignored.   Also,  comments
       beginning 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.)

OUTPUT

       harminv writes six comma-delimited columns to standard output, one line for each mode: frequency, decay constant, Q, amplitude, phase,  and
       error.  Each mode corresponds to a function of the form:

       amplitude * exp[-i (2 pi frequency t - phase) - decay t]

       Here, i is sqrt(-1), t is the time (see below for units), and the other parameters in the output columns are:

       frequency
	      The  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 distinction between positive and negative frequencies.

       decay constant
	      The exponential decay constant, indicated by decay in the above formula.	The inverse of this is often called the "lifetime" of  the
	      mode. The "half-life" is ln(2)/decay.

       Q      A  conventional,	dimensionless expression of the decay lifetime: Q = pi |frequency| / decay.  Q, which stands for "quality factor",
	      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.

       amplitude
	      The (real, positive) amplitude of the sinusoids.	The amplitude (and phase) information generally seems to be less accurate than the
	      frequency and decay constant.

       phase  The phase shift (in radians) of the sinusoids, as given by the formula above.

       error  A crude estimate of the relative error in the (complex) frequency.  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 MODES

       Typically,  harminv will find a number of spurious solutions in addition to the desired solutions, especially if your data are noisy.  Such
       solutions 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 below.

       By default, modes with error > 0.1 and Q < 10 are automatically omitted, but it is likely that you will need to set stricter limits.

UNITS

       The  frequency  (and  decay) values, both input and output, are specified in units of 1/time, where the units of time are determined by the
       sampling interval dt (the time between consecutive inputs).  dt is by default 1, unless you specify it with the -t dt option.

       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

       -h     Display help on the command-line options and usage.

       -V     Print the version number and copyright info for harminv.

       -v     Enable  verbose  output, printed to standard output as comment lines (starting with a "#" character).  Also, any "#" comments in the
	      input are echoed to the output.

       -T     Specify 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.

       -w     Specify  angular	frequencies instead of frequencies, and output angular frequency instead of frequency.	(Angular frequency is fre-
	      quency multiplied by 2 pi).

       -n     Flip 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.)

       -t dt  Specify the sampling interval dt; this determines the units of time used throughout the input and output.  Defaults to 1.0.

       -d d   Specify  the  spectral  "density"  d to 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 by d times	(freq-max  -  freq-min)  times	dt
	      times  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 is not limited 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  often
	      corresponds  to  a much larger density than the usual Fourier resolution, but the resulting singularities in the system matrices are
	      automatically removed by harminv.

       -f nf  Specify a lower bound nf on the number of spectral basis functions (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 -d option, above, which
	      is why it is the default.

	      -f also 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.

       -s sort
	      Specify  how the outputs are sorted, where sort is one of frequency/error/Q/decay/amplitude.  (Only the first character of sort mat-
	      ters.)  All sorts are in ascending order.  The default is to sort by frequency.

       -e err Omit any modes with error (see above) greater than err times the largest error among the computed modes.	Defaults to no limit.

       -E err Omit any modes with error (see above) greater than err.  Defaults to 0.1.

       -F     Omit any modes with frequencies outside the specified range.  (Such modes are not necessarily spurious, however.)

       -a amp Omit any modes with amplitude (see above) less than amp times the largest amplitude among the computed modes.  Defaults to no limit.

       -A amp Omit any modes with amplitude (see above) less than amp.	Defaults to no limit.

       -Q q   Omit any modes with |Q| (see above) less than q.	Defaults to 10.

BUGS

       Send bug reports to S. G. Johnson, stevenj@alum.mit.edu.

AUTHORS

       Written by Steven G. Johnson.  Copyright (c) 2005 by the Massachusetts Institute of Technology.

harminv 							   June 4, 2005 							HARMINV(1)