Channel Models

NeoRadium currently supports Clustered Delay Line (CDL) and Tapped Delay Line (TDL) channel models implemented as CdlChannel and TdlChannel classes correspondingly. You can also derive your customized channel models from the ChannelBase class explained below.

This module implements the base class for channel models. Currently CDL and TDL channel models are available in NeoRadium both of which are derived from the ChannelBase class in this module. For more details about these subclasses please refer to CdlChannel or TdlChannel.

class neoradium.channel.ChannelBase(**kwargs)

This is the base channel model class that handles higher level processing such as application to time-domain waveforms (Waveforms) or frequency-domain resource grids (Grid).

This class also provides the getChannelMatrix() function that calculates and returns the “Channel Matrix” for the channel model.

Almost all of interactions with channel models are done using the methods of this class. The derived classes mostly implement the lower level processes such as how the channel multi-path information are generated or how MIMO antenna arrays are processed in connection with the channel multi-path properties.

Parameters:

kwargs (dict) –

A set of optional arguments.

delaySpread:

The delay spread in nanoseconds. The default is 30 ns. It can also be a string containing one of the values in following table (See 3GPP TR 38.901 table 7.7.3-1)

Delay Spread str

Delay spread

’VeryShort’

10 ns

’Short’

30 ns

’Nominal’

100 ns

’Long’

300 ns

’VeryLong’

1000 ns
dopplerShift:

The maximum doppler shift in Hz. The default is 40 Hz (corresponding to a speed of about 10 km/h). A value of zero makes the channel model static.

carrierFreq:

The carrier frequency of the channel model in Hz. The default is 3.5 GHz.

normalizeGains:

A boolean flag. The default is True. If True, the path gains are normalized before being applied to the signals.

normalizeOutput:

A boolean flag. The default is True. If True, the gains are normalized based on the number of receive antenna.

txDir:

The transmission direction. The default is “Downlink”. This is a string and must be one of “Downlink” or “Uplink”.

kFactor:

The K-Factor (in dB) used for scaling. The default is None. If not specified (kFactor=None), K-factor scaling is disabled.

timing:

A text string that specifies the way channel values are interpolated in time. It can be one of the following values.

  • ’polar’: The channel values are converted to polar coordinates before being linearly interpolated.

  • ’linear’: The channel values are interpolated linearly.

  • ’nearest’: A nearest neighbor interpolation is used.

  • ’matlab’: Use this only when comparing the results with Matlab’s 5G toolkit for debugging and diagnostics purposes.

filterDelay:

The delay used by the channel filter class (ChannelFilter). The default is 7 sample.

stopBandAtten:

The Stop-band attenuation value (in dB) used by the channel filter class (ChannelFilter). The default is 80 dB.

seed:

The seed used for by the random functions in the channel model. Set this to a fixed value so that the channel model creates repeatable results. The default is None which means this channel model uses the NeoRadium’s global random generator.

Other Properties:

All of the parameters mentioned above are directly available. Here is a list of additional properties.

coherenceTime:

The Coherence time of the channel model in seconds.

channelFilter:

The (ChannelFilter) object used by this channel model.

sampleRate:

The sample rate used by this channel model. For 3GPP standard, this is set to 30,720,000 samples per second.

curTime:

The current time for this channel. This starts at zero when the channel is created and is increased each time the goNext() function is called.

print(indent, title, getStr)

Prints the properties of this channel model 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

restart(restartRanGen=False)

Resets the state of this channel model to the initial state. Sets current time to zero and resets the channel filter.

Parameters:

restartRanGen (Boolean (default: False)) – If a seed was not provided to this channel model, this parameter is ignored. Otherwise, if restartRanGen is set to True, this channel model’s random generator is reset and if restartRanGen is False (default), the random generator is not reset. This means if restartRanGen is False, calling this function starts a new sequence of channel instances which are different from the sequence when the channel was instantiated.

goNext()

This method is called after each application of the channel to a signal. It advances the current time value and updates the channel filter state making the channel model ready for the next application in time.

getMaxDelay()

Calculates and returns the maximum delay of this channel model in time-domain samples.

Returns:

The maximum delay of this channel model in number of time-domain samples.

Return type:

int

applyToGrid(grid)

Applies this channel model to the transmitted resource grid object specified by grid in frequency domain and returns the received resource grid in a new Grid object. This function first calls the getChannelMatrix() function to get the channel matrix and then calls the applyChannel() method of the Grid class to get the received resource grid.

