Modeling source placements

In common direction-of-arrival estimation problems, the sources are assumed to be far-field. We provide two basic types of far-field source placements:

• FarField1DSourcePlacement - Each sources location is represented by a broadside angle and assumed to be within the xy-plane. The broadside angles are measured with respect to linear arrays along the x-axis.
• FarField2DSourcePlacement - Each sources location is represented by a pair of azimuth and elevation angles. The azimuth angles are measured counter-clockwise starting from the x-axis. The elevation angles are measured with respect to the xy-plane.

import numpy as np
import doatools.model as model
# Uniformly place 5 far-field sources within (-pi/3, pi/3)
# Default unit is 'rad'.
sources_1d = model.FarField1DSourcePlacement(
    np.linspace(-np.pi/3, np.pi/3, 5)
)
# Place 3 2D sources by specifying azimuth-elevation pairs.
sources_2d = model.FarField2DSourcePlacement(
    [[-10, 30], [30, 50], [100, 45]],
    unit='deg'
)

API references

class doatools.model.sources.SourcePlacement(locations, units)

Bases: abc.ABC

Represents the placement of several sources.

This the base abstract class and should not be directly instantiated.

__getitem__(key)

Accesses a specific source location or obtains a subset of source placement via slicing.

For instance, sources[i] and sources.locations[i] are equivalent, and sources[:] will return a full copy.

Parameters:key – An integer, slice, or 1D numpy array of indices/boolean masks.

Notes

This is a generic implementation. When key is a scalar, key is treated as an index and normal indexing operation follows. When key is not a scalar, we need to return a new instance with source locations specified by key. First, a shallow copy is made with copy(). Then the shallow copy’s location data are set to the source locations specified by key. Finally, the shallow copy is returned.

size

Retrieves the number of sources.

locations

Retrieves the source locations.

While this property provides read/write access to the underlying ndarray storing the source locations. Modifying the underlying ndarray is discourage because modified values are not checked for validity.

is_far_field

Retrieves whether the source placement is considered far-field.

A far-field source’s distance to a sensor array is defined to be infinity.

units

Retrieves a tuple consisting of units used for each dimension.

valid_ranges

Retrieves the valid ranges for each dimension.

Returns:A tuple of 2-element tuples of min-max pairs. Return type:((min_1, max_1), ..)

as_unit(new_unit)

Creates a copy with the source locations converted to the new unit.

calc_spherical_coords(ref_locations)

Calculates the spherical coordinates relative to reference locations.

Parameters:ref_locations (ndarray) – An M x D matrix storing the Cartesian coordinates (measured in meters), where M is the number of reference locations, and D is the number of dimensions of the coordinates (1, 2, or 3). Returns:A tuple of three M by K matrices containing the ranges, the azimuth angles and the elevation angles, respectively. The (m,k)-th elements from the three matrices form the spherical coordinates for the k-th source relative to the m-th reference location. Return type:tuple

phase_delay_matrix(sensor_locations, wavelength, derivatives=False)

Computes the phase delay matrix.

The phase delay matrix D is an m x k matrix, where D[i,j] is the relative phase difference between the i-th sensor and the j-th source (usually using the first sensor as the reference). By convention, a positive value means that the corresponding signal arrives earlier than the referenced one.

Parameters:

• sensor_locations – An m x d (d = 1, 2, 3) matrix representing the sensor locations using the Cartesian coordinate system.
• wavelength – Wavelength of the carrier wave.
• derivatives – If set to true, also outputs the derivative matrix (or matrices) with respect to the source locations. Default value is False.

Returns:

• When derivatives is False, returns the steering matrix.
• When derivatives is True, returns both the steering matrix and the derivative matrix (or matrices if possible) with a tuple.

Notes

The phase delay matrix is used in constructing the steering matrix. This method is decoupled from the steering matrix method because the phase delays are calculated differently for different types of sources (e.g. far-field vs. near-field).

class doatools.model.sources.FarField1DSourcePlacement(locations, unit='rad')

Bases: doatools.model.sources.SourcePlacement

Creates a far-field 1D source placement.

Far-field 1D sources are placed within the xy-plane and represented by the angles relative to the y-axis (broadside angles for an array placed along the x-axis).

         y
         ^
         |   /
         |  /
         |-/
         |/
---------+---------> x

Parameters:

• locations – A list or 1D numpy array representing the source locations.
• unit (str) – Can be 'rad', 'deg' or 'sin'. 'sin' is a special unit where sine value of the broadside angle is used instead of the broadside angle itself. Default value is 'rad'.

