Devices

SimulatedDevices are the description of any entity capable of transmitting or receiving electromagnetic waves within a HermesPy simulation scenario. A simulation scenario may feature one or multiple devices freely exchanging electromagnetic waves at any different carrier frequencies and bandwidths.

Creating a new simulated device is as simple as initializing a new class instance, or calling new_device on a Simulation instance.

    Simulation,
    SimulatedDevice,
    SimulatedIdealAntenna,
    SimulatedUniformArray,
    SpecificIsolation,
    AWGN,
    N0,
    StaticTrajectory
)

# Create a new stand-alone simulated device
device = SimulatedDevice()

# Create a new device within a simulation context
simulation = Simulation()
device = simulation.new_device()

There exist a number of attributes that can be configured to describe the device’s physical properties, such as its antenna front-end, its radio-frequency chain, the isolation / leakage between transmit and receive chains, the mutual coupling between multiple antennas, the synchronizatio and the hardware noise.

# Configure the default carrier frequency at wich waveforms are emitted
device.carrier_frequency = 3.7e9

# Configure the antenna frontend
device.antennas = SimulatedUniformArray(SimulatedIdealAntenna, .5 * device.wavelength, [4, 4, 1])

# Configure the default rf-chain model
device.rf_chain = RfChain()

# Configure a transmit-receive isolation model
device.isolation = SpecificIsolation(
    1e-10 * np.ones((device.num_receive_antennas, device.num_transmit_antennas))
)

# Configure a mutual coupling model
device.coupling = PerfectCoupling()

# Configure a trigger model for synchronization
device.trigger_model = RandomTrigger()

# Specify a default sampling rate / bandwidth
device.sampling_rate = 100e6

# Configure a hardware noise model
device.noise_model = AWGN()
device.noise_level = N0(dB(-20))

Additionally, within the context of a simulation scenario, users may configure the device’s position, orientation and velocity.

# Specify the device's postion, orientation and velocity in space
device.trajectory = StaticTrajectory(
    Transformation.From_RPY(
        np.array([0, .125 * np.pi, 0], dtype=np.float64),
        np.array([10., 10., 0.], dtype=np.float64)
    ),
    np.array([1., 1., 0.], dtype=np.float64)
)

Note that these properties are only considered by spatial channel models linking to the respective devices, and are otherwise ignored by the simulation engine.

By themselves, devices neither generate any waveforms, nor perform any signal processing on received waveforms. Instead, transmit and receive digital signal processing algorithms have to be assigned to the device’s respective transmitters and receivers slots.

# Transmit random white noise from the device
transmitter = SignalTransmitter(Signal.Create(
    np.random.normal(size=(device.num_digital_transmit_ports, 100)) +
    1j * np.random.normal(size=(device.num_digital_transmit_ports, 100)),
    device.sampling_rate,
    device.carrier_frequency
))
device.transmitters.add(transmitter)

# Receive a signal without additional processing at the device
receiver = SignalReceiver(100, device.sampling_rate, expected_power=1.)
device.receivers.add(receiver)

The selected singnal processing algorithms in the snippet above are rather simplistic and only generate a static signal that is continuously transmitted, and receive a fixed number of samples, respectively. More complex algorithms implementing communication modems, radars or joint communication and sensing algorithms are available in HermesPy’s Communication, Sensing and JCAS modules.

Outside of full-fledged Monte Carlo simulations, users may inspect the output of a configured simulated device by calling the transmit method.

# Generate a transmission from the device
transmission = device.transmit()

Similarly, users may inspect the signal processing result of configured receive signal processing algorithms by calling the receive method and providing a Signal model of the assumed waveform impinging onto the device.

# Receive a signal at the device
impinging_signal = Signal.Create(
    np.random.normal(size=(device.num_digital_transmit_ports, 100)) +
    1j * np.random.normal(size=(device.num_digital_transmit_ports, 100)),
    device.sampling_rate,
    device.carrier_frequency
)
reception = device.receive(impinging_signal)

