Receiver algorithms

This module contains a number of receiver algorithms implemented in cuPHY, thus using GPU acceleration.

class aerial.phy5g.algorithms.channel_estimator.ChannelEstimator

Channel estimator class.

This class implements traditional MMSE-based channel estimation on the DMRS symbols of the received slot signal. It outputs the channel estimates for all resource elements in the DMRS symbols. Similarly to many other classes in pyAerial, this class handles groups of UEs sharing the same time-frequency resources with one call, i.e. it supports MU-MIMO.

__init__(

num_rx_ant,

ch_est_algo=1,

enable_per_prg_chest=0,

enable_ul_rx_bf=0,

cuda_stream=None,

chest_filter_h5=None,

w_freq_array=None,

w_freq4_array=None,

w_freq_small_array=None,

shift_seq_array=None,

unshift_seq_array=None,

shift_seq4_array=None,

unshift_seq4_array=None,

)

Initialize ChannelEstimator.

The channel estimation filters can be given as an H5 file or directly as Numpy arrays. If neither is given, the channel estimator is using default filters.

Parameters:

• num_rx_ant (int) – Number of receive antennas.

• ch_est_algo (int) –

  Channel estimation algorithm.

  • 0 - MMSE

  • 1 - Multi-stage MMSE with delay estimation (default)

  • 2 - RKHS not supported by pyAerial yet

  • 3 - LS channel estimation only

• enable_per_prg_chest (int) –

  Enable/disable PUSCH per-PRG channel estimation.

  • 0: Disable (default).

  • 1: Enable.

• enable_ul_rx_bf (int) –

  Enable/disable beamforming for PUSCH.

  • 0: Disable (default).

  • 1: Enable.

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

• chest_filter_h5 (str) – Filename of an HDF5 file containing channel estimation filters.

• w_freq_array (np.ndarray)

• w_freq4_array (np.ndarray)

• w_freq_small_array (np.ndarray)

• shift_seq_array (np.ndarray)

• unshift_seq_array (np.ndarray)

• shift_seq4_array (np.ndarray)

• unshift_seq4_array (np.ndarray)

Return type:

None

estimate(

*,

rx_slot,

slot,

pusch_configs=None,

num_ues=None,

num_dmrs_cdm_grps_no_data=None,

dmrs_scrm_id=None,

start_prb=None,

num_prbs=None,

prg_size=None,

num_ul_streams=None,

dmrs_syms=None,

dmrs_max_len=None,

dmrs_add_ln_pos=None,

start_sym=None,

num_symbols=None,

scids=None,

layers=None,

dmrs_ports=None,

)

Run channel estimation for multiple UE groups.

This runs the cuPHY channel estimation for all UE groups included in pusch_configs. If this argument is not given, all the other arguments need to be given and cuPHY channel estimation is run only for a single UE group sharing the same time-frequency resources, i.e. having the same PRB allocation, and the same start symbol and number of allocated symbols. This single UE group is the parameterized by the all other arguments.

The method can be called using either Numpy or CuPy arrays. In case the input arrays are located on the GPU (CuPy), the output will be on the GPU (CuPy). So the return type shall be the same as used for rx_slot when calling the method.

Parameters:

• rx_slot (Array) – Input received data as a frequency x time x Rx antenna Numpy or CuPy array with type complex64 entries.

• slot (int) – Slot number.

• pusch_configs (List[PuschConfig]) – List of PUSCH configuration objects, one per UE group. If this argument is given, the rest are ignored. If not given, all other arguments need to be given (only one UE group supported in that case).

• num_ues (int) – Number of UEs in the single UE group.

• num_dmrs_cdm_grps_no_data (int) – Number of DMRS CDM groups without data [3GPP TS 38.212, sec 7.3.1.1]. Value: 1->3.

• dmrs_scrm_id (int) – DMRS scrambling ID.

• start_prb (int) – Start PRB index of the UE allocation.

• num_prbs (int) – Number of allocated PRBs for the UE group.

• prg_size (int) – The Size of PRG in PRB for PUSCH per-PRG channel estimation.

