Physical Device¶

class PhysicalDevice(max_receive_delay=0.0, noise_power=None, leakage_calibration=None, delay_calibration=None, antenna_calibration=None, adaptive_sampling=False, lowpass_filter=False, lowpass_bandwidth=0.0, transmit_dsp=None, receive_dsp=None, transmit_encoding=None, receive_decoding=None, power=1.0, pose=None, seed=None)[source]¶

Bases: Generic[PDST], Device[PDST]

Base representing any device controlling real hardware.

Parameters:

max_receive_delay (float) – Maximum expected delay during siganl reception in seconds. Zero by default.
noise_power (ndarray | None) – Assumed power of the hardware noise at the device’s receive chains.
leakage_calibration (LeakageCalibrationBase | None) – The leakage calibration routine to apply to received signals. If not provided, defaults to the NoLeakageCalibration stub routine.
delay_calibration (DelayCalibrationBase | None) – The delay calibration routine to apply to received signals. If not provided, defaults to the NoDelayCalibration stub routine.
antenna_calibration (AntennaCalibration | None) – The antenna calibration routine to apply to transmitted and received signals. If not provided, defaults to the NoAntennaCalibration stub routine.
adaptive_sampling (bool) – Adapt the assumed sampling rate to the device’s actual sampling rate. Disabled by default.
lowpass_filter (bool) – Apply a digital lowpass filter to the received base-band samples. Disabled by default.
lowpass_bandwidth (float) – Digital lowpass filter bandwidth in Hz. Only relevant if the lowpass filter is enabled. Zero by default.

estimate_noise_power(num_samples=1000, cache=True)[source]¶

Estimate the power of the noise floor within the hardware.

Receives num_samples without any transmissions and estimates the power over them. Note that any interference in this case will be interpreted as noise.

Parameters:

num_samples (int) – Number of received samples. 1000 by default.
cache (bool) – If enabled, the PhysicalDevice.noise_power() property will be updated.

Return type:

ndarray

Returns:

Estimated noise power at each respective receive channel, i.e. the variance of the unbiased received samples.

load_calibration(path, backend=SerializationBackend.HDF)[source]¶

Load the calibration file from the hard drive.

Parameters:

path (str) – Path from which to load the calibration.
backend (SerializationBackend) – Serialization backend to use. HDF by default.

Return type:

None

process_input(impinging_signals=None, state=None)[source]¶

Process input signals impinging onto this device.

Parameters:

impinging_signals (DeviceInput | Signal | Sequence[Signal] | None) – The samples to be processed by the device.
state (Optional[TypeVar(PDST, bound= PhysicalDeviceState)]) – Device state to be used for the processing. If not provided, query the current device state.

Return type:

ProcessedDeviceInput

Returns: The processed device input information.

Raises:: ValueError – If the number of signal streams does not match the device configuration expectations.

receive(impinging_signals=None, state=None, notify=True)[source]¶

Receive over this physical device.

Internally calls PhysicalDevice.process_input() and Device.receive_operators.

Parameters:

impinging_signals (DeviceInput | Signal | Sequence[Signal] | None) – The samples to be processed by the device. If not specified, the device will download the samples directly from the represented hardware.
state (Optional[TypeVar(PDST, bound= PhysicalDeviceState)]) – Device state to be used for the processing. If not provided, query the current device state by calling state.
notify (bool) – Notify all registered callbacks within the involved DSP algorithms. Enabled by default.

Return type:

DeviceReception

Returns: The received device information.

save_calibration(path, backend=SerializationBackend.HDF)[source]¶

Save the calibration file to the hard drive.

Parameters:

path (str) – Path under which the file should be stored.
backend (SerializationBackend) – Serialization backend to use. HDF by default.

Return type:

None

serialize(process)[source]¶

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

transmit(state=None, notify=True)[source]¶

Transmit over this device.

Parameters:

state (Optional[TypeVar(PDST, bound= PhysicalDeviceState)]) – Device state to be used for the transmission. If not provided, query the current device state by calling state.
notify (bool) – Notify the transmitter’s callbacks about the generated transmission. Enabled by default.

Return type:

DeviceTransmission

Returns: Information transmitted by this device.

abstract trigger()[source]¶

Trigger the device.

