Man Linux: Main Page and Category List

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
       specific 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
       indicating 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
       frequency 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
              frequency 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  matters.)   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.