• num_ul_streams (int) – The number of active streams for this PUSCH.

• dmrs_syms (List[int]) – For the UE group, a list of binary numbers each indicating whether the corresponding symbol is a DMRS symbol. The length of the list equals the number of symbols in the slot. 0 means no DMRS in the symbol and 1 means the symbol is a DMRS symbol.

• dmrs_max_len (int) – The maxLength parameter, value 1 or 2, meaning that DMRS are single-symbol DMRS or single- or double-symbol DMRS.

• dmrs_add_ln_pos (int) – Number of additional DMRS positions.

• start_sym (int) – Start symbol index for the UE group allocation.

• num_symbols (int) – Number of symbols in the UE group allocation.

• scids (List[int]) – DMRS sequence initialization SCID [TS38.211, sec 7.4.1.1.2] for each UE in the UE group. Value is 0 or 1.

• layers (List[int]) – Number of layers for each UE in the UE group. The length of the list equals the number of UEs.

• dmrs_ports (List[int]) – DMRS ports for each UE in the UE group. The format of each entry is in the SCF FAPI format as follows: A bitmap (mask) starting from the LSB where each bit indicates whether the corresponding DMRS port index is used.

Returns:

The channel estimates as a Rx ant x layer x frequency x time Numpy or CuPy array, per UE group.

Return type:

List[Array]

class aerial.phy5g.algorithms.noise_intf_estimator.NoiseIntfEstimator

Noise and interference estimator class.

This class implements an algorithm for noise and interference estimation. It calls the corresponding cuPHY algorithms and provides the estimates as needed for cuPHY equalization and soft demapping.

It needs channel estimates as its input, along with the received data symbols.

__init__(

num_rx_ant,

eq_coeff_algo,

cuda_stream=None,

)

Initialize NoiseIntfEstimator.

Parameters:

• num_rx_ant (int) – Number of receive antennas.

• eq_coeff_algo (int) –

  Algorithm used to compute equalizer coefficients.

  • 0: Zero-forcing equalizer.

  • 1: MMSE with noise variance only.

  • 2: MMSE-IRC.

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

Return type:

None

estimate(

*,

rx_slot,

channel_est,

slot,

pusch_configs=None,

num_ues=None,

num_dmrs_cdm_grps_no_data=None,

dmrs_scrm_id=None,

start_prb=None,

num_prbs=None,

dmrs_syms=None,

dmrs_max_len=None,

dmrs_add_ln_pos=None,

start_sym=None,

num_symbols=None,

scids=None,

layers=None,

dmrs_ports=None,

)

Estimate noise and interference.

This runs the cuPHY noise and interference estimation for all UE groups included in pusch_configs. If this argument is not given, all the other arguments need to be given and cuPHY noise and interference estimation is run only for a single UE group sharing the same time-frequency resources, i.e. having the same PRB allocation, and the same start symbol and number of allocated symbols.

The method can be called using either Numpy or CuPy arrays. In case the input arrays are located on the GPU (CuPy), the output will be on the GPU (CuPy). So the return type shall be the same as used for rx_slot when calling the method.

Parameters:

• rx_slot (Array) – Input received data as a frequency x time x Rx antenna Numpy or CuPy array with type complex64 entries.

• channel_est (List[Array]) – The channel estimates as a Rx ant x layer x frequency x time Numpy or CuPy array, per UE group.

• slot (int) – Slot number.

• pusch_configs (List[PuschConfig]) – List of PUSCH configuration objects, one per UE group. If this argument is given, the rest are ignored. If not given, all other arguments need to be given (only one UE group supported in that case).

• num_ues (int) – Number of UEs in the UE group.

• num_dmrs_cdm_grps_no_data (int) – Number of DMRS CDM groups without data [3GPP TS 38.212, sec 7.3.1.1]. Value: 1->3.

• dmrs_scrm_id (int) – DMRS scrambling ID.

• start_prb (int) – Start PRB index of the UE allocation.

• num_prbs (int) – Number of allocated PRBs for the UE group.

