diff sinest.cpp @ 5:5f3c32dc6e17

* Adjust comment syntax to permit Doxygen to generate HTML documentation; add Doxyfile

--- a/sinest.cpp	Tue Oct 05 17:03:27 2010 +0100
+++ b/sinest.cpp	Wed Oct 06 15:19:49 2010 +0100
@@ -8,8 +8,10 @@
 #include "splines.h"
 #include "windowfunctions.h"
 
+/** \file sinest.h */
+
 //---------------------------------------------------------------------------
-/*
+/**
   function dsincd_unn: derivative of unnormalized discrete sinc function
 
   In: x, scale N
@@ -38,7 +40,7 @@
   return r;
 }//dsincd_unn
 
-/*
+/**
   function ddsincd_unn: 2nd-order derivative of unnormalized discrete sinc function
 
   In: x, scale (equivalently, window size) N
@@ -74,7 +76,7 @@
 }//ddsincd_unn
 
 //---------------------------------------------------------------------------
-/*
+/**
   function Window: calculates the cosine-family-windowed spectrum of a complex sinusoid on [0:N-1] at
   frequency f bins with zero central phase.
 
@@ -125,7 +127,7 @@
   return x;
 }//Window
 
-/*
+/**
   function dWindow: calculates the cosine-family-windowed spectrum and its derivative of a complex
   sinusoid on [0:N-1] at frequency f bins with zero central phase.
 
@@ -178,7 +180,7 @@
   }
 }//dWindow
 
-/*
+/**
   function ddWindow: calculates the cosine-family-windowed spectrum and its 1st and 2nd derivatives of
   a complex sinusoid on [0:N-1] at frequency f bins with zero central phase.
 
@@ -239,7 +241,7 @@
 }//ddWindow
 
 //---------------------------------------------------------------------------
-/*
+/**
   function IPWindow: computes the truncated inner product of a windowed spectrum with that of a sinusoid
   at reference frequency f.
 
@@ -267,7 +269,7 @@
   return IPWindow(f, p->x, p->N, p->M, p->c, p->iH2, p->k1, p->k2, true);
 }//IPWindow
 
-/*
+/**
   function ddIPWindow: computes the norm of the truncated inner product of a windowed spectrum with
   that of a sinusoid at reference frequency f, as well as its 1st and 2nd derivatives.
 
@@ -306,7 +308,7 @@
 }//ddIPWindow
 
 //---------------------------------------------------------------------------
-/*
+/**
   function IPWindowC: computes the truncated inner product of a windowed spectrum with that of a
   sinusoid at reference frequency f.
 
@@ -332,7 +334,7 @@
 }//IPWindowC
 
 //---------------------------------------------------------------------------
-/*
+/**
   function sIPWindow: computes the total energy of truncated inner products between multiple windowed
   spectra and that of a sinusoid at a reference frequency f. This does not consider phase alignment
   between the spectra, supposedly measured at a sequence of known instants.
@@ -370,7 +372,7 @@
 	return sIPWindow(f, p->Fr, p->x, p->N, p->M, p->c, p->iH2, p->k1, p->k2, p->lmd);
 }//sIPWindow
 
-/*
+/**
   function dsIPWindow: computes the total energy of truncated inner products between multiple windowed
   spectra and that of a sinusoid at a reference frequency f, as well as its derivative. This does not
   consider phase synchronization between the spectra, supposedly measured at a sequence of known
@@ -409,7 +411,7 @@
 	return dsIPWindow(f, p->Fr, p->x, p->N, p->M, p->c, p->iH2, p->k1, p->k2, p->sip);
 }//dsIPWindow
 
-/*
+/**
   function dsdIPWindow_unn: computes the energy of unnormalized truncated inner products between a given
   windowed spectrum and that of a sinusoid at a reference frequency f, as well as its 1st and 2nd
   derivatives. "Unnormalized" indicates that the inner product cannot be taken as the actual amplitude-
@@ -454,7 +456,7 @@
 	return ddR2;
 }//ddsIPWindow_unn
 
-/*
+/**
   function ddsIPWindow: computes the total energy of truncated inner products between multiple windowed
   spectra and that of a sinusoid at a reference frequency f, as well as its 1st and 2nd derivatives.
   This does not consider phase synchronization between the spectra, supposedly measured at a sequence
@@ -494,7 +496,7 @@
 }//ddsIPWindow
 
 //---------------------------------------------------------------------------
-/*
+/**
   function sIPWindowC: computes the total energy of truncated inner products between multiple frames of
   a spectrogram and multiple frames of a spectrogram of a sinusoid at a reference frequency f.
 
@@ -546,7 +548,7 @@
 	return sIPWindowC(f, p->L, p->offst_rel, p->x, p->N, p->M, p->c, p->iH2, p->k1, p->k2);
 }//sIPWindowC
 
-/*
+/**
   function dsIPWindowC: computes the total energy of truncated inner products between multiple frames of
   a spectrogram and multiple frames of a spectrogram of a sinusoid at a reference frequency f, together
   with its derivative.
@@ -593,7 +595,7 @@
 	return dsIPWindowC(f, p->L, p->offst_rel, p->x, p->N, p->M, p->c, p->iH2, p->k1, p->k2, p->sip);
 }//dsIPWindowC
 
-/*
+/**
   function ddsIPWindowC: computes the total energy of truncated inner products between multiple frames
   of a spectrogram and multiple frames of a spectrogram of a sinusoid at a reference frequency f,
   together with its 1st and 2nd derivatives.
@@ -657,7 +659,7 @@
   Further reading: "Least-square-error estimation of sinusoids.pdf"
 */
 
