MUSIC-based Estimators

API references

doatools.estimation.music.f_music(A, En)[source]

Computes the classical MUSIC spectrum

This is a vectorized implementation of the spectrum function:

\[P_{\mathrm{MUSIC}}(\theta) = \frac{1}{\mathbf{a}^H(\theta) \mathbf{E}_\mathrm{n} \mathbf{E}_\mathrm{n}^H \mathbf{a}(\theta)}\]
Parameters:
  • A – m x k steering matrix of candidate direction-of-arrivals, where m is the number of sensors and k is the number of candidate direction-of-arrivals.
  • En – m x d matrix of noise eigenvectors, where d is the dimension of the noise subspace.
class doatools.estimation.music.MUSIC(array, wavelength, search_grid, **kwargs)[source]

Bases: doatools.estimation.core.SpectrumBasedEstimatorBase

Creates a spectrum-based MUSIC estimator.

The MUSIC spectrum is computed on a predefined-grid using f_music(), and the source locations are estimated by identifying the peaks.

Parameters:
  • array (ArrayDesign) – Array design.
  • wavelength (float) – Wavelength of the carrier wave.
  • search_grid (SearchGrid) – The search grid used to locate the sources.
  • **kwargs – Other keyword arguments supported by SpectrumBasedEstimatorBase.

References

[1] R. Schmidt, “Multiple emitter location and signal parameter estimation,” IEEE Transactions on Antennas and Propagation, vol. 34, no. 3, pp. 276-280, Mar. 1986.

estimate(R, k, **kwargs)[source]

Estimates the source locations from the given covariance matrix.

Parameters:
  • R (ndarray) – Covariance matrix input. The size of R must match that of the array design used when creating this estimator.
  • k (int) – Expected number of sources.
  • return_spectrum (bool) – Set to True to also output the spectrum for visualization. Default value if False.
  • refine_estimates (bool) – Set to True to enable grid refinement to obtain potentially more accurate estimates.
  • refinement_density (int) – Density of the refinement grids. Higher density values lead to denser refinement grids and increased computational complexity. Default value is 10.
  • refinement_iters (int) – Number of refinement iterations. More iterations generally lead to better results, at the cost of increased computational complexity. Default value is 3.
Returns:

A tuple with the following elements.

  • resolved (bool): A boolean indicating if the desired number of sources are found. This flag does not guarantee that the estimated source locations are correct. The estimated source locations may be completely wrong! If resolved is False, both estimates and spectrum will be None.
  • estimates (SourcePlacement): A SourcePlacement instance of the same type as the one used in the search grid, represeting the estimated source locations. Will be None if resolved is False.
  • spectrum (ndarray): An numpy array of the same shape of the specified search grid, consisting of values evaluated at the grid points. Only present if return_spectrum is True.
class doatools.estimation.music.RootMUSIC1D(wavelength)[source]

Bases: object

Creates a root-MUSIC estimator for uniform linear arrays.

Parameters:wavelength (float) – Wavelength of the carrier wave.

References

[1] A. Barabell, “Improving the resolution performance of eigenstructure-based direction-finding algorithms,” ICASSP ‘83. IEEE International Conference on Acoustics, Speech, and Signal Processing, Boston, Massachusetts, USA, 1983, pp. 336-339.

[2] B. D. Rao and K. V. S. Hari, “Performance analysis of Root-Music,” IEEE Transactions on Acoustics, Speech, and Signal Processing, vol. 37, no. 12, pp. 1939-1949, Dec. 1989.

estimate(R, k, d0=None, unit='rad')[source]

Estimates the direction-of-arrivals of 1D far-field sources.

Parameters:
  • R (ndarray) – Covariance matrix input. This covariance matrix must be obtained using a uniform linear array.
  • k (int) – Expected number of sources.
  • d0 (float) – Inter-element spacing of the uniform linear array used to obtain R. If not specified, it will be set to one half of the wavelength used when creating this estimator. Default value is None.
  • unit (str) – Unit of the estimates. Default value is 'rad'. See FarField1DSourcePlacement for more details on valid units.
Returns:

A tuple with the following elements.

  • resolved (bool): True only if the rooting algorithm successfully finds k roots inside the unit circle. This flag does not guarantee that the estimated source locations are correct. The estimated source locations may be completely wrong! If resolved is False, estimates will be None.
  • estimates (FarField1DSourcePlacement): A FarField1DSourcePlacement recording the estimated source locations. Will be None if resolved is False.