Waveform

The module waveform.py implements the Waveform class which encapsulates a time-domain signal transmitted from a set of transmitter antenna or received by a set of receiver antenna. A waveform object is usually created by applying OFDM modulation to a resource grid object. See ofdmModulate() method of the Grid class for more information.

class neoradium.waveform.Waveform(waveform, noiseVar=0)

This class encapsulates a set of sequences of complex values representing the time-domain signals as transmitted by each transmitter antenna or as received by each receiver antenna. A Waveform object is usually created by applying OFDM modulation to a resource grid.

Once you have a Waveform object, you can apply a channel model to it, add AWGN noise to it, or apply other signal processing tasks such as windowing. All of these processes result in new Waveform objects.

At the receiver the received signals are usually converted back to the frequency domain by applying OFDM demodulation, which results in a Grid object representing the received resource grid.

Parameters:

waveform (2D complex numpy array) – An P x Ns 2D complex numpy array representing a set of time-domain signals of length Ns for each one of P antenna elements. The value P is equal to Nt the number of transmitter antenna when this is a transmitted signal and equal to Nr the number of receiver antenna when this is a received signal.
noiseVar (float (default: 0)) – The variance of the noise applied to the time-domain signals in this Waveform object. This is usually initialized to zero. When an AWGN noise is applied to the waveform using the addNoise() function, the variance of the noise is saved in the Waveform object.

Other Read-Only Properties:

shape:

Returns the shape of the 2-dimensional waveform numpy array.

numPorts:

The number of transmitter or receiver antenna (P) for this waveform.

length:

The length of the time-domain signal in number of samples (Ns).

print(indent=0, title=None, getStr=False)

Prints the properties of this Waveform object.

Parameters:

indent (int (default: 0)) – The number of indentation characters.
title (str or None (default: None)) – If specified, it is used as a title for the printed information.
getStr (Boolean (default: False)) – If True, it returns the information in a text string instead of printing the information.

Returns:

If the getStr parameter is True, then this function returns the information in a text string. Otherwise, nothing is returned.

Return type:

None or str

addNoise(**kwargs)

Adds Additive White Gaussian Noise (AWGN) to this waveform based on the given noise properties. The noisy waveform is then returned in a new Waveform object.

This is to some extent similar to the addNoise() method of the Grid class which applies noise in frequency domain.

Parameters:

kwargs (dict) –

One of the following parameters must be specified. They specify how the noise signal is generated.

noise:

A numpy array with the same shape as this Waveform object containing the noise information. If the noise information is provided by noise it is added directly to the waveform. In this case all other parameters are ignored.

noiseStd:

The standard deviation of the noise. An AWGN complex noise signal is generated with zero-mean and the specified standard deviation. If noiseStd is specified, noiseVar, snrDb, and nFFT values below are ignored.

noiseVar:

The variance of the noise. An AWGN complex noise signal is generated with zero-mean and the specified variance. If noiseVar is specified, the values of snrDb and nFFT are ignored.

snrDb:

The signal to noise ratio in dB. First the noise variance is calculated using the given SNR value and the nFFT value. Then an AWGN complex noise signal is generated with zero-mean and the calculated variance. Please note that if an SNR value is used to specify the amount of noise, the value of nFFT should also be provided.

nFFT:

This is only used if snrDb is specified. It is the length of Fast Fourier Transform that is applied to the signals for time/frequency domain conversion. This value is usually available from the BandwidthPart object being used for the transmission. This function uses the following formula to calculate the noise variance \(\sigma^2_{AWGN}\) from \(snrDb\) and \(nFFT\) values:

\[\sigma^2_{AWGN} = \frac 1 {N_r.nFFT.10^{\frac {snrDb} {10}}}\]

where \(N_r\) is the number of receiver antenna.

ranGen:

If provided, it is used as the random generator for the AWGN generation. Otherwise, if this is not specified, NeoRadium’s global random generator is used.

Returns:

A new Waveform object containing the noisy version of this waveform.

Return type:

Waveform

pad(numPad)

Appends a sequence of numPad zeros to the end of time-domain signals in this Waveform object.