-/*
+/**
   function LSESinusoid: LSE estimation of the predominant stationary sinusoid.
 
   In: x[N]: windowed spectrum
@@ -727,7 +729,7 @@
   pp=IPWindow(f, x, N, M, c, iH2, p.k1, p.k2, false);
 }//LSESinusoid
 
-/*
+/**
   function LSESinusoid: LSE estimation of stationary sinusoid predominant within [f1, f2].
 
   In: x[N]: windowed spectrum
@@ -769,7 +771,7 @@
   return f;
 }//LSESinusoid
 
-/*
+/**
   function LSESinusoid: LSE estimation of stationary sinusoid near a given initial frequency within [f1,
   f2].
 
@@ -819,7 +821,7 @@
   return result;
 }//LSESinusoid
 
-/*
+/**
   function LSESinusoidMP: LSE estimation of a stationary sinusoid from multi-frames spectrogram without
   considering phase-frequency consistency across frames.
 
@@ -855,7 +857,7 @@
   return errf;
 }//LSESinusoidMP
 
-/*
+/**
   function LSESinusoidMP: LSE estimation of a stationary sinusoid from multi-frames spectrogram without
   considering phase-frequency consistency across frames.
 
@@ -899,7 +901,7 @@
 }//LSESinusoidMPC
 
 //---------------------------------------------------------------------------
-/*
+/**
   function IPMulti: least square estimation of multiple sinusoids, given their frequencies and an energy
   suppression index of eps, i.e. the least square error is minimized with an additional eps*||lmd||^2
   term.
@@ -926,7 +928,7 @@
   delete List;
 }//IPMulti
 
-/*
+/**
   function IPMulti: least square estimation of multiple sinusoids, given their frequencies and an energy
   suppression index of eps, and optionally returns residue and sensitivity indicators for each sinusoid.
 
@@ -977,7 +979,7 @@
   delete List;
 }//IPMulti
 
-/*
+/**
   function IPMultiSens: computes the sensitivity of the least square estimation of multiple sinusoids given
   their frequencies .
 
@@ -1009,7 +1011,7 @@
   delete List;
 }//IPMultiSens
 
-/*
+/**
   function IPMulti: least square estimation of multi-sinusoids with GIVEN frequencies. This version
   operates in groups at least B bins from each other, rather than LSE all frequencies together.
 
@@ -1056,7 +1058,7 @@
   return 0;
 }//IPMulti
 
-/*
+/**
   function IPMulti_Direct: LSE estimation of multiple sinusoids given frequencies AND PHASES (direct
   method)
 
@@ -1115,7 +1117,7 @@
   return result;
 }//IPMulti_Direct
 
-/*
+/**
   function IPMulti_GS: LSE estimation of multiple sinusoids given frequencies AND PHASES (Gram-Schmidt method)
 
   In: x[Wid]: spectrum
@@ -1173,7 +1175,7 @@
 	return result;
 }//IPMulti_GS
 
-/*
+/**
   function IPMulti: LSE estimation of I sinusoids given frequency and phase and J sinusoids given
   frequency only
 
@@ -1234,7 +1236,7 @@
     Further reading: "LSE estimation for 2 sinusoids with 1 at a fixed frequency.pdf"
 */
 
