Beamformer#

Beamforming is split into the prototype classes TransmitBeamformer and ReceiveBeamformer for beamforming operations during signal transmission and reception, respectively. They are both derived from the base BeamformerBase. This is due to the fact that some beamforming algorithms may be exclusive to transmission or reception use-cases. Should a beamformer be applicable during both transmission and reception both prototypes can be inherited. An example for such an implementation is the Conventional beamformer.

class FocusMode(value)#

Bases: SerializableEnum

The focus mode of the beamformer.

SPHERICAL = 0#: Focus points in spherical coordinates, i.e. azimuth and zenith angles in radians.

HORIZONTAL = 1#: Focus points in horizontal coordinates, i.e. azimuth and elevation angles in radians.

CARTESIAN = 2#: Focus points in Cartesian coordinates, i.e. xyz in m.

DEVICE = 3#: Focus points considering peer devices.

class OT#

Type of operator.

alias of TypeVar(‘OT’, bound=Operator)

class BeamformerBase(operator=None)#

Bases: ABC, Generic[OT]

Base class for all beam steering precodings.

Args:

operator (OT, optional):: The operator this beamformer is attached to. By default, the beamformer is considered floating.

property operator: OT | None#

The operator this beamformer is assigned to.

Returns:: Handle to the operator. None if the beamformer is considered floating.

class TransmitBeamformer(operator=None)#

Bases: BeamformerBase[Transmitter], TransmitStreamEncoder, ABC

Base class for beam steering precodings during signal transmissions.

Args:

operator (Transmitter, optional):: The operator this beamformer is attached to. By default, the beamformer is considered floating.

abstract property num_transmit_input_streams: int#

Number of input streams required by this beamformer.

Returns:: Number of input streams.

abstract property num_transmit_output_streams: int#

Number of output streams generated by this beamformer.

Returns:: Number of output streams.

abstract property num_transmit_focus_angles: int#

Number of required transmit focus angles.

Returns:: Number of focus angles.

encode_streams(streams)#

Encode a signal MIMO stream during transmission.

This operation may modify the number of streams.

Parameters:: streams (Signal) – The signal stream to be encoded.
Return type:: Signal

Returns: The encoded signal stream.

property precoding: Precoding | None#

Access the precoding configuration this precoder is attached to.

Returns:: Handle to the precoding. None if the precoder is considered floating.
Raises:: RuntimeError – If this precoder is currently floating.

property transmit_focus: Tuple[ndarray, FocusMode]#

Focus points of the beamformer during transmission.

Returns:

Numpy array of focus points elevation and azimuth angles
Focus mode

transmit(signal, focus=None)#

Focus a signal model towards a certain target.

Parameters:

signal (Signal) – The signal to be steered.
focus (np.ndarray, optional) – Focus point of the steered signal power.

Return type:

Signal

Returns:

Samples of the focused signal.

class ReceiveBeamformer(operator=None)#

Bases: BeamformerBase[Receiver], ReceiveStreamDecoder, ABC

Base class for beam steering precodings during signal receptions.

The beamformer is characterised by its required number of input streams \(N\), the resulting number of output streams \(M\) and the supported number of focus points \(F\). Considering a beamformer is provided with a matrix of \(T\) baseband samples \(\mathbf{X} \in \mathbb{C}^{N \times T}\), the beamforming process

\[\mathbf{Y} = \mathcal{B}\lbrace \mathbf{X} \rbrace \quad \text{with} \quad \mathbf{Y} \in \mathbb{C}^{M \times T}\]

can generally be described as a function compressing the number of streams while focusing the power towards the angles of interest \(F\).

Args:

operator (Receiver, optional):: The operator this beamformer is attached to. By default, the beamformer is considered floating.

abstract property num_receive_input_streams: int#

Number of input streams required by this beamformer.

Dimension \(N\) of the input sample matrix \(\mathbf{X} \in \mathbb{C}^{N \times T}\).

Returns:: Number of input streams \(N\).

