Physical Devices#

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 PhysicalDevice(max_receive_delay=0.0, noise_power=None, leakage_calibration=None, delay_calibration=None, *args, **kwargs)#

Bases: Device

Base representing any device controlling real hardware.

Parameters:

  • max_receive_delay (float, optional) – Maximum expected delay during siganl reception in seconds. Zero by default.

  • noise_power (np.ndarray, optional) – Assumed power of the hardware noise at the device’s receive chains.

  • leakage_calibration (LeakageCalibrationBase, optional) – The leakage calibration routine to apply to received signals. If not provided, defaults to the NoLeakageCalibration stub routine.

  • delay_calibration (DelayCalibrationBase, optional) – The delay calibration routine to apply to received signals. If not provided, defaults to the NoDelayCalibration stub routine.

  • *args – Device base class initialization parameters.

  • **kwargs – Device base class initialization parameters.

abstract trigger()#

Trigger the device.

Return type:

None

property leakage_calibration: LeakageCalibrationBase#

Leakage calibration routine to apply to received signals.

Returns:

Handle to the calibration routine.

property delay_calibration: DelayCalibrationBase#

Delay calibration routine to apply to received signals.

Returns:

Handle to the delay calibration routine.

save_calibration(path)#

Save the calibration file to the hard drive.

Parameters:

path (str) – Path under which the file should be stored.

Return type:

None

load_calibration(path)#

Load the calibration file from the hard drive.

Parameters:

path (str) – Path from which to load the calibration file.

Return type:

None

property adaptive_sampling: bool#

Allow adaptive sampling during transmission.

Returns: Enabled flag.

property lowpass_filter: bool#

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

Returns: Enabled flag.

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 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 velocity: ndarray#

Cartesian device velocity vector.

Returns:

Velocity vector.

Return type:

np.ndarray

Raises:

  • ValueError – If velocity is not three-dimensional.

  • NotImplementedError – If velocity is unknown.

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.

estimate_noise_power(num_samples=1000, cache=True)#

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, optional) – Number of received samples. 1000 by default.

  • cache (bool, optional) – If enabled, the PhysicalDevice.noise_power() property will be updated.

Returns:

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

Return type:

np.ndarray

transmit(clear_cache=True)#

Transmit over this device.

Parameters:

clear_cache (bool, optional) – Clear the cache of operator signals to be transmitted. Enabled by default.

Return type:

DeviceTransmission

Returns: Information transmitted by this device.

trigger_direct(signal, calibrate=True)#

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, optional) – 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.

process_input(impinging_signals=None, cache=True)#

Process input signals impinging onto this device.

Parameters:

  • impinging_signals (Union[DeviceInput, Signal, Sequence[Signal]]) – The samples to be processed by the device.

  • cache (bool, optional) – Cache the operator inputs at the registered receive operators for further processing. Enabled by default.

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, cache=True)#

Receive over this device.

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

Parameters:

  • impinging_signals (Union[DeviceInput, Signal, Sequence[Signal]]) – The samples to be processed by the device.

  • cache (bool, optional) – Cache the received information. Enabled by default.

Return type:

DeviceReception

Returns: The received device information.

class Calibration(device=None)#

Bases: ABC, HDFSerializable, Serializable

Abstract basse class of all calibration classes.

hdf_group_name = 'calibration'#

Group name of the calibration in the HDF save file.

property device: PhysicalDevice | None#
save(path)#

Save the calibration file to the hard drive.

Parameters:

path (str) – Path under which the file should be stored.

Return type:

None

Raises:

classmethod Load(source)#
Return type:

TypeVar(CT, bound= Calibration)

class DelayCalibrationBase(device=None)#

Bases: Calibration, ABC

Abstract base class for all delay calibration classes.

hdf_group_name = 'delay_calibration'#

Group name of the delay calibration in the HDF save file.

abstract property delay: float#

Expected transmit-receive delay in seconds.

correct_transmit_delay(signal)#

Apply the delay calibration to a transmitted signal.

Parameters:

signal (Signal) – The signal to be corrected.

Return type:

Signal

Returns:

The corrected signal.

correct_receive_delay(signal)#

Apply the delay calibration to a received signal.

Parameters:

signal (Signal) – The signal to be corrected.

Return type:

Signal

Returns:

The corrected signal.

class NoDelayCalibration(device=None)#

Bases: DelayCalibrationBase, Serializable

No delay calibration.

yaml_tag: Optional[str] = 'NoDelayCalibration'#

YAML serialization tag.

property delay: float#

Expected transmit-receive delay in seconds.

correct_transmit_delay(signal)#

Apply the delay calibration to a transmitted signal.

Parameters:

signal (Signal) – The signal to be corrected.

Return type:

Signal

Returns:

The corrected signal.

correct_receive_delay(signal)#

Apply the delay calibration to a received signal.

Parameters:

signal (Signal) – The signal to be corrected.

Return type:

Signal

Returns:

The corrected signal.

to_HDF(group)#

Serialize the object state to HDF5.

Dumps the object’s state and additional information to a HDF5 group.

Parameters:

group (Group) – The HDF5 group to which the object is serialized.

Return type:

None

classmethod from_HDF(group)#

De-Serialized the object state from HDF5.

Recalls the object’s state from a HDF5 group.

Parameters:

group (Group) – The HDF5 group from which the object state is recalled.

Return type:

NoDelayCalibration

Returns: The object initialized from the HDF5 group state.

class LeakageCalibrationBase(device=None)#

Bases: Calibration

Abstract base class for all leakage calibration classes.

hdf_group_name = 'leakage_calibration'#

Group name of the leakage calibration in the HDF save file.

abstract remove_leakage(transmitted_signal, received_signal, delay_correction=0.0)#

Remove leakage from a received signal.

Parameters:

  • transmitted_signal (Signal) – The transmitted signal.

  • recveived_signal (Signal) – The received signal from which to remove the leakage.

  • delay_correction (float, optional) – Delay correction applied by the device during reception in seconds. Assumed zero by default.

Return type:

Signal

Returns:

The signal with removed leakage.

class NoLeakageCalibration(device=None)#

Bases: LeakageCalibrationBase, Serializable

No leakage calibration.

yaml_tag: Optional[str] = 'NoLeakageCalibration'#

YAML serialization tag.

remove_leakage(transmitted_signal, received_signal, delay_correction=0.0)#

Remove leakage from a received signal.

Parameters:

  • transmitted_signal (Signal) – The transmitted signal.

  • recveived_signal (Signal) – The received signal from which to remove the leakage.

  • delay_correction (float, optional) – Delay correction applied by the device during reception in seconds. Assumed zero by default.

Return type:

Signal

Returns:

The signal with removed leakage.

to_HDF(group)#

Serialize the object state to HDF5.

Dumps the object’s state and additional information to a HDF5 group.

Parameters:

group (Group) – The HDF5 group to which the object is serialized.

Return type:

None

classmethod from_HDF(group)#

De-Serialized the object state from HDF5.

Recalls the object’s state from a HDF5 group.

Parameters:

group (Group) – The HDF5 group from which the object state is recalled.

Return type:

NoLeakageCalibration

Returns: The object initialized from the HDF5 group state.