-/*
+/**
   function WindowDuo: calcualtes the square norm of the inner product between windowed spectra of two
   sinusoids at frequencies f1 and f2, df=f1-f2.
 
@@ -1262,7 +1264,7 @@
 	return result;
 }//WindowDuo
 
-/*
+/**
   function ddWindowDuo: calcualtes the square norm of the inner product between windowed spectra of two
   sinusoids at frequencies f1 and f2, df=f1-f2, with its 1st and 2nd derivatives
 
@@ -1295,7 +1297,7 @@
   return ddwindow;
 }//ddWindowDuo
 
-/*
+/**
   function sIPWindowDuo: calculates the square norm of the orthogonal projection of a windowed spectrum
   onto the linear span of the windowed spectra of two sinusoids at reference frequencies f1 and f2.
 
@@ -1333,7 +1335,7 @@
 	return sIPWindowDuo(p->f1, f2, p->x, p->N, p->c, p->d, p->M, p->iH2, p->k1, p->k2, r1, r2);
 }//sIPWindowDuo
 
-/*
+/**
   function ddsIPWindowDuo: calculates the square norm, and its 1st and 2nd derivatives against f2,, of
   the orthogonal projection of a windowed spectrum onto the linear span of the windowed spectra of two
   sinusoids at reference frequencies f1 and f2.
@@ -1382,7 +1384,7 @@
   return ddsip2[0];
 }//ddsIPWindowDuo
 
-/*
+/**
   function LSEDuo: least-square estimation of two sinusoids of which one has a fixed frequency
 
   In: x[N]: the windowed spectrum
@@ -1427,7 +1429,7 @@
     operators,¡± in Proc. ICMC¡¯02. G?teborg. 2002.
 */
 
-/*
+/**
   function CDFTW: single-frequency windowed DTFT, centre-aligned
 
   In: data[Wid]: waveform data x
@@ -1450,7 +1452,7 @@
   }
 }//CDFTW
 
-/*
+/**
   function CuDFTW: single-frequency windowed DTFT of t*data[t], centre-aligned
 
   In: data[Wid]: waveform data x
@@ -1474,7 +1476,7 @@
   }
 }//CuDFTW
 
-/*
+/**
   function TFReas: time-frequency reassignment
 
   In: data[Wid]: waveform data
@@ -1507,7 +1509,7 @@
   else fslope=0;
 } //TFReas*/
 
-/*
+/**
   function TFReas: sinusoid estimation using reassignment method
 
   In: data[Wid]: waveform data
@@ -1567,7 +1569,7 @@
     for the sinusoid modeling of audio," in Proc. EUSIPCO'09, Glasgow, 2009.
 */
 
-/*
+/**
   function AdditiveUpdate: additive reestimation of time-varying sinusoid
 
   In: x[Count]: waveform data
@@ -1643,7 +1645,7 @@
 	delete[] y; delete[] lf; delete[] ref;
 }//AdditiveUpdate
 
-/*
+/**
   function AdditiveAnalyzer: sinusoid analyzer with one additive update
 
   In: x[Count]: waveform data
@@ -1663,7 +1665,7 @@
 	AdditiveUpdate(fs, as, phs, das, x, Count, Wid, Offst, BasicAnalyzer, reserved, LogA);
 }//AdditiveAnalyzer
 
-/*
+/**
   function MultiplicativeUpdate: multiplicative reestimation of time-varying sinusoid
 
   In: x[Count]: waveform data
@@ -1728,7 +1730,7 @@
 	delete[] y; delete[] lf; delete[] lref;
 }//MultiplicativeUpdate
 
-/*
+/**
   function MultiplicativeAnalyzer: sinusoid analyzer with one multiplicative update
 
   In: x[Count]: waveform data
@@ -1806,7 +1808,7 @@
     sinusoids by demodulation," in Proc. DAFx'08, Espoo, 2008.
 */
 
-/*
+/**
   function ReEstFreq: sinusoid reestimation by demodulating frequency.
 
   In: x[Wid+Offst*(FrCount-1)]: waveform data
@@ -1896,7 +1898,7 @@
   }
 }//ReEstFreq
 
-/*
+/**
   function ReEstFreq_2: sinusoid reestimation by demodulating frequency. This is that same as ReEstFreq(...)
   except that it calls Sinusoid(...) to synthesize the phase track used for demodulation and that it
   does not allow variable window sizes for estimating demodulated sinusoid.
@@ -1975,7 +1977,7 @@
   }
 }//ReEstFreq_2
 
-/*
+/**
   function ReEstFreqAmp: sinusoid reestimation by demodulating frequency and amplitude.
 
   In: x[Wid+Offst*(FrCount-1)]: waveform data
@@ -2087,7 +2089,7 @@
   }
 }//ReEstFreqAmp
 
-/*
+/**
   function Reestimate2: iterative demodulation method for sinusoid parameter reestimation.
 
   In: x[(FrCount-1)*Offst+Wid]: waveform data
@@ -2176,7 +2178,7 @@
     using derivatives," in Proc. DAFx'09, Como, 2009.
 */
 
