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.