Beamformer

Beamforming is split into the prototype classes TransmitBeamformer and ReceiveBeamformer for beamforming operations during signal transmission and reception, respectively. 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 BeamFocus

Bases: ABC, Serializable

Single focus point of a beamformer.

abstract copy()

Create a copy of this focus point.

Return type:

TypeVar(FT, bound= BeamFocus)

Returns:

A copy of this focus point.

abstract spherical_angles(device)

Compute azimuth and zenith angles in radians, towards a beam is focused.

Parameters:

device (State) – State of the device the beamformer is operating on.

Return type:

ndarray

Returns:

Numpy vector with the azimuth and zenith angles in radians from the device’s point of view.

property_blacklist = {'beamformer', 'spherical_angles'}

class CoordinateFocus(coordinates, reference='local')

Bases: BeamFocus

Focus the beamformer towards a certain Cartesian coordinate.

Parameters:

• coordinates (ndarray | Direction) – Cartesian coordinates in m.

• reference (Literal['global', 'local']) – Reference frame of the coordinates.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

CoordinateFocus

Returns:

The deserialized object.

copy()

Create a copy of this focus point.

Return type:

CoordinateFocus

Returns:

A copy of this focus point.

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

spherical_angles(device)

Compute azimuth and zenith angles in radians, towards a beam is focused.

Parameters:

device (State) – State of the device the beamformer is operating on.

Return type:

ndarray

Returns:

Numpy vector with the azimuth and zenith angles in radians from the device’s point of view.

property coordinates: ndarray

Cartesian coordinates in m.

property reference: Literal['global', 'local']

Reference frame of the coordinates.

class FT

Type of beam focus.

alias of TypeVar(‘FT’, bound=BeamFocus)

class OT

Type of operator.

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

class ReceiveBeamformer

Bases: ReceiveStreamDecoder

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\).

abstract _decode(samples, carrier_frequency, angles, array)

Decode signal streams for receive beamforming.

This method is called as a subroutine during decode_streams and probe.

Parameters:

• samples (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) – 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.

• array (AntennaArrayState) – The assumed antenna array.

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.

decode_streams(streams, num_output_streams, device, focus=None)

Decode a MIMO signal for receive beamforming.

Wrapper around _decode() to decode a signal for receive beamforming. Compliant with the ReceiveStreamDecoder interface.

Parameters:

• streams (Signal) – The signal to be decoded.

• num_output_streams (int) – The number of desired output streams.

• device (ReceiveState) – State of the device this beamformer is operating on.

• focus (Union[BeamFocus, Sequence[BeamFocus], None]) – Focus points of the steered signal power. Must either be a single focus point or a sequence of focus points, depending on num_receive_focus_points. If not provided, the beamformer’s default receive_focus is assumed.

Raises:

ValueError –

• If the number of provided focus points does not match the beamformer requirements.

Return type:

Signal

Returns: The decoded signal.

probe(signal, device, focus_points=None)

Focus a signal model towards certain directions of interest.

Parameters:

• signal (Signal) – The signal to be steered.

• device (ReceiveState) – State of the device this beamformer is operating on.

• focus_points (ndarray | None) – 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:

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.

abstract property num_receive_focus_points: int

Number of required receive focus points.

If this is \(1\), the beamformer is considered to be a single focus point beamformer and receive_focus will return a single focus point. Otherwise, the beamformer is considered a multi focus point beamformer and receive_focus will return a Sequence of focus points.

Returns: Number of focus points.

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.

property receive_focus: BeamFocus | Sequence[BeamFocus]

Focus points of the beamformer during reception.

Depending on num_receive_focus_points this is either a single focus point or a Sequence of points.

Raises:

ValueError – If the provided number of focus points does not match the number of required focus points.

class SphericalFocus(angles: ndarray)

class SphericalFocus(azimuth: float, zenith: float)

Bases: BeamFocus

Focus point in spherical coordinates.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

SphericalFocus

Returns:

The deserialized object.

copy()

Create a copy of this focus point.

Return type:

SphericalFocus

Returns:

A copy of this focus point.

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

spherical_angles(device)

Compute azimuth and zenith angles in radians, towards a beam is focused.

Parameters:

device (State) – State of the device the beamformer is operating on.

Return type:

ndarray

Returns:

Numpy vector with the azimuth and zenith angles in radians from the device’s point of view.

property angles: ndarray

Spherical azimuth and zenith angles in radians.

class TransmitBeamformer

Bases: TransmitStreamEncoder

Base class for beam steering precodings during signal transmissions.

abstract _encode(samples, carrier_frequency, focus_angles, array)

Encode signal streams for transmit beamforming.

Parameters:

• samples (ndarray) – Signal samples, first dimension being the number of transmit antennas, second the number of samples.

• carrier_frequency (float) – The assumed central carrier frequency of the samples generated RF signal after mixing in Hz.

• focus_angles (ndarray) – Focused angles of departure in radians. Two-dimensional numpy array with the first dimension representing the number of focus points and the second dimension of magnitude two being the azimuth and elevation angles, respectively.

• array (AntennaArrayState) – The assumed antenna array.

Return type:

ndarray

Returns:

The encoded signal samples. Two-dimensional complex-valued numpy array with the first dimension representing the number of transmit antennas streams and the second dimension the number of samples.

encode_streams(streams, num_output_streams, device, focus=None)

Encode a MIMO signal for transmit beamforming.

Wrapper around _encode to encode a signal for transmit beamforming. Compliant with the TransmitStreamEncoder interface.

Parameters:

• streams (Signal) – The signal to be encoded.

• num_output_streams (int) – The number of desired output streams.

• device (TransmitState) – State of the device this beamformer is operating on.

• focus (Union[BeamFocus, Sequence[BeamFocus], None]) – Focus points of the steered signal power. Must either be a single focus point or a sequence of focus points, depending on num_transmit_focus_points. If not provided, the beamformer’s default transmit_focus is assumed.

Raises:

• ValueError – If the number of provided signal streams does not match the beamformer requirements.

• ValueError – If the number of provided focus points does not match the beamformer requirements.

Return type:

Signal

Returns: The encoded signal.

abstract property num_transmit_focus_points: int

Number of required transmit focus points.

If this is \(1\), the beamformer is considered to be a single focus point beamformer and transmit_focus will return a single focus point. Otherwise, the beamformer is considered a multi focus point beamformer and transmit_focus will return a Sequence of focus points.

property transmit_focus: BeamFocus | Sequence[BeamFocus]

Focus points of the beamformer during transmission.

Depending on num_transmit_focus_points this is either a single focus point or a Sequence of points.

Raises:

ValueError – If the provided number of focus points does not match the number of required focus points.