Return type:: None

trigger_direct(signal, calibrate=True)[source]¶

Trigger a direct transmission and reception.

Bypasses the operator abstraction layer and directly transmits the given signal.

Parameters:

signal (Signal) – The signal to be transmitted.
calibrate (bool) – If enabled, the signal will be calibrated using the device’s leakage calibration. Enabled by default.

Return type:

Signal

Returns: The received signal.

Raises:: ValueError – If the signal’s carrier frequency or sampling rate does not match the device’s.

property adaptive_sampling: bool¶

Allow adaptive sampling during transmission.

Returns: Enabled flag.

property antenna_calibration: AntennaCalibration¶

Antenna calibration routine to apply to transmitted and received signals.

Returns: Handle to the antenna calibration routine.

property delay_calibration: DelayCalibrationBase¶

Delay calibration routine to apply to received signals.

Returns:: Handle to the delay calibration routine.

property leakage_calibration: LeakageCalibrationBase¶

Leakage calibration routine to apply to received signals.

Returns:: Handle to the calibration routine.

property lowpass_bandwidth: float¶

Digital lowpass filter bandwidth

Returns:: Filter bandwidth in Hz. Zero if the device should determine the bandwidth automatically.
Raises:: ValueError – For negative bandwidths.

property lowpass_filter: bool¶

Apply a digital lowpass filter to the received base-band samples.

Returns: Enabled flag.

property max_receive_delay: float¶

Maximum expected delay during signal reception.

The expected delay will be appended as additional samples to the expected frame length during reception.

Returns:: The expected receive delay in seconds.
Raises:: ValueError – If the delay is smaller than zero.

abstract property max_sampling_rate: float¶

Maximal device sampling rate.

Returns: The samplin rate in Hz.

property noise_power: ndarray | None¶

Assumed hardware noise power at the device’s receive chains.

Returns:: Numpy array indicating the noise power at each receive chain. None if unknown or not specified.
Raises:: ValueError – If any power is negative.

property velocity: ndarray¶

class Calibration(device=None)[source]¶

Bases: ABC, Serializable

Abstract basse class of all calibration classes.

classmethod Load(path, backend=SerializationBackend.HDF)[source]¶

Load the calibration file from the hard drive.

Parameters:

path (str) – Path from which to load the calibration.
backend (SerializationBackend) – Serialization backend to use. HDF by default.

Return type:

TypeVar(CT, bound= Calibration)

save(path, backend=SerializationBackend.HDF)[source]¶

Save the calibration file to the hard drive.

Parameters:

path (str) – Path under which the file should be stored.
backend (SerializationBackend) – Serialization backend to use. HDF by default.

Return type:

None

property device: PhysicalDevice | None¶

hdf_group_name = 'calibration'¶: Group name of the calibration in the HDF save file.

class PhysicalDeviceState(device_id, timestamp, pose, velocity, carrier_frequency, sampling_rate, num_digital_transmit_ports, num_digital_receive_ports, antennas)[source]¶

Bases: DeviceState

State of a physical device.

Parameters:

device_id (int) – Unique identifier of the device this state represents.
timestamp (float) – Time stamp of the device state.
pose (Transformation) – Pose of the device with respect to the global coordinate system.
velocity (ndarray) – Velocity of the device in m/s.
carrier_frequency (float) – Carrier frequency of the device in Hz.
sampling_rate (float) – Sampling rate of the device in Hz.
num_digital_transmit_ports (int) – Number of digital transmit streams feeding into the device’s signal encoding layer. This is the number of streams expected to be generated by transmit DSP algorithms by default.
num_digital_receive_ports (int) – Number of digital receive streams emerging from the device’s signal decoding layer. This the number of streams expected to be feeding into receive DSP algorithms by default.
antennas (AntennaArrayState) – State of the device’s antenna array.

class PDT¶

Type variable for PhysicalDevice and its subclasses.

alias of TypeVar(‘PDT’, bound=PhysicalDevice)

class CT¶

Type variable for Calibration and its subclasses.

alias of TypeVar(‘CT’, bound=Calibration)

class PDST¶

Type variable for PhysicalDeviceState and its subclasses.

alias of TypeVar(‘PDST’, bound=PhysicalDeviceState)