Communication Waveform Base

class Synchronization(waveform_generator=None)

Bases: Generic[hermespy.modem.waveform_generator.WaveformType], abc.ABC, hermespy.core.factory.Serializable

Abstract base class for synchronization routines of waveform generators.

Refer to Nasir et al.1 for an overview of the current state of the art.

Parameters: waveform_generator (WaveformGenerator, optional) – The waveform generator this synchronization routine is attached to.

yaml_tag: Optional[str] = 'Synchronization': YAML serialization tag

property waveform_generator: Optional[hermespy.modem.waveform_generator.WaveformType]

Waveform generator this synchronization routine is attached to.

Returns: Handle to tghe waveform generator. None if the synchronization routine is floating.
Return type: Optional[WaveformType]

synchronize(signal, channel_state)

Simulates time-synchronization at the receiver-side.

Sorts base-band signal-sections into frames in time-domain.

Parameters

signal (np.ndarray) – Vector of complex base-band samples of with num_streams`x`num_samples entries.
channel_state (ChannelStateInformation) – State of the wireless transmission channel over which signal has been propagated.

Returns

Tuple of signal samples and channel transformations sorted into frames

Return type

List[Tuple[np.ndarray, ChannelStateInformation]]

Raises

ValueError – If the number of received streams in channel_state does not equal one. If the length of signal and the number of samples in channel_state are not identical.
RuntimeError – If the synchronization routine is floating

classmethod to_yaml(representer, node)

Serialize an Synchronization object to YAML.

Parameters

representer (Synchronization) – A handle to a representer used to generate valid YAML code. The representer gets passed down the serialization tree to each node.
node (Synchronization) – The Synchronization instance to be serialized.

Returns

The serialized YAML node

Return type

Node

classmethod from_yaml(constructor, node)

Recall a new Synchronization instance from YAML.

Parameters

constructor (SafeConstructor) – A handle to the constructor extracting the YAML information.
node (Node) – YAML node representing the Synchronization serialization.

Returns

Newly created Synchronization instance.

Return type

Synchronization

class ChannelEstimation(waveform_generator=None)

Bases: Generic[hermespy.modem.waveform_generator.WaveformType], abc.ABC

Abstract base class for channel estimation routines of waveform generators.

Parameters: waveform_generator (WaveformGenerator, optional) – The waveform generator this estimation routine is attached to.

property waveform_generator: Optional[hermespy.modem.waveform_generator.WaveformType]

Waveform generator this synchronization routine is attached to.

Returns: Handle to the waveform generator. None if the synchronization routine is floating.
Return type: Optional[WaveformType]

estimate_channel(signal, csi=None)

Estimate the wireless channel of a received communication frame.

Parameters

signal (Signal) – Signal model of the communication frame waveform.
csi (ChannelStateInformation, optional) – Ideal channel state information. May be required for some routines.

Raises

ValueError – If csi is required but not provided.

Return type

ChannelStateInformation

class ChannelEqualization(waveform_generator=None)

Bases: Generic[hermespy.modem.waveform_generator.WaveformType], abc.ABC

Abstract base class for channel equalization routines of waveform generators.

Parameters: waveform_generator (WaveformGenerator, optional) – The waveform generator this equalization routine is attached to.

property waveform_generator: Optional[hermespy.modem.waveform_generator.WaveformType]

Waveform generator this equalization routine is attached to.

Returns: Handle to the waveform generator. None if the equalization routine is floating.
Return type: Optional[WaveformType]

equalize_channel(signal, csi, snr=inf)

Equalize the wireless channel of a received communication frame.

Parameters

signal (Signal) – Signal model of the communication frame waveform.
csi (ChannelStateInformation) – Channel state estimation
snr (float) – Assumed signal to noise ratio. May be required by some routines, infinite by default.

Returns

The equalized signal model.

Return type

Signal

class WaveformGenerator(modem=None, oversampling_factor=1, modulation_order=16)

Bases: abc.ABC

Implements an abstract waveform generator.

Implementations for specific technologies should inherit from this class.

Waveform Generator initialization.

Parameters

modem (Modem, optional) – A modem this generator is attached to. By default, the generator is considered to be floating.
oversampling_factor (int, optional) – The factor at which the simulated baseband_signal is oversampled.
modulation_order (int, optional) – Order of modulation. Must be a non-negative power of two.