• dmrs_syms (List[int]) – For the UE group, a list of binary numbers each indicating whether the corresponding symbol is a DMRS symbol. The length of the list equals the number of symbols in the slot. 0 means no DMRS in the symbol and 1 means the symbol is a DMRS symbol.

• dmrs_max_len (int) – The maxLength parameter, value 1 or 2, meaning that DMRS are single-symbol DMRS or single- or double-symbol DMRS.

• dmrs_add_ln_pos (int) – Number of additional DMRS positions.

• start_sym (int) – Start symbol index for the UE group allocation.

• num_symbols (int) – Number of symbols in the UE group allocation.

• scids (List[int]) – DMRS sequence initialization SCID [TS38.211, sec 7.4.1.1.2] for each UE. Value is 0 or 1.

• layers (List[int]) – Number of layers for each UE. The length of the list equals the number of UEs.

• dmrs_ports (List[int]) – DMRS ports for each UE. The format of each entry is in the SCF FAPI format as follows: A bitmap (mask) starting from the LSB where each bit indicates whether the corresponding DMRS port index is used.

Returns:

A tuple containing:

• List[Array]: Inverse of the Cholesky decomposition of the noise/interference covariance matrix per PRB, per UE group. The size of each entry in this list is number of Rx antennas x number of Rx antennas x number of PRBs.

• Array: Pre-equalization wideband noise variance estimate per UE, i.e. one value per UE averaged over the whole frequency allocation. This value is in dB.

Return type:

List[Array], Array

class aerial.phy5g.algorithms.channel_equalizer.ChannelEqualizer

Channel equalizer class.

This class implements MMSE-based channel equalization along with soft demapping to get log-likelihood ratios for channel decoding.

It needs channel estimates and noise and interference estimates as its input, along with the received data symbols.

__init__(

num_rx_ant,

eq_coeff_algo,

enable_pusch_tdi,

cuda_stream=None,

)

Initialize ChannelEqualizer.

Parameters:

• num_rx_ant (int) – Number of receive antennas.

• eq_coeff_algo (int) –

  Algorithm used to compute equalizer coefficients.

  • 0: Zero-forcing equalizer.

  • 1: MMSE with noise variance only.

  • 2: MMSE-IRC.

• enable_pusch_tdi (int) – Whether to use time-domain interpolation.

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

Return type:

None

equalize(

*,

rx_slot,

channel_est,

lw_inv,

noise_var_pre_eq,

pusch_configs=None,

num_ues=None,

num_dmrs_cdm_grps_no_data=None,

start_prb=None,

num_prbs=None,

dmrs_syms=None,

dmrs_max_len=None,

dmrs_add_ln_pos=None,

start_sym=None,

num_symbols=None,

layers=None,

mod_orders=None,

)

Run equalization and soft demapping.

This runs the cuPHY equalization for all UE groups included in pusch_configs. If this argument is not given, all the other arguments need to be given and cuPHY equalization is run only for a single UE group sharing the same time-frequency resources, i.e. having the same PRB allocation, and the same start symbol and number of allocated symbols.

The method can be called using either Numpy or CuPy arrays. In case the input arrays are located on the GPU (CuPy), the output will be on the GPU (CuPy). So the return type shall be the same as used for rx_slot when calling the method.

Parameters:

• rx_slot (Array) – Input received data as a frequency x time x Rx antenna Numpy or CuPy array with type np.complex64 entries.

• channel_est (List[Array]) – The channel estimates as a Rx ant x layer x frequency x time Numpy or Cupy array, per UE group.

• lw_inv (List[Array]) – Inverse of the Cholesky decomposition of the noise/interference covariance matrix per PRB, per UE group. The size of each entry in this list is number of Rx antennas x number of Rx antennas x number of PRBs.

• noise_var_pre_eq (Array) – Average pre-equalizer noise variance in dB. One value per UE group.

• pusch_configs (List[PuschConfig]) – List of PUSCH configuration objects, one per UE group. If this argument is given, the rest are ignored. If not given, all other arguments need to be given (only one UE group supported in that case).

• num_ues (int) – Number of UEs in the UE group.

