Coarray reconstruction

API reference

class doatools.estimation.coarray_reconstruction.CovarianceReconstructionBase(array, wavelength, doa_estimator=None, search_grid=None, **kwargs)[source]

Bases: ABC

Base class for covariance matrix reconstruction algorithms.

Covariance matrix reconstruction algorithms aim to transform the sample covariance matrix of a sparse array into an augmented covariance matrix that corresponds to a larger virtual uniform linear array, typically based on the difference coarray concept.

property virtual_array

Retrieves the corresponding virtual uniform linear array.

Returns:

Virtual uniform linear array.

Return type:

UniformLinearArray

property solver

Retrieves the selected solver.

Returns:

Selected solver name.

Return type:

str

property doa_estimator

Retrieves the DOA estimator.

Returns:

DOA estimator instance or None.

abstractmethod reconstruct(R)[source]

Reconstructs the augmented covariance matrix.

Parameters:

R (ndarray) – Sample covariance matrix of the sparse array.

Returns:

Augmented covariance matrix.

Return type:

ndarray

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.

  • **kwargs – Other keyword arguments.

Returns:

A tuple with the following elements.

  • resolved (bool): True 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 (if provided), representing 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 and a search grid is provided.

class doatools.estimation.coarray_reconstruction.SPAEstimator(array, wavelength, lambda_noise: float = 0, doa_estimator=None, search_grid=None, **kwargs)[source]

Bases: CovarianceReconstructionBase

Creates a source location estimator based on Spatial-smoothing based Augmentation (SPA) algorithm.

The SPA algorithm reconstructs a large covariance matrix corresponding to the difference coarray uniform linear array using semi-definite programming (SDP) approach, and then applies subspace-based methods (such as MUSIC) for DOA estimation.

Parameters:

  • array (ArrayDesign) – Array design.

  • wavelength (float) – Wavelength of the carrier wave.

  • search_grid (SearchGrid, optional) – The search grid used to locate the sources. Defaults to None. Not needed for gridless DOA estimators like RootMUSIC1D and ESPRIT.

  • lambda_noise (float, optional) – The noise variance, used for the SPA_noisevar variant. Defaults to 0 (standard SPA).

  • doa_estimator – DOA estimator instance. Defaults to None (RootMUSIC1D).

  • **kwargs – Other keyword arguments.

References

[1] Z. Yang, L. Xie, and C. Zhang, “A Discretization-Free Sparse and Parametric Approach for Linear Array Signal Processing,” IEEE Transactions on Signal Processing, vol. 62, no. 19, pp. 4959-4973, Oct. 2014.

reconstruct(R)[source]

Reconstructs the augmented covariance matrix using SPA algorithm.

Parameters:

R (ndarray) – Sample covariance matrix of the sparse array.

Returns:

Augmented covariance matrix.

Return type:

ndarray

class doatools.estimation.coarray_reconstruction.ANMEstimator(array, wavelength, zeta: float = 0.0, doa_estimator=None, search_grid=None, **kwargs)[source]

Bases: CovarianceReconstructionBase

Creates a source location estimator based on Augmentation via Nuclear-norm Minimization (ANM) algorithm.

The ANM algorithm reconstructs the augmented covariance matrix by solving a nuclear-norm minimization problem, which exploits the low-rank property of the covariance matrix.

Parameters:

  • array (ArrayDesign) – Array design.

  • wavelength (float) – Wavelength of the carrier wave.

  • search_grid (SearchGrid, optional) – The search grid used to locate the sources. Defaults to None. Not needed for gridless DOA estimators like RootMUSIC1D and ESPRIT.

  • zeta (float, optional) – Regularization parameter. Defaults to 0.0.

  • max_workers (int, optional) – Maximum number of workers for parallel processing. Defaults to 1.

  • doa_estimator – DOA estimator instance. Defaults to None (RootMUSIC1D).

  • **kwargs – Other keyword arguments.

References

[1] C. Zhou, Y. Gu, X. Fan, Z. Shi, G. Mao, and Y. D. Zhang, “Direction-of-Arrival Estimation for Coprime Array via Virtual Array Interpolation,” IEEE Transactions on Signal Processing, vol. 66, no. 22, pp. 5956-5971, Nov. 2018. [2] X. Wu, W.-P. Zhu, and J. Yan, “A Toeplitz Covariance Matrix Reconstruction Approach for Direction-of-Arrival Estimation,” IEEE Transactions on Vehicular Technology, vol. 66, no. 9, pp. 8223-8237, Sept. 2017.