abstract property num_receive_output_streams: int#

Number of output streams generated by this beamformer.

Dimension \(M\) of the output sample matrix \(\mathbf{Y} \in \mathbb{C}^{M \times T}\).

Returns:: Number of output streams \(M\).

abstract property num_receive_focus_angles: int#

Number of required receive focus angles.

Returns:: Number of focus angles \(F\).

decode_streams(streams)#

Encode a signal MIMO stream during signal recepeption.

This operation may modify the number of streams.

Parameters:: streams (Signal) – The signal stream to be decoded.
Return type:: Signal

Returns: The decoded signal stream.

property precoding: Precoding | None#

Access the precoding configuration this precoder is attached to.

Returns:: Handle to the precoding. None if the precoder is considered floating.
Raises:: RuntimeError – If this precoder is currently floating.

abstract _decode(samples, carrier_frequency, angles)#

Decode signal streams for receive beamforming.

This method is called as a subroutine during receive() and probe().

Parameters:

samples (np.ndarray) – Signal samples, first dimension being the number of signal streams \(N\), second the number of samples \(T\).
carrier_frequency (float) – The assumed carrier central frequency of the samples \(f_\mathrm{c}\).
angles (ndarray) – (np.ndarray): Spherical coordinate system angles of arrival in radians. A three-dimensional numpy array with the first dimension representing the number of angles, the second dimension of magnitude number of focus points \(F\), and the third dimension containing the azimuth and zenith angle in radians, respectively.

Return type:

ndarray

Returns:

Stream samples of the focused signal towards all focus points. A three-dimensional numpy array with the first dimension representing the number of focus points, the second dimension the number of returned streams and the third dimension the amount of samples.

property receive_focus: Tuple[ndarray, FocusMode]#

Focus points of the beamformer during reception.

Returns:

Numpy array of focus points elevation and azimuth angles
Focus mode

receive(signal, focus_points=None, focus_mode=FocusMode.SPHERICAL)#

Focus a signal model towards a certain target.

Parameters:

signal (Signal) – The signal to be steered.
focus_points (np.ndarray, optional) – Focus point of the steered signal power. Two-dimensional numpy array with the first dimension representing the number of points and the second dimension representing the point values.
focus_mode (FocusMode, optional) – Type of focus points. By default, spherical coordinates are expected.

Return type:

Signal

Returns:

Signal focused towards the requested focus points.

Raises:

FloatingError – If the operator or operator device are not yet specified.
RuntimeError – If the number of signal streams does not match the number of required input streams.

property probe_focus_points: ndarray#

Default beamformer focus points during probing.

Returns:: The focus points as a three-dimensional numpy array, with the first dimension representing the probe index, the second dimension the point and the third dimension of magnitude two the point azimuth and zenith, respectively.
Raises:: ValueError – On invalid arguments.

probe(signal, focus_points=None)#

Focus a signal model towards certain directions of interest.

Parameters:

signal (Signal) – The signal to be steered.
focus_points (np.ndarray, optional) – Focus point of the steered signal power. Two-dimensional numpy array with the first dimension representing the number of points and the second dimension representing the point values.

Return type:

ndarray

Returns:

plot_receive_pattern(signal=None)#

Visualize the beamformer instance’s receive characteristics.

Parameters:: signal (Signal, optional) – The impinging signal model for which to plot the receive characteristics. By default, a point-source signal at \((\theta=0, \phi=0)\) will be generated.
Return type:: Figure
Returns:: A handle to the created matplotlib figure.

classmethod PlotReceivePattern(array_topology=None, signal=None)#

Visualize the beamformer class’ receive characteristics.

Parameters:

array_topology (Tuple[int, ...], optional) – The sensor array topology. By default, an \(8 \times 8\) uniform mimo matrix is assumed.
signal (Signal, optional) – The impinging signal model for which to plot the receive characteristics. By default, a point-source signal at \((\theta=0, \phi=0)\) will be generated.

Return type:

Figure

Returns:

A handle to the created matplotlib figure.