Wireless Scenario

Inheritance diagram of hermespy.core.scenario.Scenario, hermespy.core.scenario.ReplayScenario

Scenarios are the base class for describing a wireless application featuring multiple interconnected devices.

class Scenario(seed=None, devices=None)[source]

Bases: ABC, RandomNode, TransformableBase, Generic[DeviceType, DST, DropType]

A wireless scenario.

Scenarios consist of several devices transmitting and receiving electromagnetic signals. Each device can be operated by multiple operators simultaneously.

Parameters:

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

  • devices (Sequence[Device], optional) – Devices to be added to the scenario during initialization.

classmethod Replay(file, campaign='default')[source]

Replay a scenario from an HDF5 save file.

Parameters:

  • file (str) – File system location of the HDF5 save file.

  • campaign (str, optional) – Identifier of the campaign to replay. If not specified, the assumed campaign name is default.

Return type:

Scenario

add_device(device)[source]

Add a new device to the scenario.

Parameters:

device (Device) – New device to be added to the scenario.

Raises:
Return type:

None

device_index(device)[source]

Index of device

Parameters:

device (Device) – Device for which to lookup the index.

Return type:

int

Returns: The device index.

Raises:

ValueError – If device is not registered in this scenario.

device_registered(device)[source]

Check if an device is registered in this scenario.

Parameters:

device (Device) – The device to be checked.

Returns:

The device’s registration status.

Return type:

bool

drop()[source]

Generate a single data drop from all scenario devices.

Return: The generated drop information.

Return type:

TypeVar(DropType, bound= Drop)

generate_outputs(transmissions, states=None)[source]

Generate signals emitted by devices.