-/*
+/**
   function Derivative: derivative method for estimating amplitude derivative, frequency, and frequency derivative given
   signal and its derivatives.
 
@@ -2225,7 +2227,7 @@
   FreeFFTBuffer(fft);
 }//Derivative
 
-/*
+/**
   function Xkw: computes windowed spectrum of x and its derivatives up to order K at angular frequency omg,
   from x using window w and its derivatives.
 
@@ -2259,7 +2261,7 @@
   }
 }//Xkw
 
-/*
+/**
   function Xkw: computes windowed spectrum of x and its derivatives up to order K at angular frequency
   omg, from x and its derivatives using window w.
 
@@ -2286,7 +2288,7 @@
   }
 }//Xkw
 
-/*
+/**
   function Derivative: derivative method for estimating the model log(s)=h[M]'r[M], by discarding extra
   equations
 
@@ -2407,7 +2409,7 @@
 	DeAlloc2(A);
 }//Derivative*/
 
-/*
+/**
   function DerivativeLS: derivative method for estimating the model log(s)=h[M]'r[M], least-square
   implementation
 
@@ -2497,7 +2499,7 @@
 	DeAlloc2(A);
 }//DerivativeLS
 
-/*
+/**
   function DerivativeLS: derivative method for estimating the model log(s)=h[M]'r[M] using Fr
   measurement points a quarter of Wid apart from each other, implemented by least-square.
 
@@ -2602,7 +2604,7 @@
     modeling,¡± in Proc. ICASSP'05, Philadelphia, 2005.
 */
 
-/*
+/**
   function RDFTW: windowed DTFT at frequency k bins
 
   In: data[Wid]: waveform data
@@ -2629,7 +2631,7 @@
   }
 }//RDFTW
 
-/*
+/**
   function TFAS05: the Abe-Smith method 2005
 
   In: data[Wid]: waveform data
@@ -2723,7 +2725,7 @@
 	f=feses/Wid, a=exp(yeses), ph=pheses, fslope=2*beta/2/M_PI, aesp=alf;
 }//TFAS05
 
-/*
+/**
   function TFAS05_enh: the Abe-Smith method 2005 enhanced by LSE amplitude and phase estimation
 
   In: data[Wid]: waveform data
@@ -2757,7 +2759,7 @@
 }//TFAS05_enh
 
 //---------------------------------------------------------------------------
-/*
+/**
   function DerivativeLSv_AmpPh: estimate the constant-term in the local derivative method. This is used
   by the local derivative algorithm, whose implementation is found in the header file as templates.
 
@@ -2788,7 +2790,7 @@
     sinusoids," under review.
 */
 
-/*
+/**
   function setv: computes I test functions v[I] by modulation u[I] to frequency f
 
   In: u[I+1][Wid], du[I+1][Wid]: base-band test functions and their derivatives
@@ -2816,7 +2818,7 @@
   }
 }//setv
 
-/*
+/**
   function setvhalf: computes I half-size test functions v[I] by modulation u[I] to frequency f.
 
   In: u[I][hWid*2], du[I][Wid*2]: base-band test functions and their derivatives
@@ -2840,7 +2842,7 @@
 
 //#define ERROR_CHECK
 
-/*
+/**
   function DerivativePiecewise: Piecewise derivative algorithm. In this implementation of the piecewise
   method the test functions v are constructed from I "basic" (single-frame) test functions, each
   covering the same period of 2T, by shifting these I functions by steps of T. A total number of (L-1)I
@@ -3023,7 +3025,7 @@
   delete mlist;
 }//DerivativePiecewise
 
-/*
+/**
   function DerivativePiecewise2: Piecewise derivative algorithm in which the real and imaginary parts of
   the exponent are modelled separately. In this implementation of the piecewise method the test
   functions v are constructed from I "basic" (single-frame) test functions, each covering the same
@@ -3278,7 +3280,7 @@
   return ene;
 }//testsv
 
-/*
+/**
   function DerivativePiecewise3: Piecewise derivative algorithm in which the log amplitude and frequeny
   are modeled separately as piecewise functions. In this implementation of the piecewise method the test
   functions v are constructed from I "basic" (single-frame) test functions, each covering the same
@@ -3444,7 +3446,7 @@
 
 //initialization routines for the piecewise derivative method
 
-/*
+/**
   function seth: set h[M] to a series of power functions.
 
   In: M, T.
@@ -3463,7 +3465,7 @@
  }
 }//seth
 
-/*
+/**
   function setdh: set dh[M] to the derivative of a series of power functions.
 
   In: M, T.
@@ -3483,7 +3485,7 @@
  }
 }//setdh
 
-/*
+/**
   function setdih: set dih[M] to the difference of the integral of a series of power functions.
 
   In: M, I
@@ -3502,7 +3504,7 @@
   }
 }//setdih
 
-/*
+/**
   function sshLinear: sets M and h[M] for the linear spline model
 
   In: T
@@ -3516,7 +3518,7 @@
   for (int t=0; t<T; t++) h[0][t]=1, h[1][t]=t;
 }//sshLinear
 
-/*
+/**
   function sdihLinear: sets dih[M] for the linear spline model. For testing only.
 
   In: T
@@ -3530,7 +3532,7 @@
   for (int t=0; t<T; t++)	dih[0][t]=1, dih[1][t]=t+0.5;
 }//sdihLinear
 
-/*
+/**
   function sshCubic: sets M and h[M] for cubic spline models.
 
   In: T
@@ -3544,7 +3546,7 @@
   for (int t=0; t<T; t++) h[3][t]=t*t*t, h[2][t]=t*t, h[1][t]=t, h[0][t]=1;
 }//sshCubic
 
-/*
+/**
   function sdihCubic: sets dih[M] for cubic spline models.
 
   In: T
@@ -3561,7 +3563,7 @@
   }
 }//sdihCubic*/
 