• num_dmrs_cdm_grps_no_data (int) – Number of DMRS CDM groups without data [3GPP TS 38.212, sec 7.3.1.1]. Value: 1->3.

• start_prb (int) – Start PRB index of the UE allocation.

• num_prbs (int) – Number of allocated PRBs for the UE group.

• dmrs_syms (List[int]) – For the UE group, a list of binary numbers each indicating whether the corresponding symbol is a DMRS symbol. The length of the list equals the number of symbols in the slot. 0 means no DMRS in the symbol and 1 means the symbol is a DMRS symbol.

• dmrs_max_len (int) – The maxLength parameter, value 1 or 2, meaning that DMRS are single-symbol DMRS or single- or double-symbol DMRS.

• dmrs_add_ln_pos (int) – Number of additional DMRS positions.

• start_sym (int) – Start symbol index for the UE group allocation.

• num_symbols (int) – Number of symbols in the UE group allocation.

• layers (List[int]) – Number of layers for each UE.

• mod_orders (List[int]) – QAM modulation order for each UE.

Returns:

A tuple containing:

• List[Array]: Log-likelihood ratios for the received bits to be fed into decoding (rate matching). One Numpy array per UE group and the size of each Numpy array is 8 x number of layers x number of subcarriers x number of data symbols. The size of the first dimension is fixed to eight as modulations up to 256QAM are supported and cuPHY returns the same size independently of modulation. Only the first entries corresponding to the actual number of bits are used.

• List[Array]: Equalized symbols, one Numpy array per UE group. The size of each Numpy array is equal to number of layers x number of subcarriers x number of data symbols.

Return type:

List[Array], List[Array]

class aerial.phy5g.algorithms.rsrp_estimator.RsrpEstimator

RSRP, post- and pre-equalizer SINR estimator class.

This class implements RSRP estimation as well as post- and pre-equalizer SINR estimation for PUSCH receiver pipeline.

__init__(num_rx_ant, enable_pusch_tdi, cuda_stream=None)

Initialize RsrpEstimator.

Parameters:

• num_rx_ant (int) – Number of receive antennas.

• enable_pusch_tdi (int) – Whether time-interpolation is used in computing equalizer coefficients. This impacts post-equalizer SINR.

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

Return type:

None

estimate(

channel_est,

ree_diag_inv,

noise_var_pre_eq,

pusch_configs=None,

num_ues=None,

num_prbs=None,

dmrs_add_ln_pos=None,

layers=None,

)

Run RSRP and post- and pre-equalizer SINR estimation.

The method can be called using either Numpy or CuPy arrays. In case the input arrays are located on the GPU (CuPy), the output will be on the GPU (CuPy). So the return type shall be the same as used for rx_slot when calling the method.

Parameters:

• channel_est (List[Array]) – The channel estimates as a Rx ant x layer x frequency x time Numpy or CuPy array, per UE group.

• ree_diag_inv (List[Array]) – Inverse of post-equalizer residual error covariance diagonal, per UE group.

• noise_var_pre_eq (Array) – Average pre-equalizer noise variance in dB. One value per UE group.

• pusch_configs (List[PuschConfig]) – List of PUSCH configuration objects, one per UE group. If this argument is given, the rest are ignored. If not given, all other arguments need to be given (only one UE group supported in that case).

• num_ues (int) – Number of UEs in the UE group.

• num_prbs (int) – Number of allocated PRBs for the UE group.

• dmrs_add_ln_pos (int) – Number of additional DMRS positions. This is used to derive the total number of DMRS symbols.

• layers (List[int]) – Number of layers for each UE.

Returns:

A tuple containing:

• Array: RSRP values per UE.

• Array: Pre-equalization SINR values per UE.

• Array: Post-equalization SINR values per UE.

Return type:

Array, Array, Array

class aerial.phy5g.algorithms.cfo_ta_estimator.CfoTaEstimator

CFO and TA estimator class.

This class implements an algorithm for carrier frequency offset and timing advance estimation. It calls the corresponding cuPHY algorithms and provides the estimates as needed for other cuPHY algorithms.