Parameters:

grid (Grid) – The transmitted resource grid. It is an Nt x L x K Grid object where Nt is the number of transmit antenna, L is the number OFDM symbols, and K is the number of subcarriers in the resource grid.

Returns:

A resource grid containing the received signal information. It is an Nr x L x K Grid object where Nr is the number of receive antenna, L is the number OFDM symbols, and K is the number of subcarriers in the resource grid.

Return type:

Grid

applyToSignal(inputSignal, keepNt=False)

Applies this channel model to the time-domain Waveform specified by inputSignal and returns another Waveform object containing the received signal in time domain.

Parameters:

  • inputSignal (Waveform) – The transmitted time-domain waveform. It is an Nt x Ns Waveform object where Nt is the number of transmit antenna and Ns is the number of time samples in the transmitted waveform.

  • keepNt (Boolean (default: False)) – This should always be set to False. It is only set to True when it is used internally to calculate a channel matrix.

Returns:

A Waveform object containing the received signal. It is an Nr x Ns Waveform object where Nr is the number of receive antenna and Ns is the number of time samples in the received waveform.

Return type:

Waveform

getChannelMatrix(bwp, numSlots=1, timeDomain=True, interpolateTime=False)

Calculates and returns the channel matrix of this channel model. The channel matrix is a 4-D L x K x Nr x Nt complex numpy array where L is the number of OFDM symbols, K is the number of subcarriers, Nr is the number of receive antenna, and Nt is the number of transmit antenna.

Parameters:

  • bwp (BandwidthPart) – The bandwidth part object used to get information about the shape of the channel matrix, the timing information about OFDM symbols, and the FFT size.

  • numSlots (int) – The number slots. This is used to determine the number of OFDM symbols L. This function can create channel matrixes at slot boundaries. In other words L is always a multiple of bwp.symbolsPerSlot.

  • timeDomain (Boolean (default: True)) –

    Calculate the channel matrix in time domain. NeoRadium can calculate the channel matrix in both time domain and frequency domain.

    The time-domain calculation provides results that are closer to the effect of applying the channel in time domain to an OFDM-modulated waveform.

    The frequency domain method calculates the channel matrix directly using the multi-path information.

  • interpolateTime (Boolean (default: False)) –

    This parameter is only used when timeDomain=True.

    If set to True the path gains are first calculated at the sampling times based on the current dopplerShift parameter of this channel model. These gains are then upsampled (Interpolated) using the method specified by the timing property of this channel model. This is usually slower and results in a less accurate channel matrix.

    If set to False (the default) the path gains are calculated directly at the OFDM symbol times and there is no need for interpolation.

Returns:

A 4-D L x K x Nr x Nt complex numpy array where L is the number of OFDM symbols, K is the number of subcarriers, Nr is the number of receive antenna, and Nt is the number of transmit antenna.

Return type:

4-D complex numpy array

getTimingOffset(numSamples=3072)

This function calculates the timing offset used in synchronization of a received time-domain signal. It first calculates the Channel Impulse Response (CIR) and then uses it to find the index of the maximum power.

Parameters:

numSamples (int (default: 3072)) – The number of time-domain samples to consider when calculating the CIR. The default value of 3072 is equivalent to the duration of one sub-frame (1 millisecond) which works for most situations. When a time-domain signal is available, the actual number of samples could be used for this parameter.

Returns:

The time-domain offset value used for synchronization of a received waveform. This return value can be directly passed to the sync() function to synchronize a received waveform.

Return type:

int

getPathGains(channelTimes=None)

This function calculates the path gains of this channel at the times specified by the channelTimes. The returned value is a 4-D tensor of shape (len(channelTimes) x nr x nt x np). The path gains are normalized based on the normalizeOutput and normalizeGains values (See ChannelBase)

Parameters:

channelTimes (numpy array or None (default: None)) – This is a 1-D list of the times at which the path gains are calculated. If this is None, then the path gains are calculated for current time (See curTime in ChannelBase).

Returns:

The path gains at the specified times. The shape of returned tensor is (len(channelTimes) x nr x nt x np).

Return type:

4-D complex numpy array

getPathFilters()

This function returns the channel filter coefficients for each path. It can be used with the path gains obtained by the getPathGains() function to calculate Channel Impulse Response (CIR).

