Device Model

class Device(power=1.0, pose=None, seed=None)

Bases: ABC, Generic[DST], Transformable, RandomNode, Serializable

Physical device representation within HermesPy.

It acts as the basis for all transmissions and receptions of sampled electromagnetic signals.

Parameters:

• power (float, optional) – Average power of the transmitted signals in Watts. 1.0 Watt by default.

• pose (Transformation, optional) – Pose of the device with respect to its scenario coordinate system origin.

• seed (int, optional) – Random seed used to initialize the pseudo-random number generator.

add_dsp(dsp)

Add a DSP algorithm to this device.

Parameters:

dsp (Transmitter | Receiver) – DSP algorithm to be added to the device. If the DSP algorithm is a transmitter, it will be added to the transmit layer. If the DSP algorithm is a receiver, it will be added to the receive layer. If the DSP is both, it will be added to both layers.

Return type:

None

generate_output(operator_transmissions, state=None, resample=True)

Generate the device’s output.

Parameters:

• operator_transmissions (Sequence[Transmissions]) – List of operator transmissions from which to generate the output.

• state (DST, optional) – Device state to be used for the output generation. If not provided, query the current device state

• resample (bool, optional) – Resample the output signal to the device’s sampling rate. Enabled by default.

Return type:

DeviceOutput

Returns: The device’s output.

Raises:

RuntimeError – If the transmit coding is incompatible with the number of transmit antenna ports.

process_input(impinging_signals, state=None)

Process input signals impinging onto this device.

Parameters:

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

• state (DST, optional) – 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.

recall_reception(group)

Recall a specific reception from a HDF5 serialization.

Parameters:

group (Group) – HDF group containing the reception.

Return type:

DeviceReception

Returns: The recalled reception.

recall_transmission(group)

Recall a specific transmission from a HDF5 serialization.

Parameters:

group (Group) – HDF group containing the transmission.

Return type:

DeviceTransmission

Returns: The recalled transmission.

receive(impinging_signals, state=None, notify=True)

Receive over this device.

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

Parameters:

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

• state (DST, optional) – Device state to be used for the processing. If not provided, query the current device state by calling state().

• notify (bool, optional) – Notify all registered callbacks within the involved DSP algorithms. Enabled by default.

Return type:

DeviceReception

Returns: The received device information.

receive_operators(operator_inputs, state=None, notify=True)

Receive over the registered operators.

Parameters:

• operator_inputs (ProcessedDeviceInput | Sequence[Signal]) – The signal samples to be processed by the device’s operators. If a ProcessedDeviceInput is provided, the operator inputs will be extracted from it. Otherwise, the operator inputs are assumed to be provided directly.

• state (DST, optional) – Assumed state of the device during reception. If not provided, the current device state will be queried by calling state().

• notfiy (bool, optional) – Notify all registered callbacks within the involved DSP algorithms. Enabled by default.

Return type:

list[Reception]

Returns: List of information generated by receiving over the device’s operators.

Raises:

ValueError – If the number of operator inputs does not match the number of receive operators.

abstract state()

Query the immutable physical state of the device.

Returns: The physical device state.

Return type:

TypeVar(DST, bound= DeviceState)

transmit(state=None, notify=True)

Transmit over this device.

Parameters:

• state (DST, optional) – Device state to be used for the transmission. If not provided, query the current device state by calling state().

• notify (bool, optional) – Notify the transmitter’s callbacks about the generated transmission. Enabled by default.

Return type:

DeviceTransmission

Returns: Information transmitted by this device.

transmit_operators(state=None, notify=True)

Generate transmitted information for all registered operators.

Calls Transmitter.transmit() for each transmit operator.

Parameters:

• state (DST, optional) – Device state to be used for the transmission. If not provided, query the current device state by calling state().

• notify (bool, optional) – Notify the transmitter’s callbacks about the generated transmission. Enabled by default.

Return type:

list[Transmission]

Returns: List of operator transmisisons.

abstract property antennas: AntennaArray

Model of the device’s antenna array.

abstract property carrier_frequency: float

Central frequency of the device’s emissions in the RF-band.

Returns:

Carrier frequency in Hz.

Return type:

frequency (float)

Raises:

ValueError – On negative carrier frequencies.

property input_callbacks: Hookable[ProcessedDeviceInput]

Callbacks notified about processed inputs.

property max_frame_duration: float

Maximum frame duration transmitted by this device.

Returns:

Maximum duration in seconds.

Return type:

max_duration (float)

property num_antennas: int

Number of antennas within this device’s topology.

Returns:

Number of antennas, greater or equal to one.

Return type:

int

property num_digital_receive_ports: int

Number of available digital signal stream ports for reception.

If no receive coding was configured, this value is equal to the number of receive antenna ports.

property num_digital_transmit_ports: int

Number of available digital signal stream ports for transmission.

If no transmit coding was configured, this value is equal to the number of transmit antenna ports.

property num_receive_antenna_ports: int

Number of available receive antenna ports.

Short hand to antennas' num_receive_ports.

property num_receive_antennas: int

Number of available receive antennas.

Shorthand to antennas' num_receive_antennas.

property num_transmit_antenna_ports: int

Number of available transmit antenna ports.

Shorthand to antennas' num_transmit_ports.

property num_transmit_antennas: int

Number of available transmit antennas.

Shorthand to antennas' num_transmit_antennas.

property output_callbacks: Hookable[DeviceOutput]

Callbacks notified about generated outputs.

property power: float

Average power of the transmitted signal signal.

Returns:

Power in Watt.

Return type:

power (float)

Raises:

ValueError – If value is smaller than zero.

property receive_coding: ReceiveSignalCoding

Digital coding applied to received samples after analog-to-digital conversion.

receivers: ReceiverSlot

Receivers capturing signals from this device

abstract property sampling_rate: float

Sampling rate at which the device’s analog-to-digital converters operate.

Returns:

Sampling rate in Hz.

Return type:

sampling_rate (float)

Raises:

ValueError – If the sampling rate is not greater than zero.

property snr: float

Signal to noise ratio of the received signal.

Returns: Linear signal to noise ratio

property transmit_coding: TransmitSignalCoding

Digital coding applied to transmitted samples before digital-to-analog conversion.

transmitters: TransmitterSlot

Transmitters broadcasting signals over this device.

property wavelength: float

Central wavelength of the device’s emmissions in the RF-band.

Returns:

Wavelength in m.

Return type:

wavelength (float)

Raises:

ValueError – On wavelengths smaller or equal to zero.