The transmit routine is a wrapper around multiple subroutines, that are individually executed during simulation runtime for performance optimization reasons, finally returning a SimulatedDeviceTransmission dataclass containing all information generated during the simulation of the device’s transmit chain.

        graph TD

transmit_operators[transmit_operators]
operator_transmissions{{List Transmission}}
generate_output[generate_output]
output{{SimulatedDeviceOutput}}
deviceTransmission{{SimulatedDeviceTransmission}}
triggerRealization{{TriggerRealization}}

transmit_operators --> operator_transmissions --> generate_output --> output
operator_transmissions --> deviceTransmission
output --> deviceTransmission
triggerRealization --> generate_output

click transmit_operators "core.device.Device.html#hermespy.core.device.Device.transmit_operators" "transmit_operators"
click operator_transmissions "core.device.Transmission.html#hermespy.core.device.Transmission" "Transmission"
click generate_output "#hermespy.simulation.simulated_device.SimulatedDevice.generate_output" "generate_output"
click output "simulation.simulated_device.SimulatedDeviceOutput.html" "SimulatedDeviceOutput"
click deviceTransmission "simulation.simulated_device.SimulatedDeviceTransmission.html" "SimulatedDeviceTransmission"
click triggerRealization "simulation.synchronization.TriggerRealization.html" "TriggerRealization"
    

The receive method requires the input of the signal to be processed by the device, and is also a wrapper around multiple subroutines, that are individually executed during simulation runtime for performance optimization reasons, finally returning a SimulatedDeviceReception dataclass containing all information generated during the simulation of the device’s receive chain.

        graph TD

signal{{Impinging Signal}}
triggerRealization{{TriggerRealization}}
leaking_signal{{Leaking Signal}}
processed_input{{ProcessedSimulatedDeviceInput}}
receptions{{List Reception}}
device_reception{{SimulatedDeviceReception}}

subgraph process_input [process_input]

    realize_reception[[realize_reception]]
    process_from_realization[[process_from_realization]]
    device_realization{{SimulatedDeviceReceiveRealization}}
end

receive_operators[receive_operators]

signal --> process_input
triggerRealization --> process_input
leaking_signal --> process_input
realize_reception --> device_realization --> process_from_realization
process_from_realization --> processed_input
processed_input --> receive_operators
receive_operators --> receptions
receptions --> device_reception
processed_input --> device_reception

click signal "core.signal_model.Signal.html" "Signal"
click triggerRealization "simulation.synchronization.TriggerRealization.html" "TriggerRealization"
click leaking_signal "core.signal_model.Signal.html" "Signal"
click realize_reception "#hermespy.simulation.simulated_device.SimulatedDevice.realize_reception" "realize_reception"
click device_realization "simulation.simulated_device.SimulatedDeviceReceiveRealization.html" "SimulatedDeviceReceiveRealization"
click processed_input "simulation.simulated_device.ProcessedSimulatedDeviceInput.html" "ProcessedSimulatedDeviceInput"
click receive_operators "core.device.Device.html#hermespy.core.device.Device.receive_operators" "receive_operators"
click receptions "core.device.Reception.html#hermespy.core.device.Reception" "Reception"
click device_reception "simulation.simulated_device.SimulatedDeviceReception.html" "SimulatedDeviceReception"
click process_from_realization "#hermespy.simulation.simulated_device.SimulatedDevice.process_from_realization" "process_from_realization"
    

class SimulatedDevice(scenario=None, antennas=None, rf_chain=None, isolation=None, coupling=None, trigger_model=None, sampling_rate=None, carrier_frequency=0.0, noise_level=None, noise_model=None, pose=None, velocity=None, power=1.0, seed=None)

Bases: Device[SimulatedDeviceState], Moveable, Serializable

Representation of an entity capable of emitting and receiving electromagnetic waves.

A simulation scenario consists of a collection of devices, interconnected by a network of channel models.

Parameters:

• scenario (Scenario, optional) – Scenario this device is attached to. By default, the device is considered floating.

• antennas (SimulatedAntennaArray, optional) – Antenna array model of the device. By default, a single ideal istropic antenna is assumed.