It needs channel estimates as its input.

__init__(

num_rx_ant,

mu=1,

enable_cfo_correction=True,

enable_to_estimation=True,

cuda_stream=None,

)

Initialize CfoTaEstimator.

Parameters:

• num_rx_ant (int) – Number of receive antennas.

• mu (int) – Numerology. Values in [0, 3]. Default: 1.

• enable_cfo_correction (int) –

  Enable/disable CFO correction:

  • 0: Disable.

  • 1: Enable (default).

• enable_to_estimation (int) –

  Enable/disable time offset estimation:

  • 0: Disable.

  • 1: Enable (default).

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

Return type:

None

estimate(

channel_est,

pusch_configs=None,

num_ues=None,

num_prbs=None,

dmrs_syms=None,

dmrs_max_len=None,

dmrs_add_ln_pos=None,

layers=None,

)

Estimate carrier frequency offset and timing advance.

Parameters:

• channel_est (List[Array]) – The channel estimates as a Rx ant x layer x frequency x time Numpy or CuPy array, per UE group.

• pusch_configs (List[PuschConfig]) – List of PUSCH configuration objects, one per UE group. If this argument is given, the rest are ignored. If not given, all other arguments need to be given (only one UE group supported in that case).

• num_ues (int) – Number of UEs in the UE group.

• num_prbs (int) – Number of allocated PRBs for the UE group.

• dmrs_syms (List[int]) – For the UE group, a list of binary numbers each indicating whether the corresponding symbol is a DMRS symbol. The length of the list equals the number of symbols in the slot. 0 means no DMRS in the symbol and 1 means the symbol is a DMRS symbol.

• dmrs_max_len (int) – The maxLength parameter, value 1 or 2, meaning that DMRS are single-symbol DMRS or single- or double-symbol DMRS.

• dmrs_add_ln_pos (int) – Number of additional DMRS positions.

• layers (List[int]) – Number of layers for each UE. The length of the list equals the number of UEs.

Returns:

A tuple containing:

• Array: Carrier frequency offset per UE, in Hz.

• Array: Timing offset per UE, in microseconds.

Return type:

Array, Array

class aerial.phy5g.algorithms.trt_engine.TrtTensorPrms

Class to hold the TRT input and output tensor parameters.

property cuphy_data_type: aerial.pycuphy.types.DataType

Convert data type to cuPHY data type format.

__init__(name, dims, data_type=numpy.float32)

Parameters:

• name (str)

• dims (List[int])

• data_type (type)

Return type:

None

class aerial.phy5g.algorithms.trt_engine.TrtEngine

TensorRT engine class.

This class implements a simple wrapper around NVIDIA’s TensorRT and its cuPHY API. It takes a TRT engine file as its input, along with the names and dimensions of the input and output tensors. The TRT engine file can be generated offline from an .onnx file using the trtexec tool.

__init__(

trt_model_file,

max_batch_size,

input_tensors,

output_tensors,

cuda_stream=None,

)

Initialize TrtEngine.

Parameters:

• trt_model_file (str) – This is TRT engine (model) file.

• max_batch_size (int) – Maximum batch size.

• input_tensors (List[TrtTensorPrms]) – A mapping from tensor names to input tensor dimensions. The names are strings that must match with those found in the TRT model file, and the shapes are iterables of integers. The batch dimension is skipped.

• output_tensors (List[TrtTensorPrms]) – A mapping from tensor names to output tensor dimensions. The names are strings that must match with those found in the TRT model file, and the shapes are iterables of integers. The batch dimension is skipped.

• cuda_stream (int) – The CUDA stream. If not given, one will be created.

Return type:

None

run(input_tensors)

Run the TensorRT model.

This runs the model using NVIDIA TensorRT engine.

Parameters:

input_tensors (dict) – A mapping from input tensor names to the actual input tensors. The tensor names must match with those given in the initialization, and with those found in the TRT model. Actual batch size is read from the tensor size. The tensors can be either Numpy or CuPy arrays.

Returns:

A mapping from output tensor names to the actual output tensors.

Return type:

dict