Modeling array perturbations

API references

class doatools.model.perturbations.ArrayPerturbation(params, known=False)[source]

Bases: object

Creates an array perturbation.

In practice, sensor arrays are not perfectly calibrated and various array imperfections exist. These imperfections/perturbations are generally modelled with parameters independent of the sources.

Parameters:
  • params – Parameters associated with this perturbation. Usually an ndarray.
  • known (bool) – Specifies whether this perturbation is known in prior. Default value is False.
params

Retrieves the parameters used to model this perturbation.

is_known

Retrieves whether this perturbation is known.

is_applicable_to(array)[source]

Checks if this perturbation is applicable to the given array.

Parameters:array (ArrayDesign) – Array design.
Returns:A two-element tuple of the format (bool, str). The first element is a boolean indicating whether this perturbation is applicable. The second element is a string describing why this perturbation is not applicable.
Return type:tuple
perturb_sensor_locations(locations)[source]

Perturbs the given sensor locations.

Parameters:locations (ndarray) – A matrix containing the locations of array elements/sensors, where the \(i\)-th row consists of the Cartesian coordinates of the \(i\)-th array element/sensor.

Notes

The number of dimensions of the sensor locations and number of dimensions of the perturbations do not need to match. It is perfectly fine to apply 3D location errors to 1D arrays.

perturb_steering_matrix(A, DA)[source]

Perturbs the given steering matrix (and derivative matrices).

Given the steering matrix

\[\mathbf{A} = \begin{bmatrix} \mathbf{a}(\mathbf{\theta}_1) & \mathbf{a}(\mathbf{\theta}_2) & \cdots & \mathbf{a}(\mathbf{\theta}_K) \end{bmatrix},\]

The d-th derivative matrix is computed as

\[\dot{\mathbf{A}}_d = \begin{bmatrix} \frac{\partial \mathbf{a}(\mathbf{\theta}_1)}{\partial \theta_{1d}} & \frac{\partial \mathbf{a}(\mathbf{\theta}_2)}{\partial \theta_{2d}} & \cdots & \frac{\partial \mathbf{a}(\mathbf{\theta}_K)}{\partial \theta_{Kd}} \end{bmatrix},\]

where \(\theta_{kd}\) is the \(d\)-th parameter of the \(k\)-th source location.

Denote the perturbation as a function \(C(\cdots)\). The perturbed steering matrix can then be expressed as

\[\tilde{\mathbf{A}} = \begin{bmatrix} C(\mathbf{a}(\mathbf{\theta}_1)) & C(\mathbf{a}(\mathbf{\theta}_2)) & \cdots & C(\mathbf{a}(\mathbf{\theta}_K)) \end{bmatrix}.\]

The \(d\)-th derivative matrix should be computed as

\[\dot{\tilde{\mathbf{A}}}_d = \begin{bmatrix} \frac{\partial C(\mathbf{a}(\mathbf{\theta}_1))}{\partial \theta_{1d}} & \frac{\partial C(\mathbf{a}(\mathbf{\theta}_2))}{\partial \theta_{2d}} & \cdots & \frac{\partial C(\mathbf{a}(\mathbf{\theta}_K))}{\partial \theta_{Kd}} \end{bmatrix}.\]
Parameters:
  • A (ndarray) – Steering matrix input.
  • DA (list) – A list of derivative matrices. If this list is empty, there is no need to consider the derivative matrices.
Returns:

A two element tuple. The first element is the perturbed steering matrix. The second element is a list of perturbed derivative matrices. If DA is an empty list, the second element should also be an empty list.
Return type:

tuple
class doatools.model.perturbations.LocationErrors(location_errors, known=False)[source]

Bases: doatools.model.perturbations.ArrayPerturbation

Creates an array perturbation that models sensor location errors.

Parameters:
  • location_errors – Location error matrix.
  • known (bool) – Specifies whether this perturbation is known in prior. Default value is False.
is_applicable_to(array)[source]

Checks if this perturbation is applicable to the given array.

Parameters:array (ArrayDesign) – Array design.
Returns:A two-element tuple of the format (bool, str). The first element is a boolean indicating whether this perturbation is applicable. The second element is a string describing why this perturbation is not applicable.
Return type:tuple
perturb_sensor_locations(locations)[source]

Perturbs the given sensor locations.

Parameters:locations (ndarray) – A matrix containing the locations of array elements/sensors, where the \(i\)-th row consists of the Cartesian coordinates of the \(i\)-th array element/sensor.

Notes

The number of dimensions of the sensor locations and number of dimensions of the perturbations do not need to match. It is perfectly fine to apply 3D location errors to 1D arrays.

