Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	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.

       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 de-
       scribed 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 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	format	RE+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.)

OUTPUT
       harminv writes 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 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 dis-
	      tinction 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 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.

       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)  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 MODES
       Typically, 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.

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  sam-
       pling  interval dt (the time between consecutive	inputs).  dt is	by de-
       fault 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 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.

       -f nf  Specify  a  lower	bound nf on 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  -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  fre-
	      quency/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.   De-
	      faults 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.   De-
	      faults 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)

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>

home | help