Parameters:

  • transmissions (list[list[Transmission]]) – Results of all transmitting DSP algorithms.

  • states (Sequence[DST | None], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state().

Return type:

Sequence[DeviceOutput]

Returns: List of device outputs.

new_device(*args, **kwargs)[source]

Add a new device to the scenario.

Convenience function pointing to hermespy.core.scenario.Scenario.new_device().

Returns: Handle to the created device.

Raises:

  • ValueError – If the device already exists.

  • RuntimeError – If the scenario is not in default mode.

  • RuntimeError – If the scenario does not allow for the creation or addition of new devices.

Return type:

TypeVar(DeviceType, bound= Device)

process_inputs(impinging_signals, states=None)[source]

Process input signals impinging onto the scenario’s devices.

Parameters:

  • impinging_signals (Sequence[DeviceInput | Signal | Sequence[Signal]]) – list of signals impinging onto the devices.

  • states (Sequence[DST | None], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state().

Return type:

Sequence[ProcessedDeviceInput]

Returns: list of the processed device input information.

Raises:

ValueError – If the number of impinging_signals does not match the number of registered devices.

receive_devices(impinging_signals, states=None, notify=True)[source]

Receive over all scenario devices.

Internally calls Scenario.process_inputs() and Scenario.receive_operators().

Parameters:

  • impinging_signals (Sequence[DeviceInput] | Sequence[Signal] | Sequence[Sequence[Signal]) – list of signals impinging onto the devices.

  • states (Sequence[DST | None], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling :meth:`Device.state

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

Return type:

Sequence[DeviceReception]

Returns: list of the processed device input information.

Raises:

ValueError – If the number of impinging_signals does not match the number of registered devices.

receive_operators(operator_inputs, states=None, notify=True)[source]

Receive over the registered operators.

Parameters:

  • operator_inputs (Sequence[Sequence[Signal]] | ProcessedDeviceInput) – Signal models to be processed by the receive DSP algorithms. Two-dimensional sequence where the first dimension corresponds to the devices and the second to the operators.

  • states (Sequence[DST | None], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state().

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

Return type:

Sequence[Sequence[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 devices.

record(file, overwrite=False, campaign='default', state=None, serialize_state=True)[source]

Start recording drop information generated from this scenario.

After the scenario starts recording, changing the device and operator configuration is not permitted.

Parameters:

  • file (str) – The system path where to store the generated recording data.

  • overwrite (bool, optional) – Overwrite the file if a recording already exists. Disabled by default.

  • campaign (str, optional) – Name of the measurement campaign.

  • state (scenario, optional) – Scenario to be used for state serialization. By default, this scenario is assumed.

  • serialize_state (bool, optional) – Serialize the scenario state to the recording. Enabled by default.

Raises:

RuntimeError – If the scenario is not in default mode.

Return type:

None

replay(file=None, campaign='default')[source]

Replay the scenario from and HDF5 savefile.

Parameters:

  • file (Union[None, str, File], optional) – File from which the scenario should be replayed. May be a file system location or an HDF5 File handle.

  • campaign (str, optional) – Identifier of the campaign to replay. If not specified, the assumed campaign name is default.

Raises:

  • RuntimeError – If file is not specified and can’t be inferred from previous record executions.

  • ValueError – If campaign is specified and is not contained within the savefile.

Return type:

None

stop()[source]

Stop a running recording / playback session.

Return type:

None

transmit_devices(states=None, notify=True)[source]

Generated information transmitted by all registered devices.

Parameters:

  • states (Sequence[DST | None], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state().

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

Return type:

Sequence[DeviceTransmission]

Returns: List of generated information transmitted by each device.

transmit_operators(states=None, notify=True)[source]

Generate information transmitted by all registered device operators.

Parameters:

  • states (Sequence[DST], optional) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state().

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

Return type:

Sequence[Sequence[Transmission]]

Returns:

The generated information sorted into devices and their respective operators.

property campaign: str

Measurement campaign identifier.

If not specified, the scenario will assume the campaign name to be default.

Returns:

Name of the current measurement campaign.

Raises:

ValueError – If in replay mode and the requested campaign name is not available.

property devices: list[DeviceType]

Devices registered in this scenario.

Returns: list of devices.

property drop_duration: float

The scenario’s default drop duration in seconds.

If the drop duration is set to zero, the property will return the maximum frame duration over all registered transmitting modems as drop duration!

Returns:

The default drop duration in seconds.

Return type:

float

Raises:
property mode: ScenarioMode

Current operating mode of the scenario.

Returns: Operating mode flag.

property num_devices: int

Number of devices in this scenario.

Returns:

Number of devices

Return type:

int

property num_drops: int | None

Number of drops within the scenario.

If the scenario is in replay mode, this property represents the recorded number of drops

If the scenario is in record mode, this property represnts the current number of recorded drops.

Returns: Number of drops. None if not applicable.

property num_operators: int

Number of operators within this scenario.

Returns:

The number of operators.

Return type:

int

property num_receivers: int

Number of receiving operators within this scenario.

Returns:

The number of receivers.

Return type:

int

property num_transmitters: int

Number of transmitting operators within this scenario.

Returns:

The number of transmitters.

Return type:

int

property operators: set[Operator]

All operators within this scenario.

Returns: A set containing all unique operators within this scenario

property receivers: list[Receiver]

All receiving operators within this scenario.

Returns:

list of all transmitting operators.

Return type:

list[Receiver]

serialized_attributes = {'devices'}
property transmitters: list[Transmitter]

All transmitting operators within this scenario.

Returns:

list of all transmitting operators.

Return type:

list[Transmitter]

yaml_tag = 'Scenario'
class ReplayScenario(seed=None, devices=None)[source]

Bases: Scenario[Device, DeviceState, Drop]

Scenario which is unable to generate drops.

Parameters:

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

  • devices (Sequence[Device], optional) – Devices to be added to the scenario during initialization.

class ScenarioMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Current scenario mode.

DEFAULT = 0

Default scenario state.

For configuration and generating drops.

RECORD = 1

Recording scenario state.

For recording datasets.

REPLAY = 2

Replay scenario state.

For replaying already recorded datasets.

class ScenarioType

Type of scenario.

alias of TypeVar(‘ScenarioType’, bound=Scenario)