yaml_tag: str = 'Waveform': YAML serialization tag.

symbol_type

Symbol type.

alias of complex

abstract property samples_in_frame: int

The number of discrete samples per generated frame.

Returns: The number of samples.
Return type: int

property oversampling_factor: int

Access the oversampling factor.

Returns: The oversampling factor.
Return type: int

property modulation_order: int

Access the modulation order.

Returns: The modulation order.
Return type: int

property bits_per_symbol: int

Number of bits transmitted per modulated symbol.

Returns: Number of bits per symbol
Return type: int

abstract property bits_per_frame: int

Number of bits required to generate a single data frame.

Returns: Number of bits
Return type: int

abstract property symbols_per_frame: int

Number of dat symbols per transmitted frame.

Returns: Number of data symbols
Return type: int

property frame_duration: float

Length of one data frame in seconds.

Returns: Frame length in seconds.
Return type: float

abstract property bit_energy: float

Returns the theoretical average (discrete-time) bit energy of the modulated baseband_signal.

Energy of baseband_signal x[k] is defined as sum{|x[k]}^2 Only data bits are considered, i.e., reference, guard intervals are ignored.

Return type: float

abstract property symbol_energy: float

The theoretical average symbol (discrete-time) energy of the modulated baseband_signal.

Energy of baseband_signal x[k] is defined as sum{|x[k]}^2 Only data bits are considered, i.e., reference, guard intervals are ignored.

Return type: float
Returns: The average symbol energy in UNIT.

abstract property power: float

Returns the theoretical average symbol (unitless) power,

Power of baseband_signal x[k] is defined as sum_{k=1}^N{|x[k]|}^2 / N Power is the average power of the data part of the transmitted frame, i.e., bit energy x raw bit rate

Return type: float

abstract map(data_bits)

Map a stream of bits to data symbols.

Parameters: data_bits (np.ndarray) – Vector containing a sequence of L hard data bits to be mapped onto data symbols.
Returns: Mapped data symbols.
Return type: Symbols

abstract unmap(symbols)

Map a stream of data symbols to data bits.

Parameters: symbols (Symbols) – Sequence of K data symbols to be mapped onto bit sequences.
Returns: Vector containing the resulting sequence of L data bits In general, L is greater or equal to K.
Return type: np.ndarray

abstract modulate(data_symbols)

Modulate a stream of data symbols to a base-band signal containing a single data frame.

Parameters: data_symbols (Symbols) – Singular stream of data symbols to be modulated by this waveform.
Returns: Signal model of a single modulate data frame.
Return type: Signal

abstract demodulate(signal, channel_state, noise_variance)

Demodulate a base-band signal stream to data symbols.

Parameters

signal (np.ndarray) – Vector of complex-valued base-band samples of a single communication frame.
channel_state (ChannelStateInformation) – Channel state information of a single communication frame.
noise_variance (float) – Variance of the thermal noise introduced during reception.

Returns

Tuple of 3 vectors of equal-length first dimension num_symbols. The demodulated data symbols, their channel estimates and their noise variance.

Return type

(np.ndarray, ChannelStateInformation, np.ndarray)

abstract property bandwidth: float

Bandwidth of the frame generated by this generator.

Used to estimate the minimal sampling frequency required to adequately simulate the scenario.

Returns: Bandwidth in Hz.
Return type: float

property data_rate: float

Data rate theoretically achieved by this waveform configuration.

Return type: float
Returns: Bits per second.

property modem: hermespy.modem.modem.Modem

Access the modem this generator is attached to.

Returns: A handle to the modem.
Return type: Modem
Raises: RuntimeError – If this waveform generator is not attached to a modem.

property synchronization: hermespy.modem.waveform_generator.Synchronization

Synchronization routine.

Returns: Handle to the synchronization routine.
Return type: Synchronization

property channel_estimation: hermespy.modem.waveform_generator.ChannelEstimation

Channel estimation routine.

Returns: Handle to the synchronization routine.
Return type: ChannelEstimation

property channel_equalization: hermespy.modem.waveform_generator.ChannelEqualization

Channel estimation routine.

Returns: Handle to the equalization routine.
Return type: ChannelEqualization

abstract property sampling_rate: float