static from_z(z, wavelength, d0, unit='rad')

Creates a far-field 1D source placement from complex roots.

Used in rooting based DOA estimators such as root-MUSIC and ESPRIT.

Parameters:

• z – A ndarray of complex roots.
• wavelength (float) – Wavelength of the carrier wave.
• d0 (float) – Inter-element spacing of the uniform linear array.
• unit (str) – Can be 'rad', 'deg' or 'sin'. Default value is 'rad'.

Returns:

An instance of FarField1DSourcePlacement.

is_far_field

Retrieves whether the source placement is considered far-field.

A far-field source’s distance to a sensor array is defined to be infinity.

valid_ranges

Retrieves the valid ranges for each dimension.

Returns:A tuple of 2-element tuples of min-max pairs. Return type:((min_1, max_1), ..)

as_unit(new_unit)

Creates a copy with the source locations converted to the new unit.

calc_spherical_coords(ref_locations)

Calculates the spherical coordinates relative to reference locations.

Parameters:ref_locations (ndarray) – An M x D matrix storing the Cartesian coordinates (measured in meters), where M is the number of reference locations, and D is the number of dimensions of the coordinates (1, 2, or 3). Returns:A tuple of three M by K matrices containing the ranges, the azimuth angles and the elevation angles, respectively. The (m,k)-th elements from the three matrices form the spherical coordinates for the k-th source relative to the m-th reference location. Return type:tuple

phase_delay_matrix(sensor_locations, wavelength, derivatives=False)

Computes the phase delay matrix for 1D far-field sources.

class doatools.model.sources.FarField2DSourcePlacement(locations, unit='rad')

Bases: doatools.model.sources.SourcePlacement

Creates a far-field 2D source placement.

Far-field 2D sources are represented by azimuth and elevation angles. The azimuth angles start from the x-axis and the elevation angles are measured with respect to the xy-plane.

Parameters:

• locations – An k x 2 numpy array representing the source locations, where k is the number of sources, and the k-th row consists of the azimuth and elevation angles of the k-th source. Should never be modified after creation.
• unit – Can be 'rad' or 'deg'. Default value is 'rad'.

is_far_field

Retrieves whether the source placement is considered far-field.

A far-field source’s distance to a sensor array is defined to be infinity.

valid_ranges

Retrieves the valid ranges for each dimension.

Returns:A tuple of 2-element tuples of min-max pairs. Return type:((min_1, max_1), ..)

as_unit(new_unit)

Creates a copy with the source locations converted to the new unit.

calc_spherical_coords(ref_locations)

Calculates the spherical coordinates relative to reference locations.

Parameters:ref_locations (ndarray) – An M x D matrix storing the Cartesian coordinates (measured in meters), where M is the number of reference locations, and D is the number of dimensions of the coordinates (1, 2, or 3). Returns:A tuple of three M by K matrices containing the ranges, the azimuth angles and the elevation angles, respectively. The (m,k)-th elements from the three matrices form the spherical coordinates for the k-th source relative to the m-th reference location. Return type:tuple

phase_delay_matrix(sensor_locations, wavelength, derivatives=False)

Computes the phase delay matrix for 2D far-field sources.

class doatools.model.sources.NearField2DSourcePlacement(locations)

Bases: doatools.model.sources.SourcePlacement

Creates a near-field 2D source placement.

Parameters:locations – An k x 2 numpy array representing the source locations, where k is the number of sources and the k-th row consists of the x and y coordinates of the k-th source. Should never be modified after creation.

is_far_field

Retrieves whether the source placement is considered far-field.

A far-field source’s distance to a sensor array is defined to be infinity.

valid_ranges

Retrieves the valid ranges for each dimension.

Returns:A tuple of 2-element tuples of min-max pairs. Return type:((min_1, max_1), ..)

as_unit(new_unit)

Creates a copy with the source locations converted to the new unit.

calc_spherical_coords(ref_locations)

Calculates the spherical coordinates relative to reference locations.

Parameters:ref_locations (ndarray) – An M x D matrix storing the Cartesian coordinates (measured in meters), where M is the number of reference locations, and D is the number of dimensions of the coordinates (1, 2, or 3). Returns:A tuple of three M by K matrices containing the ranges, the azimuth angles and the elevation angles, respectively. The (m,k)-th elements from the three matrices form the spherical coordinates for the k-th source relative to the m-th reference location. Return type:tuple

phase_delay_matrix(sensor_locations, wavelength, derivatives=False)

Computes the phase delay matrix for 2D near-field sources.