Code-Books

This is the module which provides functions and classes that implement DFT based Code-Books. Current implementation supports Type-I codebook based precoder or beamformer.

Type-1 Code-Book

This module provides classes and the functions that implements Type-I CodeBook based precoder specified in sections 5.2.2.2.1,2 of TS 28.214.

  • The class TypeICodeBook allows the users to precode the Tx data corresponding to PDSCH with Type-I Codebook based precoder.

  • A precoder IdealPrecoder, which is to be approximated is passed as an input to the object of this class and beam indices have been estimated using an algorithm. Current implementation supports an algorithm named SearchFree and the class which implements this algorithm is SearchFree [sf] .

  • Computed beam indices have been mapped to Precoder Matrix Indicator (PMI), which identifies a precoding matrix from a predefined codebook for the specified rank.

  • A Full Dimensional MIMO system employing a 2-dimensional panel array at the Base Station (BS) side is considered, with \(N1\) horizontal atennas and \(N2\) vertical antennas. Dual polarized antennas have been considered, with \(P = 2\). Thus, the total number of transmit antenna ports seen by a UE in downlink assuming single panel antenna structure at Base Station is \(N1*N2*P\). For multi panel antenna structure, the number of transmit antenna ports is \(Ng*N1*N2*P\), where \(Ng\) denotes the number of panel in vertical direction.

  • For a complex valued MIMO channel matrix \(H\) of dimension \(Nr\times(N1*N2*P)\), (where \(Nr\) denoted the number of UE antenna), BS pre-multiplies its transmitted data by a complex valued precoding matrix W of dimension \((N1*N2*P) \times L\), where \(L\) denotes the transmisson rank or the number of data layers.

Table 33 Arrangement of Type-I Single Panel assuming that Tx support atleast 4 CSI-RS ports.

Number of Layers

Mode “1”

Mode “2”

Mode “1-2”

1

✅

✅

❌

2

✅

✅

❌

3

❌

❌

✅

4

❌

❌

✅

5

❌

❌

✅

6

❌

❌

✅

7

❌

❌

✅

8

❌

❌

✅
Table 34 Arrangement of Type-I Multi Panel assuming that the Tx support atleast 8 CSI-RS ports

Number of Layers

Mode “1”

Mode “2”

1

✅

✅

2

✅

✅

3

✅

✅

4

✅

✅

Note

  • For 4 or more ports and if the transmitted number of layers are either 1 or 2 (i.e., for rank 1 or rank 2), code book is divided in to two modes mode “1” and mode “2”.

  • mode “1” corresponds to selecting one beam group from a set of oversampled dft beam groups.

  • mode “2” correspond to selecting 4 beam groups respectively. [3GPPTS38214Type1CB]

class toolkit5G.MIMOProcessing.TypeICodeBook(codebookType, AntennaStructure, AntennaPolarization=2)[source]

A class for generating Type-I Codebook based precoder.

Parameters:

  • codebookType (str) – Specifies the type of the codebook. A higher layer parameter specified in TS 38.214 section 5.2.2.1. It specify whether the code book is a single panel or multi panel. Valid codebookType are “typeI-SinglePanel”, and “typeI-MultiPanel”.

  • AntennaStructure (int or NumPy.ndarray of int) – Specifies the number of atenna elements in horizonatal and vertical directions. Denoted by variables [N1,N2]. Additionally it also specify the number of panel in vertical direction for multi panel codebook. Denoted by variable Ng.

    • Must be an array of 2 int’s if codebookType is “typeI-SinglePanel”.

      • Valid [N1,N2] are [[2,1],[2,2],[4,1],[3,2],[6,1],[4,2],[8,1],[4,3],[6,2],[12,1],[4,4],[8,2],[16,1]].

    • Must be an array of 3 int’s if codebookType is “typeI-MultiPanel”.

      • Valid [Ng,N1,N2] are [[2,2,1],[2,4,1],[4,2,1],[2,2,2],[2,8,1],[4,4,1],[2,4,2],[4,2,2]].

  • AntennaPolarization (int) – Specifies the antenna element polarization. Denoted by variable P. Since Type-I code book assumes dual or cross polarized antenna elements it must be 2.