Rate at which the waveform generator signal is internally sampled.

Returns: Sampling rate in Hz.
Return type: float

classmethod to_yaml(representer, node)

Serialize an WaveformGenerator object to YAML.

Parameters

representer (SafeRepresenter) – A handle to a representer used to generate valid YAML code. The representer gets passed down the serialization tree to each node.
node (WaveformGenerator) – The WaveformGenerator instance to be serialized.

Returns

The serialized YAML node

Return type

Node

classmethod from_yaml(constructor, node)

Recall a new WaveformGenerator instance from YAML.

Parameters

constructor (SafeConstructor) – A handle to the constructor extracting the YAML information.
node (Node) – YAML node representing the WaveformGenerator serialization.

Returns

Newly created WaveformGenerator instance.

Return type

WaveformGenerator

class PilotWaveformGenerator(modem=None, oversampling_factor=1, modulation_order=16)

Bases: hermespy.modem.waveform_generator.WaveformGenerator, abc.ABC

Abstract base class of communication waveform generators generating a pilot signal.

Waveform Generator initialization.

Parameters

modem (Modem, optional) – A modem this generator is attached to. By default, the generator is considered to be floating.
oversampling_factor (int, optional) – The factor at which the simulated baseband_signal is oversampled.
modulation_order (int, optional) – Order of modulation. Must be a non-negative power of two.

abstract property pilot_signal: hermespy.core.signal_model.Signal

Model of the pilot sequence within this communication waveform.

Returns: The pilot sequence.
Return type: Signal

class PilotSymbolSequence

Bases: abc.ABC

Abstract base class for pilot sequences.

abstract property sequence: numpy.ndarray

The scalar sequence of pilot symbols.

For a configurable pilot section, this symbol sequence will be repeated accordingly.

Return type: ndarray
Returns: The symbol sequence.

class UniformPilotSymbolSequence(pilot_symbol=1 + 0j)

Bases: hermespy.modem.waveform_generator.PilotSymbolSequence

A pilot symbol sequence containing identical symbols.

Only viable for testing purposes, since it makes the pilot sections easy to spot within the frame. Not advisable to be used in production scenarios.

Parameters: pilot_symbol (complex) – The configured single pilot symbol. 1. by default.

property sequence: numpy.ndarray

The scalar sequence of pilot symbols.

For a configurable pilot section, this symbol sequence will be repeated accordingly.

Return type: ndarray
Returns: The symbol sequence.

class CustomPilotSymbolSequence(pilot_symbols)

Bases: hermespy.modem.waveform_generator.PilotSymbolSequence

A customized pilot symbol sequence.

The user may freely chose the pilot symbols from samples within the complex plane.

Parameters: pilot_symbols (np.ndarray) – The configured pilot symbols

property sequence: numpy.ndarray

The scalar sequence of pilot symbols.

For a configurable pilot section, this symbol sequence will be repeated accordingly.

Return type: ndarray
Returns: The symbol sequence.

class ConfigurablePilotWaveform(symbol_sequence=None, repeat_symbol_sequence=True)

Bases: hermespy.modem.waveform_generator.PilotWaveformGenerator, abc.ABC

Parameters

symbol_sequence (Optional[PilotSymbolSequence], optional) – The configured pilot symbol sequence. Uniform by default.
repeat_symbol_sequence (bool, optional) – Allow the repetition of pilot symbol sequences. Enabled by default.

pilot_symbol_sequence: hermespy.modem.waveform_generator.PilotSymbolSequence: The configured pilot symbol sequence.

repeat_pilot_symbol_sequence: bool: Allow the repetition of pilot symbol sequences.

pilot_symbols(num_symbols)

Sample a pilot symbol sequence.

Parameters: num_symbols (int) – The expected number of symbols within the sequence.
Return type: ndarray
Returns: A pilot symbol sequence of length num_symbols.
Raises: RuntimeError – If a repetition of the symbol sequence is required but not allowed.

1: Ali A. Nasir, Salman Durrani, Hani Mehrpouyan, Steven D. Blostein, and Rodney A. Kennedy. Timing and carrier synchronization in wireless communication systems: a survey and classification of research in the last 5 years. EURASIP Journal on Wireless Communications and Networking, 2016(1):180, 2016. doi:10.1186/s13638-016-0670-9.