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 BeamFocus[source]#

Bases: ABC, Serializable

Single focus point of a beamformer.

abstract copy()[source]#

Create a copy of this focus point.

Return type:: TypeVar(FT, bound= BeamFocus)
Returns:: A copy of this focus point.

property beamformer: BeamformerBase | None#: Beamformer this focus point is assigned to.

abstract property spherical_angles: ndarray#: Azimuth and zenith angles in radians, towards which the beam is focused in spherical coordinates.

class BeamformerBase(operator=None)[source]#

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 CoordinateFocus(coordinates, reference='local')[source]#

Bases: BeamFocus

Focus the beamformer towards a certain Cartesian coordinate.

Parameters:

coordinates (numpy.ndarray) – Cartesian coordinates in m.
reference (str, optional) – Reference frame of the coordinates.

copy()[source]#

Create a copy of this focus point.

Return type:: CoordinateFocus
Returns:: A copy of this focus point.

property coordinates: ndarray#: Cartesian coordinates in m.

property reference: Literal['global', 'local']#: Reference frame of the coordinates.

property spherical_angles: ndarray#: Azimuth and zenith angles in radians, towards which the beam is focused in spherical coordinates.

class DeviceFocus(device)[source]#

Bases: BeamFocus

Focus point targeting a device.

Parameters:: device (Device) – Device focused by the beamformer.

copy()[source]#

Create a copy of this focus point.

Return type:: DeviceFocus
Returns:: A copy of this focus point.

property device: Device#: Device focused by the beamformer.

property spherical_angles: ndarray#: Azimuth and zenith angles in radians, towards which the beam is focused in spherical 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(operator=None)[source]#

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 _decode(samples, carrier_frequency, angles, array)[source]#

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 (numpy.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 (AntennaArray) – 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)[source]#

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.

probe(signal, focus_points=None)[source]#

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:

receive(signal, focus=None, array=None)[source]#

Focus a signal model towards a certain target.

Parameters:

signal (Signal) – The signal to be steered.
focus (BeamFocus | Sequence[BeamFocus], optional) – Focus of the steered signal power. If not provided, the beamformer’s default receive_focus is used.
array (AntennaArray, optional) – Antenna array assumed used for steering. If not specified, the operator’s antenna array is used.

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.
ValueError – If the number of focus points does not match the number of required focus points.

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.

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

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 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)[source]#

class SphericalFocus(azimuth: float, zenith: float)

Bases: BeamFocus

Focus point in spherical coordinates.

copy()[source]#

Create a copy of this focus point.

Return type:: SphericalFocus
Returns:: A copy of this focus point.

property angles: ndarray#: Spherical azimuth and zenith angles in radians.

property spherical_angles: ndarray#: Azimuth and zenith angles in radians, towards which the beam is focused in spherical coordinates.

class TransmitBeamformer(operator=None)[source]#

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.

encode_streams(streams)[source]#

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.

transmit(signal, focus=None, array=None)[source]#

Focus a signal model towards a certain target.

Parameters:

signal (Signal) – The signal to be steered.
focus (BeamFocus | Sequence[BeamFocus], optional) – Focus points of the steered signal power. If None, the beamformer’s default transmit_focus is used.
array (AntennaArray, optional) – Antenna array assumed used for steering. If None, the operator’s antenna array is used.

Return type:

Signal

Returns:

Samples of the focused signal.

Raises:

RuntimeError – 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.
ValueError – If the number of focus points does not match the number of required focus points.

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.

Returns: Number of focus points.

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.

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: 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.