Input:

  • numIterations (int) – Specifies the number of iterations to estimate beam indices by search free algorithm. Must be a positive int.

  • IdealPrecoder (NumPy.ndarray) – The ideal precoder computed by taking the SVD of the Channel matrix which is to be approximated by type1 codebook based precoder, Must be of dimension Nt x rank, where Nt = N1*N2*P denoting the number of Tx antenna ports.

  • rank (int or numpy.int) – Specifies the number of Tx layers. Must be an int. Maximum number of layers supported by Type-I code book is 8.

  • codebookMode (str) –

    Specifies the mode of Type-I code book. Must be a string.

    • For Single Panel valid codebookMode are “1”, “2”, and “1-2”.

      • Min, Max number of layers supported under single panel mode “1” or mode “2” are 1, 2 respectively.

      • Min, Max number of layers supported under mode “1-2” are 3, 8 respectively.

    • For Multi Panel valid codebookMode are “1”, “2”.

      • Min, Max number of layers supported under multi panel mode “1” or mode “2” are 1, 4 respectively.

  • method (str) – Specifies the method to compute the beam indices corresponding to type-1 codebook based precoder. Must be a string. Current supported method is “SearchFree”.

Output:

[Nt,rank], np.complex64- denoting a type-I codebook based precoder, where Nt denote the number of Tx antenna ports, i.e., Nt = N1*N2*P for single panel and Nt = Ng*N1*N2*P for multi panel.

Raises:

  • ValueError – If AntennaStructure is not an array of 2 Non Zero integers [N1,N2] under single panel code book.

  • ValueError – If Passed Antenna Configuration [N1,N2] is not Supported. Supported configuration under single panel code book are [[2,1],[2,2],[4,1],[3,2],[6,1],[4,2],[8,1],[4,3],[6,2],[12,1],[4,4],[8,2],[16,1]].

  • ValueError – If Passed Antenna Configuration [Ng,N1,N2] is not Supported. Supported configuration under multi panel code book are [[2,2,1],[2,4,1],[4,2,1],[2,2,2],[2,8,1],[4,4,1],[2,4,2],[4,2,2]].

class toolkit5G.MIMOProcessing.SearchFree(IdealPrecoder, rank, AntennaStructure, AntennaPolarization=2)[source]

A class which implements search-free algorithm for precoder selection in Full Dimension (FD) MIMO systems with DFT based code books.

Parameters:

  • IdealPrecoder (NumPy.ndarray) – The ideal precoder computed by taking the SVD of the Channel matrix which is to be approximated by type1 codebook based precoder, Must be of dimension Nt x rank, where Nt = N1*N2*P denoting the number of Tx antenna ports.

  • rank (int or numpy.int) – Specifies the number of Tx layers. Must be an int. Maximum number of layers supported by Type-I code book is 8.

  • AntennaStructure (int or NumPy.ndarray of int) – Specifies the number of atenna elements in horizonatal and vertical directions. Denoted by variables [N1,N2]. Additionally it also specify the number of panel in vertical direction for multi panel codebook. Denoted by variable Ng.

    • Must be an array of 2 int’s if codebookType is “typeI-SinglePanel”.

      • Valid [N1,N2] are [[2,1],[2,2],[4,1],[3,2],[6,1],[4,2],[8,1],[4,3],[6,2],[12,1],[4,4],[8,2],[16,1]].

    • Must be an array of 3 int’s if codebookType is “typeI-MultiPanel”.

      • Valid [Ng,N1,N2] are [[2,2,1],[2,4,1],[4,2,1],[2,2,2],[2,8,1],[4,4,1],[2,4,2],[4,2,2]].

  • AntennaPolarization (int) – Specifies the antenna element polarization. Denoted by variable P. Since Type-I code book assumes dual or cross polarized antenna elements it must be 2.

  • numIterations (int) – Specifies the number of iterations required to estimate beam indices by search free algorithm. Must be a positive int.

Example:

The following code snippet shows the use of type-I codebook based precoder at a carrier frequency of 3.6 GHz with a scs of 15 KHz. 24 resouce blocks (RBs) and FFT size of 1024 have been considered for simulation. Number of transmitted layers are 5 under \(8\times32\) MIMO system (i.e., 8 Rx antenna ports and 32 Tx antenna ports). Precoder is applied at sub-band level with a sub-band size of 4 RBs.

