Device Modeling

%%{init: {'theme': 'dark'}}%% classDiagram-v2 direction RL class Device { topology carrier_frequency transmit() receive() } class SimulatedDevice { position orientation velocity acceleration } class HardwareDevice { trigger() } class Operator { transmit() receive() } class Modem { tx_bits rx_bits ... waveform transmit() receive() } class Radar { waveform ... target_estimates transmit() receive() } Operator <|-- Modem Operator <|-- Radar Device *-- Operator SimulatedDevice <|-- Device HardwareDevice <|-- Device
%%{init: {'theme': 'dark'}}%% flowchart LR channel{Real World} subgraph devicea[HardwareDevice] direction TB deviceatx>Tx Slot] --> deviceabinding[Hardware Binding] --> devicearx>Rx Slot] end subgraph deviceb[HardwareDevice] direction TB devicebtx>Tx Slot] --> devicebbinding[Hardware Binding] --> devicebrx>Rx Slot] end deviceabinding <--> channel devicebbinding <--> channel
%%{init: {'theme': 'dark'}}%% flowchart LR channel{Channel Modeling} subgraph devicea[SimulatedDevice] direction TB deviceatx>Tx Slot] devicearx>Rx Slot] end subgraph deviceb[SimulatedDevice] direction TB devicebtx>Tx Slot] devicebrx>Rx Slot] end deviceatx --> channel --> devicearx devicebtx --> channel --> devicebrx
exception FloatingError

Bases: RuntimeError

Exception raised if an operation fails due to a currently being considered floating.

SlotType

Type of slot.

alias of TypeVar(‘SlotType’, bound=OperatorSlot)

OperatorType

Type of operator.

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

class Operator(slot=None)

Bases: Generic[hermespy.core.device.SlotType]

Base class for operators of devices.

In HermesPy, operators may configure devices, broadcast signals over them or capture signals from them. Each operator is attached to a single device instance it operates on.

Parameters

slot (OperatorSlot, optional) – Device slot this operator is attached to. By default, the operator is not attached and considered floating.

property slot: Optional[hermespy.core.device.OperatorSlot]

Device slot this operator operates.

Returns

Handle to the device slot. None if the operator is currently considered floating.

Return type

slot (Optional[OperatorSlot])

property slot_index: Optional[int]

Index of the operator within its slot.

Returns

Index of the operator. None if the operator is currently considered floating.

Return type

index (Optional[int])

property device: Optional[hermespy.core.device.Device]

Device this operator is attached to.

Returns

Handle to the operated device. None if the operator is currently considered floating.

Return type

device (Optional[Device])

property attached: bool

Attachment state of the operator.

Returns

Boolean attachment indicator

Return type

bool

abstract property frame_duration: float

Duration of a single sample frame.

Returns

Frame duration in seconds.

Return type

duration (float)

SecondSlotType

Type of slot.

alias of TypeVar(‘SecondSlotType’, bound=OperatorSlot)

class MixingOperator(carrier_frequency=None, slot=None)

Bases: Generic[hermespy.core.device.SlotType], hermespy.core.device.Operator[hermespy.core.device.SlotType], abc.ABC

Base class for operators performing mixing operations.

Parameters
  • carrier_frequency (float, optional) – Central frequency of the mixed signal in radio-frequency transmission band.

  • slot (SlotType, optional) – Device slot this operator operators.

property carrier_frequency: float

Central frequency of the mixed signal in radio-frequency transmission band.

By default, the carrier frequency of the operated device is returned.

Returns

Carrier frequency in Hz.

Return type

float

Raises
  • ValueError – If the carrier frequency is smaller than zero.

  • RuntimeError – If the operator is considered floating.

abstract property sampling_rate: float

Rate which this operator continuous signals into discrete samples.

Returns

Sampling rate in Hz.

Return type

rate (float)

class Receiver(seed=None, *args, **kwargs)

Bases: hermespy.core.random_node.RandomNode, hermespy.core.device.MixingOperator[ReceiverSlot]

Operator receiving from a device.

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

  • *args – Operator base class initialization parameters.

  • **kwargs – Operator base class initialization parameters.

property slot: Optional[hermespy.core.device.OperatorSlot]

Device slot this operator operates.

Returns

Handle to the device slot. None if the operator is currently considered floating.

Return type

slot (Optional[OperatorSlot])

property reference_transmitter: Optional[hermespy.core.device.Transmitter]

Reference transmitter for this receiver.

Returns

Handle to this receiver’s reference transmitter. None, if no reference transmitter is specified.

Return type

transmitter (Optional[Transmitter])

abstract receive()

Receive a signal.

Pulls the required signal model and channel state information from the underlying device.

Returns

Tuple of received signal as well as additional information.

Return type

Tuple[Signal, Any, …]

Raises

FloatingError – If the transmitter is currently considered floating.