• rf_chain (RfChain, optional) – Model of the device’s radio frequency amplification chain. If not specified, a chain with ideal hardware models will be assumed.

• isolation (Isolation, optional) – Model of the device’s transmit-receive isolations. By default, perfect isolation is assumed.

• coupling (Coupling, optional) – Model of the device’s antenna array mutual coupling. By default, ideal coupling behaviour is assumed.

• trigger_model (TriggerModel, optional) – The assumed trigger model. By default, a StaticTrigger is assumed.

• sampling_rate (float, optional) – Sampling rate at which this device operates. By default, the sampling rate of the first operator is assumed.

• carrier_frequency (float, optional) – Center frequency of the mixed signal in rf-band in Hz. Zero by default.

• noise_level (NoiseLevel, optional) – Level of the decvice’s additive noise. By default, infinite signal-to-noise ratio (SNR) is assumed.

• noise_model (NoiseModel, optional) – Spectral model of the device’s additive noise. By default, additive white Gaussian noise is assumed.

• pose (Transformation | Trajectory, optional) – Position and orientation of the device in time and space. If a Transformation is provided, the device is assumed to be static. If not specified, the device is assumed to be at the origin with zero velocity.

• velocity (numpy.ndarray, optional) – Initial velocity of the moveable in local coordinates. By default, the moveable is assumed to be resting. Only considered if pose is a Transformation, otherwise the velocity is assumed from the Trajectory.

• power (float, optional) – Power of the device. Assumed to be 1.0 by default.

• seed (int, optional) – Seed of the device’s pseudo-random number generator.

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

Generate the simulated device’s output.

Parameters:

• operator_transmissions (Sequence[Transmissions]) – Resulting transmissions of the device’s transmit DSP algorithms.

• state (SimulatedDeviceState, optional) – State of the device during the transmission. If not specified, the simulated device’s state at timestamp zero will be assumed.

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

• trigger_realization (TriggerRealization, optional) – Trigger realization modeling the time delay between a drop start and frame start. Perfect triggering is assumed by default.

• operator_transmit_ports (Sequence[Sequence[int]], optional) – Intended transmission ports of each transmit DSP algorithm. If not specified, the operator’s default ports will be assumed.

Return type:

SimulatedDeviceOutput

Returns: The device’s output.

process_from_realization(impinging_signals, realization, trigger_realization=None, leaking_signals=None, state=None)

Simulate a signal reception for this device model.

Parameters:

• impinging_signals (DeviceInput | Signal | Sequence[Signal] | SimulatedDeviceOutput) – List of signal models arriving at the device. May also be a two-dimensional numpy object array where the first dimension indicates the link and the second dimension contains the transmitted signal as the first element and the link channel as the second element.

• realization (SimulatedDeviceRealization) – Random realization of the device reception process.

• trigger_realization (TriggerRealization, optional) – Trigger realization modeling the time delay between a drop start and frame start. Perfect triggering is assumed by default.

• leaking_signal (Signal, optional) – Signal leaking from transmit to receive chains. Expected to be a sequence of signals if operator_separation is enabled. If not specified, no leakage is considered during signal reception.

• state (SimulatedDeviceState, optional) – State of the simulated device during the reception. If not specified, the device’s state at timestamp zero will be assumed.

Return type:

ProcessedSimulatedDeviceInput

Returns: The received information.

Raises:

ValueError – If device_signals is constructed improperly.

process_input(impinging_signals, state=None, trigger_realization=None, noise_level=None, noise_model=None, leaking_signals=None)

Process input signals at this device.

Parameters:

• impinging_signals (DeviceInput | Signal | Sequence[Signal] | SimulatedDeviceOutput) – List of signal models arriving at the device. May also be a two-dimensional numpy object array where the first dimension indicates the link and the second dimension contains the transmitted signal as the first element and the link channel as the second element.

• state (SimulatedDeviceState, optional) – State of the device during the reception. If not specified, the device’s state at timestamp zero will be assumed.

• trigger_realization (TriggerRealization, optional) – Trigger realization modeling the time delay between a drop start and frame start. Perfect triggering is assumed by default.