#######################################
#Importing necessary Python Libraries
#######################################
import os
os.environ["CUDA_VISIBLE_DEVICES"] = "-1"
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3'

%matplotlib widget
import matplotlib.pyplot  as plt
import matplotlib.patches as mpatches
import matplotlib as mpl

import numpy      as np

############################
#Importing toolkit5G modules
############################

import toolkit5G
from toolkit5G.MIMOProcessing  import TypeICodeBook

########################
## Simulation Parameters
########################

carrierFrequency = 3.6*10**9     # Carrier Frequency
numBatches       = 10            # Number of batches considered for simulation
scs              = 15*10**3      # Subcarrier Spacing for simulation
numRB            = 24            # Number of Resource mapping considered for simulation
Nfft             = 1024          # FFT Size
bwpOffset        = np.random.randint(Nfft-numRB*12)
rank             = 5

#################################
# Antenna Structure at BS and UE
#################################
txAntStruture = np.array([1,1,4,4,2]) # Tx or BS Antenna Structure
rxAntStruture = np.array([1,1,2,2,2]) # Rx or UE Antenna Structure
################################Sub-Band Channel and SVD Based SubBand Precoding########################################################################################################################
subBandSize      = 4 # sub-band size in PRBs
numSubBands      = int(numRB/subBandSize) # Number of Sub-Band Channels
subBandSCIndices = np.arange(bwpOffset, bwpOffset + numSubBands*subBandSize*12).reshape(numSubBands,-1) # Sub-Carrier indices corresponding to each sub-band

######################
# Digital Beamforming
######################
[U, S, Vh] = np.linalg.svd(Hf)
# precoder   = np.conj(Vh.transpose(3,0,1,2,4,6,5)[...,0:rank])
combiner  = np.conj((U*(1/S[...,np.newaxis,:].repeat(S.shape[-1], axis = -2)))[...,0:rank].transpose(3,0,1,2,4,6,5))
# xBeam      = (precoder@txGrid.transpose(0,1,3,4,2)[:,np.newaxis,...,np.newaxis])[...,0]

############### Type-1 Code-Book based Precoding #######################################################################################################################################################
#############################################################
# Single Panel Mode 1, Mode 2 : Valid Ranks are 1 and 2
# Single Panel Mode 1-2       : Valid Ranks are 3,4,5,6,7,8
# Multi Panel Mode 1, Mode 2  : Valid Ranks are 1,2,3,4
#############################################################

codebookType        = "typeI-SinglePanel"
AntennaStructure    = txAntStruture[-3:-1]
AntennaPolarization = txAntStruture[-1]
codebookMode        = "1-2"
method              = "SearchFree"
numIterations       =  100

type1CB  = TypeICodeBook(codebookType, AntennaStructure, AntennaPolarization)
numPorts = np.prod(AntennaStructure)*AntennaPolarization
type1Precoder = np.zeros((numBatches,Nfft,numPorts,rank), dtype="complex_")

for nsb in range(numSubBands):
    Hk       = Hf[...,subBandSCIndices[nsb],:,:]
    H        = (np.conj(Hk.transpose(0,1,2,3,4,6,5))@Hk).mean(-3)
    [S2, V]  = np.linalg.eig(H)
    for nb in range(numBatches):
        type1Precoder[nb,subBandSCIndices[nsb],...]  = type1CB(numIterations,V[0,0,0,nb,:,0:rank], rank, codebookMode, method)


a = type1Precoder[:,np.newaxis,np.newaxis,np.newaxis,:,:]
b = txGrid.transpose(0,1,3,4,2)[:,np.newaxis,...,np.newaxis]
CBbeamFormedGrid = (a@b)[...,0]


print()
print("Type-I SP Mode1 Precoder Shape:\n", a.shape)
print()
print("CodeBook Beamformed Grid Shape:\n", CBbeamFormedGrid.shape)
References:
[3GPPTS38214Type1CB]

(3GPP TS 38.214 Release 17 V17.1.0); Physical layer procedures for data.

[sf]

(A Search-Free Algorithm for Precoder Selection in FD-MIMO Systems with DFT-Based Codebooks. Federico Penna, Hongbing Cheng, and Jungwon Lee).