To make sure a signal is received in its entirety when it goes through a channel model, we usually need to pad zeros to the end of the time-domain signal. The number of these zeros usually depend on the maximum channel delay. The function getMaxDelay() of the channel model can be used to get the number of padded zeros.

Parameters:: numPad (int) – The number of time-domain zero samples to be appended to the end of this waveform.
Returns:: A new Waveform object which is numPad samples longer than the original waveform.
Return type:: Waveform

sync(timingOffset)

Removes timingOffset values from the beginning of the time-domain signals in this Waveform object. This effectively shifts the signal in time domain by timingOffset samples.

When a time-domain signal goes through a channel model, it is delayed in time because of the propagation delay. Different transmission paths may be affected by different propagation delays. The function getTimingOffset() can be used to obtain the overall propagation delay given by timingOffset. In practice this value is calculated by finding the time-domain sample index where the correlation between the received signal and a set of reference signals is at its maximum. See for example the function estimateTimingOffset() of the Grid class.

Parameters:: timingOffset (int) – The number of time-domain samples that are removed from the beginning of the time-domain signals in this Waveform object.
Returns:: A new Waveform object which is timingOffset samples shorter than the original waveform.
Return type:: Waveform

applyChannel(channel)

Applies the channel model channel to this Waveform object and returns a new Waveform object representing the received signal. This function internally calls the applyToSignal() method of the channel model passing in this waveform object as the inputSignal.

Parameters:: channel (ChannelBase) – The channel model that is applied to this time-domain waveform.
Returns:: A new Waveform object which represents the received time-domain waveform.
Return type:: Waveform

applyWindowing(cpLens, windowing, bwp)

This is a helper function that is used to apply windowing to the OFDM waveform obtained from OFDM modulation of a resource grid.

This method supports several different windowing approaches including the ones specified in 3GPP TS 38.104, Sections B.5.2 and C.5.2.

You usually do not need to call this function directly. It is called internally at the end of the OFDM modulation process when the function ofdmModulate() of the Grid class is called.

Parameters:

cpLens (list) – A list of integer values each representing the length of cyclic prefix part at the beginning of each OFDM symbol in number of time-domain samples. This list can be obtained from the BandwidthPart object.
windowing (str) –
A text string specifying how the window length is obtained. It can be one the following:

”STD”:

The windowing size is determined based on 3GPP TS 38.104, Sections B.5.2 and C.5.2.

Ratio as percentage:

A windowing ratio can be specified as a percentage value. For example the text string “%25” represents a windowing ratio of 0.25. The window length is calculated as the minimum value of cpLens multiplied by the windowing ratio and rounded to the nearest integer value.

Ratio:

A windowing ratio (between 0 and 1) can be specified as a number. For example the text string “0.125” represents a windowing ratio of 0.125. The window length is calculated as the minimum value of cpLens multiplied by the windowing ratio and rounded to the nearest integer value.

Window Length:

The actual window length can also be specified as an integer value. For example the text string “164” represents a window length equal to 164.
bwp (BandwidthPart) – The bandwidth part used for the communication.

Returns:

A new Waveform object which represents the waveform after applying the windowing.

Return type:

Waveform

ofdmDemodulate(bwp, f0=0, cpOffsetRatio=0.5)

Applies OFDM demodulation to the waveform which results in a frequency-domain resource grid returned as a Grid object.

If an AWGN noise was applied to the waveform using the addNoise() method, then the amount of noise is transferred to the Grid object that is created. The noise variance of the returned resource grid is equal to the waveform’s noise variance times nFFT.

Parameters:

bwp (BandwidthPart) – The bandwidth part used for the communication.
f0 (float (default: 0)) – The carrier frequency of the waveform. If it is 0 (default), then a baseband waveform is assumed. This should match the value originally used when applying OFDM modulation at the transmitter side. See the ofdmModulate() method of the Grid class.
cpOffsetRatio (float (default: 0.5)) – This value determines where in the cyclic prefix (Ratio from the beginning of CP), should we start applying FFT. The default value of 0.5 means the starting sample for applying FFT is the mid point in the cyclic prefix.

Returns:

A Grid object representing the received resource grid.

Return type:

Grid