• noise_level (NoiseLevel, optional) – Level of the simulated hardware noise. If not specified, the device’s configured noise level will be assumed.

• noise_model (NoiseModel, optional) – Model of the simulated hardware noise. If not specified, the device’s configured noise model will be assumed.

• leaking_signals (Signal, optional) – Signals leaking from transmit to receive chains. Expected to be a sequence of signals if operator_separation is enabled. If not specified, no leakage is considered during signal reception.

Return type:

ProcessedSimulatedDeviceInput

Returns: The processed device input.

realize_reception(noise_level=None, noise_model=None)

Generate a random realization for receiving over the simulated device.

Parameters:

• noise_level (NoiseLevel, optional) – Level of the simulated hardware noise. If not specified, the device’s configured noise level will be assumed.

• noise_model (NoiseModel, optional) – Model of the simulated hardware noise. If not specified, the device’s configured noise model will be assumed.

Return type:

SimulatedDeviceReceiveRealization

Returns: The generated realization.

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

Receive information at this device.

Parameters:

• impinging_signals (DeviceInput | Signal | Sequence[Signal] | SimulatedDeviceOutput) – List of signal models arriving at the device. May also be a two-dimensional numpy object array where the first dimension indicates the link and the second dimension contains the transmitted signal as the first element and the link channel as the second element.

• state (SimulatedDeviceState, optional) – State of the device during the reception. If not specified, the device’s state at timestamp zero will be assumed.

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

• trigger_realization (TriggerRealization, optional) – Trigger realization modeling the time delay between a drop start and frame start. Perfect triggering is assumed by default.

Return type:

SimulatedDeviceReception

Returns: The processed device input.

state(timestamp=0.0)

Immutable physical state of the device during simulation drop generation.

Parameters:

timestamp (float, optional) – Global timestamp in seconds. By default, zero is assumed.

Return type:

SimulatedDeviceState

Returns: Device state at the given timestamp.

transmit(state=None, notify=True, trigger_realization=None)

Transmit over this device.

Parameters:

• state (SimulatedDeviceState, optional) – State of the device during the transmission. If not specified, the device’s current state will be assumed.

• notify (bool, optional) – Notify the DSP layer’s callbacks about the transmission results. Enabled by default.

• trigger_realization (TriggerRealization, optional) – Trigger realization modeling the time delay between a drop start and frame start. Perfect triggering is assumed by default.

Return type:

SimulatedDeviceTransmission

Returns: Information transmitted by this device.

property antennas: SimulatedAntennaArray

Antenna array model of the simulated device.

property attached: bool

Attachment state of this device.

Returns:

True if the device is currently attached, False otherwise.

Return type:

bool

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 coupling: Coupling

Model of the device’s antenna array mutual coupling behaviour.

Returns: Handle to the coupling model.

property isolation: Isolation

Model of the device’s transmit-receive isolation.

Returns: Handle to the isolation model.

property noise: float

Shorthand property for accessing the noise level of the device.

Raises:

ValueError – For negative noise levels.

property noise_level: NoiseLevel

Level of the simulated hardware noise.

property noise_model: NoiseModel

Model of the simulated hardware noise.

property operator_separation: bool

Separate operators during signal modeling.

Returns:

Enabled flag.

rf_chain: RfChain

Model of the device’s radio-frequency chain.

property sampling_rate: float

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

Returns:

Sampling rate in Hz. If no operator has been specified and the sampling rate was not set, a sampling rate of \(1\) Hz will be assumed by default.

Raises:

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

property scenario: Scenario | None

Scenario this device is attached to.

Returns:

Handle to the scenario this device is attached to. None if the device is considered floating.

serialized_attribute = {'adc', 'rf_chain'}

property simulated_input_callbacks: Hookable[ProcessedSimulatedDeviceInput]

Callbacks notified about processed inputs.

property simulated_output_callbacks: Hookable[SimulatedDeviceOutput]

Callbacks notified about generated outputs.

property trigger_model: TriggerModel

The device’s trigger model.