Returns:

The p’th row of the returned matrix contains the filter coefficients of the p’th path. Please note that different paths may have different number of filter coefficients. The number of columns in the returned matrix is equal to maximum number of filter coefficients for all the paths. The rows are zero-padded at the end if the actual number of filter coefficients is less than the number of columns.

Return type:

2-D numpy array

CDL Channel Model

This module implements the CdlChannel class which encapsulates the Clustered Delay Line (CDL) channel model functionality.

class neoradium.cdl.CdlChannel(profile='A', **kwargs)

This class implements the Clustered Delay Line (CDL) channel model based on 3GPP TR 38.901. It is derived from the ChannelBase class.

All of API functions used in most typical use cases are explained in the documentation of ChannelBase class.

The typical use case involves instantiating a CdlChannel object and then calling functions such as getChannelMatrix(), applyToSignal(), applyToGrid(), etc.

Parameters:

  • profile (str or None (default: 'A')) – The CDL profile. It can be one of ‘A’, ‘B’, ‘C’, ‘D’, ‘E’, or None. See 3GPP TR 38.90 section 7.7.1 for more information. Use None to indicate a customized version of CDL channel (See Customizing CDL Model).

  • kwargs (dict) –

    A set of optional arguments. Please refer to ChannelBase for a list of inherited parameters. Here is a list of additional parameters specific to CdlChannel.

    ueDirAZ:

    This is a list of 2 angles for the Azimuth and Zenith of the UE’s direction of movement in degrees. The default is [0, 90] which indicates moving along the x-axis. In this version, the base station is assumed to be stationary.

    txAntenna:

    The transmitter antenna. This must be an instance of AntennaPanel or AntennaArray class.

    rxAntenna:

    The receiver antenna. This must be an instance of AntennaPanel or AntennaArray class.

    txOrientation:

    The orientation of transmitter antenna. This is a list of 3 angle values in degrees for the bearing angle \(\alpha\), down-tilt angle \(\beta\), and slant angle \(\gamma\). The default is [0,0,0]. Please refer to 3GPP TR 38.901 Section 7.1.3 for more information.

    rxOrientation:

    The orientation of receiver antenna. This is a list of 3 angle values in degrees for the bearing angle \(\alpha\), down-tilt angle \(\beta\), and slant angle \(\gamma\). The default is [0,0,0]. Please refer to 3GPP TR 38.901 Section 7.1.3 for more information.

    xPolPower:

    The Cross Polarization Power in db. The default is 10db. For more details please refer to Step 3 in 3GPP TR 38.901 Section 7.7.1.

    angleScaling:

    The Angle Scaling parameters. If specified, it must be a tuple of 2 numpy arrays.

    The first item specifies the angle scaling mean values. It is a 1-D numpy array of 4 values corresponding to the Azimuth of Departure, Azimuth of Arrival, Zenith of Departure, and Zenith of Arrival angles.

    The second item specifies the RMS angle spread values. It is a 1-D numpy array of 4 values corresponding to the Azimuth of Departure, Azimuth of Arrival, Zenith of Departure, and Zenith of Arrival angles. If this is set to None (the default), the Angle Scaling is disabled. For more information please see Angle Scaling below.

    If this is set to None (the default), the Angle Scaling is disabled.

    pathDelays:

    Use this to customize or override the path delays which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    pathPowers:

    Use this to customize or override the path powers which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    aods:

    Use this to customize or override the Azimuth of Departure angles which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    aoas:

    Use this to customize or override the Azimuth of Arrival angles which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    zods:

    Use this to customize or override the Zenith of Departure angles which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    zoas:

    Use this to customize or override the Zenith of Arrival angles which by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    angleSpreads:

    Use this to customize or override the RMS Angle spread (in degrees) which is used to normalized angles. This a list of 4 values corresponding to the Azimuth of Departure, Azimuth of Arrival, Zenith of Departure, and Zenith of Arrival angles. These values by default are set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    Please note that this should not be confused with angle spread values used for angle scaling.

    hasLos:

    Use this to customize or override the hasLos property of this channel model which by default is set based on the CDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information.

    kFactorLos:

    Use this when customizing the CDL model. This is the K-Factor ratio (in dB) for the LOS cluster (1st cluster). You don’t need to specify this parameter for most use cases. See Customizing CDL Model below for more information. When customizing the CDL model, this value by default is set to the difference of path powers (in dB) for the first and second clusters.