-/*
+/**
   function ssALinearSpline: sets N and A[L] for the linear spline model
 
   In: L, M, T
@@ -3577,7 +3579,7 @@
   double iT=1.0/T; for (int l=0; l<L; l++) A[l][0][l]=1, A[l][1][l]=-iT, A[l][1][l+1]=iT;
 }//ssALinearSpline
 
-/*
+/**
   function ssLinearSpline: sets M, N, h and A for the linear spline model
 
   In: L, M, T
@@ -3591,7 +3593,7 @@
   ssALinearSpline(L, T, M, N, A, mlist);
 }//ssLinearSpline
 
-/*
+/**
   function ssACubicHermite: sets N and A[L] for cubic Hermite spline model
 
   In: L, M, T
@@ -3613,7 +3615,7 @@
   }
 }//ssACubicHermite
 
-/*
+/**
   function ssLinearSpline: sets M, N, h and A for the cubic Hermite spline model
 
   In: L, M, T
@@ -3627,7 +3629,7 @@
   ssACubicHermite(L, T, M, N, A, mlist);
 }//ssCubicHermite
 
-/*
+/**
   function ssACubicSpline: sets N and A[L] for cubic spline model
 
   In: L, M, T
@@ -3662,7 +3664,7 @@
   DeAlloc2(ML); DeAlloc2(MR); DeAlloc2(M42);
 }//ssACubicSpline
 
-/*
+/**
   function ssLinearSpline: sets M, N, h and A for the cubic spline model
 
   In: L, M, T
@@ -3676,7 +3678,7 @@
   ssACubicSpline(L, T, M, N, A, mlist, mode);
 }//ssCubicSpline
 
-/*
+/**
   function setu: sets u[I+1] as base-band windowed Fourier atoms, whose frequencies come in the order of
   0, 1, -1, 2, -2, 3, -3, 4, etc, in bins.
 
@@ -3707,7 +3709,7 @@
   DeAlloc2(wins);
 }//setu
 
-/*
+/**
   function DerivativePiecewiseI: wrapper for DerivativePiecewise(), doing the initialization ,etc.
 
   In: L, T: number and length of pieces
@@ -3739,7 +3741,7 @@
   delete mlist;
 }//DerivativePiecewiseI
 
-/*
+/**
   function DerivativePiecewiseII: wrapper for DerivativePiecewise2(), doing the initialization ,etc.
   This models the derivative of log ampltiude and frequency as separate piecewise polynomials, the first
   specified by SpecifyA, the second by SpecifyB.
@@ -3778,7 +3780,7 @@
   delete mlist;
 }//DerivativePiecewiseII
 
-/*
+/**
   function DerivativePiecewiseIII: wrapper for DerivativePiecewise3(), doing the initialization ,etc.
   Notice that this time the log amplitude, rather than its derivative, is modeled as a piecewise
   polynomial specified by SpecifyA.
@@ -3826,7 +3828,7 @@
   delete mlist;
 }//DerivativePiecewiseIII
 
-/*
+/**
   function AmpPhCorrectionExpA: model-preserving amplitude and phase correction in piecewise derivative
   method.
 
@@ -3968,3 +3970,4 @@
   delete mlist;
   return result;
 }//AmpPhCorrectionExpA
+