class doatools.model.perturbations.GainErrors(gain_errors, known=False)[source]

Bases: doatools.model.perturbations.ArrayPerturbation

Creates an array perturbation that models gain errors.

Parameters:
  • gain_errors – A real vector storing the gain errors. The values are relative. For instance, a gain error of -0.1 means the actual gain is 0.9.
  • known (bool) – Specifies whether this perturbation is known in prior. Default value is False.
is_applicable_to(array)[source]

Checks if this perturbation is applicable to the given array.

Parameters:array (ArrayDesign) – Array design.
Returns:A two-element tuple of the format (bool, str). The first element is a boolean indicating whether this perturbation is applicable. The second element is a string describing why this perturbation is not applicable.
Return type:tuple
perturb_steering_matrix(A, DA)[source]

Perturbs the steering matrix with gain errors.

Given the gain error vector, \(\mathbf{g}\), the perturbed steering matrix is computed as

\[\tilde{\mathbf{A}} = (\mathbf{g} + \mathbf{I}) \mathbf{A}.\]

The derivative matrices are computed as

\[\dot{\tilde{\mathbf{A}}}_i = (\mathbf{g} + \mathbf{I}) \dot{\mathbf{A}}_i.\]
Parameters:
  • A (ndarray) – Steering matrix input.
  • DA (list) – A list of derivative matrices. If this list is empty, there is no need to consider the derivative matrices.
Returns:

A two element tuple. The first element is the perturbed steering matrix. The second element is a list of perturbed derivative matrices. If DA is an empty list, the second element should also be an empty list.
Return type:

tuple
class doatools.model.perturbations.PhaseErrors(phase_errors, known=False)[source]

Bases: doatools.model.perturbations.ArrayPerturbation

Creates an array perturbation that models phase errors.

Parameters:
  • phase_errors – A real vector storing the phase errors. The values are in radians.
  • known (bool) – Specifies whether this perturbation is known in prior. Default value is False.
is_applicable_to(array)[source]

Checks if this perturbation is applicable to the given array.

Parameters:array (ArrayDesign) – Array design.
Returns:A two-element tuple of the format (bool, str). The first element is a boolean indicating whether this perturbation is applicable. The second element is a string describing why this perturbation is not applicable.
Return type:tuple
perturb_steering_matrix(A, DA)[source]

Perturbs the steering matrix with phase errors.

Given the phase error vector, \(\mathbf{\phi}\), the perturbed steering matrix is computed as

\[\tilde{\mathbf{A}} = \mathrm{diag}(\exp(j\mathrm{\phi})) \mathbf{A},\]

where the \(\exp(\cdot)\) denote element-wise exponentiation.

The derivative matrices are computed as

\[\dot{\tilde{\mathbf{A}}}_i = \mathrm{diag}(\exp(j\mathrm{\phi})) \dot{\mathbf{A}}_i.\]
Parameters:
  • A (ndarray) – Steering matrix input.
  • DA (list) – A list of derivative matrices. If this list is empty, there is no need to consider the derivative matrices.
Returns:

A two element tuple. The first element is the perturbed steering matrix. The second element is a list of perturbed derivative matrices. If DA is an empty list, the second element should also be an empty list.
Return type:

tuple
class doatools.model.perturbations.MutualCoupling(C, known=False)[source]

Bases: doatools.model.perturbations.ArrayPerturbation

Creates an array perturbation that models mutual coupling.

Parameters:
  • C – Mutual coupling matrix.
  • known (bool) – Specifies whether this perturbation is known in prior. Default value is False.
is_applicable_to(array)[source]

Checks if this perturbation is applicable to the given array.

Parameters:array (ArrayDesign) – Array design.
Returns:A two-element tuple of the format (bool, str). The first element is a boolean indicating whether this perturbation is applicable. The second element is a string describing why this perturbation is not applicable.
Return type:tuple
perturb_steering_matrix(A, DA)[source]

Perturbs the steering matrix with mutual coupling.

Given the mutual coupling matrix, \(\mathbf{C}\), the perturbed steering matrix is computed as

\[\tilde{\mathbf{A}} = \mathbf{C} \mathbf{A}.\]

The derivative matrices are computed as

\[\dot{\tilde{\mathbf{A}}}_i = \mathbf{C} \dot{\mathbf{A}}_i.\]
Parameters:
  • A (ndarray) – Steering matrix input.
  • DA (list) – A list of derivative matrices. If this list is empty, there is no need to consider the derivative matrices.
Returns:

A two element tuple. The first element is the perturbed steering matrix. The second element is a list of perturbed derivative matrices. If DA is an empty list, the second element should also be an empty list.
Return type:

tuple