Other Properties:

All of the parameters mentioned above are directly available. Please also refer to the ChannelBase class for a list of inherited properties. Here is a list of additional properties specific to this class.

nrNt:

A tuple of the form (nr,nt), where nr and nt are the number receiver and transmitter antenna elements correspondingly.

rayCoupling:

This property is used internally for ray coupling. See Step 2 in 3GPP TR 38.901 Section 7.7.1 for more details.

initialPhases:

The random initial phases used when creating channel gains. See Step 10 in 3GPP TR 38.901 Section 7.5 for more details.

Note

All of the angle values are provided to this class in degrees. Internally, this class uses radian values for all the calculations. So, when you access any of the angle values such as aods, aoas, zods, and zoas, remember that they are in radians.

Angle Scaling:

If angleScaling is set to None, the angle scaling is disabled. Otherwise, angle scaling is applied to all angles of arrival and departure for all clusters according to 3GPP TR 38.901 Section 7.7.5.1 and Annex A.

Customizing CDL Model:

There are two different ways to customize the CDL model:

  1. You can choose one of the predefined CDL profiles (A, B, C, D, or E) and then modify the parameters of the model by passing in additional information. For example you can choose CDL-B model and then pass your own path delays to override the path delays specified in the standard.

  2. You can also create your own model completely from scratch. You first pass None for the profile parameter and then specify all channel model parameters. Please note that you must specify at least the following parameters in this case:

    • pathDelays

    • pathPowers

    • aods

    • aoas

    • zods

    • zoas

    • hasLos

    You can also optionally specify the following values:

    • angleSpreads (defaults to [4.0, 10.0, 2.0, 2.0] if not specified)

    • kFactorLos (defaults to pathPowers[0]-pathPowers[1])

    Also note that if your channel model contains a LOS cluster, it must be the first cluster in the lists and the hasLos parameter should be set to True.

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

Prints the properties of this channel model object. It first calls the base class print() and then adds the information specific to CdlChannel class.

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

restart(restartRanGen=False)

This method first calls the base class restart() and then re-initializes the ray coupling and initial phases randomly.

Parameters:

restartRanGen (Boolean (default: False)) – If a seed was not provided to this channel model, this parameter is ignored. Otherwise, if restartRanGen is set to True, this channel model’s random generator is reset and if restartRanGen is False (default), the random generator is not reset. This means if restartRanGen is False, calling this function starts a new sequence of channel instances which are different from the sequence when the channel was instantiated.

TDL Channel Model

This module implements the TdlChannel class which encapsulates the Tapped Delay Line (TDL) channel model functionality.

class neoradium.tdl.TdlChannel(profile='A', **kwargs)

This class implements the Tapped Delay Line (TDL) channel model based on 3GPP TR 38.901. It is derived from the ChannelBase class.

According to 3GPP TR 38.901, TDL models are mostly used for simplified evaluations, for non-MIMO cases. They are defined for the frequency range from 0.5 GHz to 100 GHz with a maximum bandwidth of 2 GHz.

Although TDL model is defined for mostly non-MIMO use cases, this implementation does support MIMO configs. However, unlike CdlChannel, this model does not work with the antenna classes AntennaPanel or AntennaArray. For TDL channel models, you just need to specify the number of transmit and receive antenna.

The typical use case involves instantiating a TdlChannel object and then calling functions such as getChannelMatrix(), applyToSignal(), applyToGrid(), etc.

