Wireless Scenario

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

class Scenario(seed=None, devices=None)

Bases: ABC, Serializable, 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 | None) – Random seed used to initialize the pseudo-random number generator.

• devices (Sequence[TypeVar(DeviceType, bound= Device)] | None) – Devices to be added to the scenario during initialization.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

Scenario

Returns:

The deserialized object.

classmethod Replay(file, campaign=None, backend=SerializationBackend.HDF)

Replay a scenario from an HDF5 save file.

Note

This function is currently highly experimental and may be subject to change. It does not fully deserialize all configurations in the case of simulation scenarios.

Parameters:

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

• campaign (str | None) – Identifier of the campaign to replay.

• backend (SerializationBackend) – Serialization backend to be used for deserialization. Default is HDF5.

Return type:

tuple[Scenario, int]

Returns: Tuple containing the replayed scenario and the number of recorded drops.

add_device(device)

Add a new device to the scenario.

Parameters:

device (TypeVar(DeviceType, bound= Device)) – New device to be added to the scenario.

Raises:

• ValueError – If the device already exists.

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

Return type:

None

device_index(device)

Index of device

Parameters:

device (TypeVar(DeviceType, bound= 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)

Check if an device is registered in this scenario.

Parameters:

device (TypeVar(DeviceType, bound= Device)) – The device to be checked.

Returns:

The device’s registration status.

Return type:

bool

drop()

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)

Generate signals emitted by devices.

Parameters:

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

• states (Sequence[Optional[TypeVar(DST, bound= DeviceState)]] | None) – 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)

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)

Process input signals impinging onto the scenario’s devices.

Parameters:

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

• states (Sequence[Optional[TypeVar(DST, bound= DeviceState)]] | None) – States of the transmitting devices. If not specified, the current device states will be queried by calling hermespy.core.device.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)

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[Optional[TypeVar(DST, bound= DeviceState)]] | None) – States of the transmitting devices. If not specified, the current device states will be queried by calling Device.state.

• notify (bool) – 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)

Receive over the registered operators.

Parameters:

• operator_inputs (Sequence[ProcessedDeviceInput] | Sequence[Sequence[Signal]]) – 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[Optional[TypeVar(DST, bound= DeviceState)]] | None) – States of the transmitting devices. If not specified, the current device states will be queried by calling hermespy.core.device.Device.state().

• notify (bool) – 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, campaign=None, overwrite=False, state=None, serialize_state=True, backend=SerializationBackend.HDF)

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.

• campaign (str | None) – Name of the measurement campaign.

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

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

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

• backend (SerializationBackend) – Serialization backend to be used for serialization. Default is HDF5.

Raises:

RuntimeError – If the scenario is not in default mode.

Return type:

None

replay(file=None, campaign=None, backend=SerializationBackend.HDF)

Replay the scenario from and HDF5 savefile.

Parameters:

• file (str | None) – File system location from which the scenario should be replayed. Must be specified if the scenario is not in replay mode.

• campaign (str | None) – Identifier of the campaign to replay.

• backend (SerializationBackend) – Serialization backend to be used for deserialization. Default is HDF5.

Raises:

• RuntimeError – If file is not specified and scenario is not in replay mode.

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

Return type:

int

Returns: Number of recorded drops to be replayed.

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

stop()

Stop a running recording / playback session.

Return type:

None

transmit_devices(states=None, notify=True)

Generated information transmitted by all registered devices.

Parameters:

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

• notify (bool) – 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)

Generate information transmitted by all registered device operators.

Parameters:

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

• notify (bool) – 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:

• ValueError – For durations smaller than zero.

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

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

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 represents the current number of recorded drops.

Returns: Number of drops. Zero if the scenario is in default mode.

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]

property transmitters: list[Transmitter]

All transmitting operators within this scenario.

Returns:

list of all transmitting operators.

Return type:

list[Transmitter]

class ReplayScenario(seed=None, devices=None)

Bases: Scenario[Device, DeviceState, Drop]

Scenario which is unable to generate drops.

Parameters:

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

• devices (Sequence[TypeVar(DeviceType, bound= Device)] | None) – Devices to be added to the scenario during initialization.

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

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)