property signal: Optional[hermespy.core.signal_model.Signal]

Cached recently received signal model.

Returns

Signal model. None if no signal model is cached.

Return type

signal (Optional[Signal])

property csi: Optional[hermespy.core.channel_state_information.ChannelStateInformation]

Cached recently received channel state information

Returns

Channel state information. None if no state information is cached.

Return type

csi (Optional[ChannelStateInformation])

cache_reception(signal, csi=None)

Cache recent reception at this receiver.

Parameters
Return type

None

abstract property energy: float

Average energy of the received signal.

Returns

Energy.

Return type

float

class OperatorSlot(device)

Bases: Generic[hermespy.core.device.OperatorType]

Slot list for operators of a single device.

Parameters

device (Device) – Device this slot belongs to.

property device: hermespy.core.device.Device

Device this operator slot belongs to.

Returns

Handle to the device.

Return type

Device

operator_index(operator)

Index of an operator within this slot.

Returns

The operator’s index.

Return type

index (int)

Raises

ValueError – If the operator is not registered at this slot.

add(operator)

Add a new operator to this slot.

Parameters

operator (OperatorType) – Operator to be added to this slot.

Raises

RuntimeError – If the operator is already registered at this slot.

Return type

None

remove(operator)

Remove an operator from this slot.

Parameters

operator (OperatorType) – Handle to the operator to be removed.

Raises

ValueError – If the operator is not registered at this slot.

Return type

None

registered(operator)

Check if an operator is registered at this slot.

Returns

Boolean indicating the registration status.

Return type

bool

property num_operators: int

Number of operators on this slot.

Returns

Number of operators.

Return type

int

class Transmitter(seed=None, *args, **kwargs)

Bases: hermespy.core.random_node.RandomNode, hermespy.core.device.MixingOperator[TransmitterSlot]

Operator transmitting over a device.

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

  • *args – Operator base class initialization parameters.

  • **kwargs – Operator base class initialization parameters.

abstract transmit(duration=0.0)

Transmit a signal.

Registers the signal samples to be transmitted by the underlying device.

Parameters

duration (float, optional) – Duration of the transmitted signal. If not specified, the duration will be inferred by the transmitter.

Returns

Tuple of transmitted signal as well as additional information.

Return type

Tuple[Signal, Any, …]

Raises

FloatingError – If the transmitter is currently considered floating.

property slot: Optional[hermespy.core.device.OperatorSlot]

Device slot this operator operates.

Returns

Handle to the device slot. None if the operator is currently considered floating.

Return type

slot (Optional[OperatorSlot])

class TransmitterSlot(*args, **kwargs)

Bases: hermespy.core.device.OperatorSlot[hermespy.core.device.Transmitter]

Slot for transmitting operators within devices.

Parameters
  • *args – OperatorSlot base class initialization parameters.

  • **kwargs – OperatorSlot base class initialization parameters.

add(operator)

Add a new operator to this slot.

Parameters

operator (OperatorType) – Operator to be added to this slot.

Raises

RuntimeError – If the operator is already registered at this slot.

Return type

None

add_transmission(transmitter, signal)

Add a transmitter’s most recent transmission.

Parameters
  • transmitter (Transmitter) – The transmitter emitting the signal.

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

Raises

ValueError – If the transmitter is not registered at this slot.

Return type

None

get_transmissions(clear_cache=True)

Get recent transmissions.

Return type

List[Signal]

clear_cache()

Clear the cached transmission of all registered transmit operators.

Return type

None

class ReceiverSlot(*args, **kwargs)

Bases: hermespy.core.device.OperatorSlot[hermespy.core.device.Receiver]

Slot for receiving operators within devices.

Parameters
  • *args – OperatorSlot base class initialization parameters.

  • **kwargs – OperatorSlot base class initialization parameters.

get_receptions(clear_cache=True)

Get recent receptions.

Return type

List[Tuple[Signal, ChannelStateInformation]]

class UnsupportedSlot(device)

Bases: hermespy.core.device.OperatorSlot

Slot for unsupported operations within devices.

Parameters

device (Device) – Device this slot belongs to.

add(operator)

Add a new operator to this slot.

Parameters

operator (OperatorType) – Operator to be added to this slot.

Raises

RuntimeError – If the operator is already registered at this slot.

Return type

None

class Device(antennas=None, power=1.0, position=None, orientation=None, topology=None, seed=None)

Bases: abc.ABC, hermespy.core.random_node.RandomNode

Physical device representation within HermesPy.

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

Parameters
  • antennas (AntennaArrayBase, optional) – Model of the device’s antenna array. By default, a UniformArray of ideal antennas is assumed.

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

  • position (np.ndarray, optional) – Position of the device within its scenario in cartesian coordinates. By default, the device position is considered to be unknown (None).

  • orientation (np.ndarray, optional) – Orientation of the device within its scenario as a quaternion. By default, the device orientation is considered to be unknown (None).

  • topology (np.ndarray, optional) – Antenna array topology of the device. By default, a single ideal omnidirectional antenna is assumed.

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