reconstruct(R)[source]

Reconstructs the augmented covariance matrix using ANM algorithm.

Parameters:

R (ndarray) – Sample covariance matrix of the sparse array.

Returns:

Augmented covariance matrix.

Return type:

ndarray

class doatools.estimation.coarray_reconstruction.StructCovMLEEstimator(array, wavelength, epsilon: float = 0.0001, max_iter: int = 10, lambda_noise: float = None, doa_estimator=None, search_grid=None, **kwargs)[source]

Bases: CovarianceReconstructionBase

Creates a source location estimator based on Structured Covariance Maximum Likelihood Estimation (StructCovMLE) algorithm.

The StructCovMLE algorithm recovers the Toeplitz covariance matrix of a ULA from sparse array data using an iterative optimization approach.

Parameters:

  • array (ArrayDesign) – Array design.

  • wavelength (float) – Wavelength of the carrier wave.

  • search_grid (SearchGrid, optional) – The search grid used to locate the sources. Defaults to None. Not needed for gridless DOA estimators like RootMUSIC1D and ESPRIT.

  • epsilon (float, optional) – Relative change threshold for convergence. Defaults to 1e-4.

  • max_iter (int, optional) – Maximum number of iterations. Defaults to 10.

  • lambda_noise (float, optional) – Noise variance for noise-aware variant.

  • doa_estimator – DOA estimator instance. Defaults to None (RootMUSIC1D).

  • **kwargs – Other keyword arguments.

References

[1] R. R. Pote and B. D. Rao, “Maximum Likelihood-Based Gridless DoA Estimation Using Structured Covariance Matrix Recovery and SBL With Grid Refinement,” IEEE Transactions on Signal Processing, vol. 71, pp. 802-815, 2023.

reconstruct(R)[source]

Reconstructs the augmented covariance matrix using StructCovMLE algorithm.

Parameters:

R (ndarray) – Sample covariance matrix of the sparse array.

Returns:

Augmented covariance matrix.

Return type:

ndarray

class doatools.estimation.coarray_reconstruction.WassersteinEstimator(array, wavelength, use_gradient: bool = False, mu: float = 0.01, lr: float = 0.1, max_iter: int = 500, tol: float = 1e-07, verbose: bool = False, doa_estimator=None, search_grid=None, **kwargs)[source]

Bases: CovarianceReconstructionBase

Creates a source location estimator based on Wasserstein algorithm.

The Wasserstein algorithm estimates the Toeplitz covariance matrix of a Uniform Linear Array (ULA) from the sample covariance matrix of a sparse linear array using SDP.

Parameters:

  • array (ArrayDesign) – Array design.

  • wavelength (float) – Wavelength of the carrier wave.

  • search_grid (SearchGrid, optional) – The search grid used to locate the sources. Defaults to None. Not needed for gridless DOA estimators like RootMUSIC1D and ESPRIT.

  • use_gradient (bool, optional) – Whether to use the gradient-based implementation. Defaults to False.

  • mu (float, optional) – log-barrier coefficient for gradient-based implementation. Defaults to 1e-2.

  • lr (float, optional) – Learning rate for gradient-based implementation. Defaults to 1e-1.

  • max_iter (int, optional) – Maximum number of iterations for gradient-based implementation. Defaults to 500.

  • tol (float, optional) – Convergence threshold for gradient-based implementation. Defaults to 1e-7.

  • verbose (bool, optional) – Whether to print verbose output for gradient-based implementation. Defaults to False.

  • doa_estimator – DOA estimator instance. Defaults to None (RootMUSIC1D).

  • **kwargs – Other keyword arguments.

References

[1] M. Wang, Z. Zhang, and A. Nehorai, “Grid-Less DOA Estimation Using Sparse Linear Arrays Based on Wasserstein Distance,” IEEE Signal Processing Letters, vol. 26, no. 6, pp. 838-842, June 2019.

reconstruct(R)[source]

Reconstructs the augmented covariance matrix using Wasserstein algorithm.

Parameters:

R (ndarray) – Sample covariance matrix of the sparse array.

Returns:

Augmented covariance matrix.

Return type:

ndarray