Parameters:

  • profile (str or None (default: 'A')) –

    The TDL profile name. It can be one of the following:

    • The TDL profile which is one of ‘A’, ‘B’, ‘C’, ‘D’, ‘E’.

    • A string that specifies both profile and delay spread according to 3GPP TS 38.101-4: ‘A30’, ‘B100’, ‘C60’, ‘C300’, ‘D30’. The numbers here are the delay spread in nano seconds. Please note that the delay spread specified here overrides any value passed to the delaySpread parameter (See ChannelBase)

    • A string that specifies profile, delay spread, and doppler shift according to 3GPP TS 38.101-4 Table B.2.2-1 and 3GPP TS 38.101-4 Table B.2.2-2. This includes ‘A30-5’, ‘A30-10’, ‘B100-400’, ‘C300-100’, ‘C300-600’, ‘C300-1200’, for FR1, and ‘A30-35’, ‘A30-75’, ‘A30-300’, ‘C60-300’, ‘D30-75’ for FR2. Please note that the delay spread and doppler shift specified here overrides any values passed to the delaySpread and dopplerShift parameters (See ChannelBase)

    • None can be used to completely customize the TDL channel. See Customizing TDL Model below for more information.

  • kwargs (dict) –

    A set of optional arguments. Please refer to ChannelBase for a list of inherited parameters. Here is a list of additional parameters specific to TdlChannel.

    txAntennaCount:

    The number of transmitter antenna. Isotropic antenna elements are assumed. The default is 1.

    rxAntennaCount:

    The number of receiver antenna. Isotropic antenna elements are assumed. The default is 1.

    mimoCorrelation:

    Specifies the relative amount of MIMO correlation in MIMO use cases. It can be one of ‘Low’ (default), ‘Medium’, ‘MediumA’, ‘MediumB’, and ‘High’. See Calculating Correlation Matrix for more information.

    polarization:

    The polarization type for the MIMO use cases. It can be one of ‘CoPolar’(default) or ‘CrossPolar’. See Calculating Correlation Matrix for more information.

    correlationMatrix:

    The correlation matrix. By default this implementation calculates the correlation matrix based on 3GPP standard using the given parameters such as mimoCorrelation and polarization. However you can specify your own correlation matrix using this parameter. See Calculating Correlation Matrix for more information.

    sosType:

    The TDL model uses the Sum-of-Sinusoids method to calculate the channel gains. This implementation supports 2 different variations of this technique:

    sosNumSins:

    The number of Sinusoids used in the Sum-of-Sinusoids algorithm. The default is 32.

    pathDelays:

    Use this to customize or override the path delays which by default are set based on the TDL channel model as defined in 3GPP TR 38.901 Tables Tables 7.7.2-1 to Table 7.7.2-5. You don’t need to specify this parameter for most use cases. See Customizing TDL Model below for more information.

    pathPowers:

    Use this to customize or override the path powers which by default are set based on the TDL channel model as defined in 3GPP TR 38.901 Tables Tables 7.7.2-1 to Table 7.7.2-5. You don’t need to specify this parameter for most use cases. See Customizing TDL Model below for more information.

    kFactorLos:

    The K-Factor ratio (in dB) for the LOS tap (1st tap). this value by default is set to (pathPowers[0]-pathPowers[1]).

    hasLos:

    Use this to customize or override the hasLos property of this channel model which by default is set based on the TDL channel model as defined in 3GPP TR 38.901. You don’t need to specify this parameter for most use cases. See Customizing TDL Model below for more information.

Other Properties:

All of the parameters mentioned above are directly available. Please also refer to the ChannelBase class for a list of inherited properties. Here is a list of additional properties specific to this class.

nrNt:

A tuple of the form (nr,nt), where nr and nt are the number receiver and transmitter antenna elements correspondingly. For TDL models, nr and nt are the same as rxAntennaCount and nt=txAntennaCount`` parameters.

Calculating Correlation Matrix:

For MIMO use cases, by default, this class uses the parameters such as mimoCorrelation and polarization to calculate the correlation matrix based on the 3GPP standard documents. This implementation is based on the following documents:

  • 3GPP TS 38.101-4 Section B.2.3.2.1

  • 3GPP TS 38.101-4 Tables B.2.3.1.2-1 and B.2.3.2.2-1

  • 3GPP TS 38.104 Tables G.2.3.1.2-1 and G.2.3.2.3-1

Customizing TDL Model:

There are two different ways to customize the TDL model:

  1. You can choose one of the predefined TDL profiles (See the profile parameter above) and then modify the parameters of the model by passing in additional information. For example you can choose ‘B100-400’ for profile and then pass your own path delays to override the path delays specified in the standard.

  2. You can also define your own model completely from scratch. You first pass None for the profile parameter and then specify all channel model parameters. Please note that you must specify at least the following parameters in this case:

    • pathDelays

    • pathPowers

    • hasLos

    You can also optionally specify the following values:

    • kFactorLos (defaults to pathPowers[0]-pathPowers[1])

    Also note that if your channel model contains a LOS tap, it must be the first tap in the lists and the hasLos parameter should be set to True.

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

Prints the properties of this channel model object. It first calls the base class print() and then adds the information specific to TdlChannel class.

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