antennas: AntennaArrayBase

Model of the device’s antenna array.

transmitters: TransmitterSlot

Transmitters broadcasting signals over this device.

receivers: ReceiverSlot

Receivers capturing signals from this device

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 position: Optional[numpy.ndarray]

Position of the device within its scenario in cartesian coordinates.

Returns

The device’s position. None if the position is considered to be unknown.

Return type

position (Optional[np.array])

Raises

ValueError – If the position is not a valid cartesian vector.

property orientation: Optional[numpy.ndarray]

Orientation of the device within its scenario as a quaternion.

Returns

The modem orientation as a normalized quaternion. None if the position is considered to be unknown.

Return type

orientation (Optional[np.array])

Raises

ValueError – If orientation is not a valid quaternion.

property topology: numpy.ndarray

Antenna array topology.

The topology is represented by an Mx3 numpy array, where the first dimension M is the number of antennas and the second dimension their cartesian position within the device’s local coordinate system.

Returns

A matrix of Mx3 entries describing the sensor array topology.

Return type

topology (np.ndarray)

Raises

ValueError – If the first dimension topology is smaller than 1 or its second dimension is larger than 3.

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 antenna_positions: numpy.ndarray

Global positions of the antenna array elements.

Returns

Matrix of dimension num_antennas x 3.

Return type

np.ndarray

property max_frame_duration: float

Maximum frame duration transmitted by this device.

Returns

Maximum duration in seconds.

Return type

max_duration (float)

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.

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.

abstract property velocity: numpy.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.

transmit(clear_cache=True)

Transmit signal over this device.

Parameters

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

Returns

Signal emitted by this device.

Return type

Signal

DeviceType

Type of device.

alias of TypeVar(‘DeviceType’, bound=hermespy.core.device.Device)

class DuplexTransmitter(duplex_operator)

Bases: hermespy.core.device.Transmitter

Transmitter within a duplex operator.

Parameters

duplex_operator (DuplexOperator) – Duplex operator this transmitter is bound to.

transmit(duration=0.0)

Transmit a signal.

Registers the signal samples to be transmitted by the underlying device.

Parameters

duration (float, optional) – Duration of the transmitted signal. If not specified, the duration will be inferred by the transmitter.

Returns

Tuple of transmitted signal as well as additional information.

Return type

Tuple[Signal, Any, …]

Raises

FloatingError – If the transmitter is currently considered floating.

property sampling_rate: float

Rate which this operator continuous signals into discrete samples.

Returns

Sampling rate in Hz.

Return type

rate (float)

property frame_duration: float

Duration of a single sample frame.

Returns

Frame duration in seconds.

Return type

duration (float)

class DuplexReceiver(duplex_operator)

Bases: hermespy.core.device.Receiver

Receiver within a duplex operator.

Parameters

duplex_operator (DuplexOperator) – Duplex operator this receiver is bound to.

property sampling_rate: float

Rate which this operator continuous signals into discrete samples.

Returns

Sampling rate in Hz.

Return type

rate (float)

property frame_duration: float

Duration of a single sample frame.

Returns

Frame duration in seconds.

Return type

duration (float)

property reference_transmitter: Optional[hermespy.core.device.Transmitter]

Reference transmitter for this receiver.

Returns

Handle to this receiver’s reference transmitter. None, if no reference transmitter is specified.

Return type

transmitter (Optional[Transmitter])

receive()

Receive a signal.

Pulls the required signal model and channel state information from the underlying device.

Returns

Tuple of received signal as well as additional information.

Return type

Tuple[Signal, Any, …]

Raises

FloatingError – If the transmitter is currently considered floating.

property energy: float

Average energy of the received signal.

Returns

Energy.

Return type

float

class DuplexOperator

Bases: object

Operator binding to both transmit and receive slots of any device.

property device: Optional[hermespy.core.device.Device]

Device this operator is operating.

Returns

Handle to the operated device. None if the operator is currently operating no device.

Return type

device (Optional[device])

property reference_transmitter: hermespy.core.device.Transmitter

Reference transmitter for this duplex operator.

Returns

Handle to this receiver’s reference transmitter. By default, returns the duplex’s transmit operator.

Return type

transmitter (Transmitter])

abstract transmit(duration=0.0)
Return type

Tuple[Any, ...]

abstract receive()
Return type

Tuple[Any, ...]

abstract property sampling_rate: float
Return type

float

abstract property frame_duration: float
Return type

float

property carrier_frequency: float
Return type

float

abstract property energy: float

Average energy of the transmitted and received signal.

Returns

Energy.

Return type

flot