Communication Waveform Base

class WaveformType

Type hint for waveform generator classes.

alias of TypeVar(‘WaveformType’, bound=WaveformGenerator)

class Synchronization(waveform_generator=None)

Bases: Generic[WaveformType], ABC, 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_blacklist: Set[str] = {'waveform_generator'}

Set of properties to be ignored during serialization.

property waveform_generator: WaveformType | None

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)

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.

Return type:

List[int]

Returns:

List of time indices indicating the first samples of frames detected in signal.

Raises:

RuntimeError – If the synchronization routine is floating

class ChannelEstimation(waveform_generator=None)

Bases: Generic[WaveformType], Serializable

Base class for channel estimation routines of waveform generators.

Parameters:

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

yaml_tag: Optional[str] = 'NoChannelEstimation'

YAML serialization tag.

property_blacklist: Set[str] = {'waveform_generator'}

Set of properties to be ignored during serialization.

property waveform_generator: WaveformType | None

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(symbols)

Estimate the wireless channel of a received communication frame.

Parameters:

symbols (Symbols) – Demodulated communication symbols.

Return type:

Tuple[StatedSymbols, ChannelStateInformation]

Returns: The symbols and their respective channel states.

class IdealChannelEstimation(waveform_generator=None)

Bases: Generic[WaveformType], ChannelEstimation[WaveformType]

Channel estimation accessing the ideal channel state informaion.

This type of channel estimation is only available during simulation runtime.

Parameters:

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

yaml_tag: Optional[str] = 'IdealChannelEstimation'

YAML serialization tag.

class ChannelEqualization(waveform_generator=None)

Bases: Generic[WaveformType], ABC, Serializable

Abstract base class for channel equalization routines of waveform generators.

Parameters:

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

yaml_tag: Optional[str] = 'NoEqualization'

YAML serialization tag.

property_blacklist: Set[str] = {'waveform_generator'}

Set of properties to be ignored during serialization.

property waveform_generator: WaveformType | None

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(stated_symbols)

Equalize the wireless channel of a received communication frame.

Parameters:

frame (Symbols) – Symbols and channel state of the received communication frame.

Return type:

Symbols

Returns: The equalize symbols.

class ZeroForcingChannelEqualization(waveform_generator=None)

Bases: Generic[WaveformType], ChannelEqualization[WaveformType], Serializable

Zero-Forcing channel equalization for arbitrary waveforms.

Parameters:

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

yaml_tag: Optional[str] = 'ZeroForcing'

YAML serialization tag

equalize_channel(symbols)

Equalize the wireless channel of a received communication frame.

Parameters:

frame (Symbols) – Symbols and channel state of the received communication frame.

Return type:

Symbols

Returns: The equalize symbols.

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

Bases: ABC, Serializable

Implements an abstract waveform generator.

Implementations for specific technologies should inherit from this class.

Waveform Generator initialization.

Parameters:

• modem (BaseModem, 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.

property_blacklist: Set[str] = {'modem'}

Set of properties to be ignored during serialization.

symbol_type

Symbol type.

alias of complex128

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.

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.

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

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)

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.

Return type:

Symbols

Returns:

The demodulated communication symbols

estimate_channel(frame)

Return type:

Tuple[StatedSymbols, ChannelStateInformation]

equalize_symbols(symbols)

Return type:

Symbols

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.

Returns:

Bits per second.

property modem: BaseModem | None

Access the modem this generator is attached to.

Returns: A handle to the modem.

property synchronization: Synchronization

Synchronization routine.

Returns:

Handle to the synchronization routine.

Return type:

Synchronization

property channel_estimation: ChannelEstimation

Channel estimation routine.

Returns:

Handle to the estimation routine.

Return type:

ChannelEstimation

property channel_equalization: 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

property symbol_precoding_support: bool

Flag indicating if this waveforms supports symbol precodings.

Returns: Boolean support flag.

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

Bases: WaveformGenerator, ABC

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

Waveform Generator initialization.

Parameters:

• modem (BaseModem, 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: Signal

Model of the pilot sequence within this communication waveform.

Returns:

The pilot sequence.

Return type:

Signal

class PilotSymbolSequence

Bases: ABC

Abstract base class for pilot sequences.

abstract property sequence: ndarray

The scalar sequence of pilot symbols.

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

Returns:

The symbol sequence.

class UniformPilotSymbolSequence(pilot_symbol=1 + 0j)

Bases: 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: ndarray

The scalar sequence of pilot symbols.

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

Returns:

The symbol sequence.

class CustomPilotSymbolSequence(pilot_symbols)

Bases: 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: ndarray

The scalar sequence of pilot symbols.

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

Returns:

The symbol sequence.

class MappedPilotSymbolSequence(mapping)

Bases: CustomPilotSymbolSequence

Pilot symbol sequence derived from a mapping.

Parameters:

mapping (PskQamMapping) – Mapping from which the symbols pilot symbols should be inferred

class ConfigurablePilotWaveform(symbol_sequence=None, repeat_symbol_sequence=True, **kwargs)

Bases: PilotWaveformGenerator, 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.

• **kwargs – Additional WaveformGenerator initialization parameters.

pilot_symbol_sequence: 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.