Reference Signals

CSI-RS

The module csirs.py implements the Channel State Information Reference Signals (CSI-RS) based on 3GPP TS 38.211 and 3GPP TS 38.214. CSI-RS is implemented in NeoRadium in the following 3 classes:

CsiRs: Implements one CSI-RS resource which can be used for both Zero-Power (ZP) and Non-Zero-Power (NZP) resources.
CsiRsSet: Implements a CSI-RS Resource Set which contains one or more CSI-RS resources.
CsiRsConfig: Implements the overall CSI-RS configuration information. It contains one or more CSI-RS resource sets.

NeoRadium’s API implementation provides both flexibility and simplicity. Here is a couple of different ways to configure CSI-RS.

Flexible Configuration: This method provides the most flexibility in configuration. Different numbers and types of CSI-RS resources can be configured in different numbers and types of CSI-RS resource sets. For example the following code configures two CSI-RS resource sets, one ZP and one NZP, with one and two CSI-RS resources correspondingly. Each CSI-RS is configured individually with different settings.

An example of flexibility in CSI-RS configuration

from neoradium import Carrier, CsiRsConfig, CsiRsSet, CsiRs

# Create the carrier and bandwidth part objects
carrier = Carrier(startRb=0, numRbs=24, spacing=15)
bwp = carrier.bwps[0]

# Create a ZP CSI-RS resource and add it to the ZP CSI-RS resource set
zpCsiRs = CsiRs(offset=1, symbols=[1], numPorts=1, freqMap="1000", density=0.5)
zpCsiRsSet = CsiRsSet("ZP", bwp, csiRsList=[zpCsiRs],
                      resourceType='semiPersistent', period=10)

# Create two NZP CSI-RS resources and add them to the NZP CSI-RS resource set
nzpCsiRs1 = CsiRs(offset=0, symbols=[1], numPorts=1, freqMap="000000001000", density=3)
nzpCsiRs2 = CsiRs(offset=3, symbols=[3], numPorts=1, freqMap="1000", density=1)
nzpCsiRsSet = CsiRsSet("NZP", bwp, csiRsList=[nzpCsiRs1, nzpCsiRs2],
                       resourceType='periodic', period=5)

# Now create the CSI-RS configuration using the ZP and NZP resource sets
csiRsConfig = CsiRsConfig([zpCsiRsSet, nzpCsiRsSet])

Easy and simple configuration: You can quickly create a typical CSI-RS configuration without getting involved with the complexity of different CSI-RS configuration parameters. For example the following code configures CSI-RS with one NZ and one NZP resources.

An example of simplicity in CSI-RS configuration

from neoradium import Carrier, CsiRsConfig, CsiRsSet, CsiRs

# Create the carrier and bandwidth part objects
carrier = Carrier(startRb=0, numRbs=24, spacing=15)
bwp = carrier.bwps[0]

# Create the CSI-RS configuration with a single call. The CSI-RS resource and
# resource set are automatically configured using the parameters provided.
csiRsConfig = CsiRsConfig(csiType="NZP", bwp=bwp, symbols=[1], numPorts=1,
                          freqMap="000000001000", density=3)

For more examples, see Channel State Information Reference Signals (CSI-RS) Configuration

class neoradium.csirs.CsiRs(**kwargs)

This class implements a CSI-RS resource which can be used to represent a Zero-Power (ZP - see 3GPP TS 38.214 Section 5.1.4.2) or Non-Zero-Power (NZP - see 3GPP TS 38.214 Section 5.2.2.3.1) resource.

Parameters:

kwargs (dict) –

A set of optional arguments.

resourceId:

The resource identifier of this CSI-RS resource. This is set to zero by default. This represents the values zp-CSI-RS-ResourceId or nzp-CSI-RS-ResourceId in 3GPP TS 38.214 for ZP and NZP resource types correspondingly.

offset:

The slot offset for this CSI-RS resource. It is set 0 by default. This is the value \(T_{offset}\) in 3GPP TS 38.211 section 7.4.1.5.3. It is only used if the resourceType parameter of CsiRsSet class containing this CSI-RS resource is set to 'periodic' or 'semiPersistent'. See Time-Domain Configuration for more information.

numPorts:

The number of antenna ports used by this CSI-RS resource. It can be one of 1, 2, 4, 8, 12, 16, 24, or 32. This is the value \(X\) in 3GPP TS 38.211 Table 7.4.1.5.3-1.

cdmSize:

The CDM size of this CSI-RS resource. It can be one of 1, 2, 4, or 8 corresponding to noCDM, fd-CDM2, cdm4-FD2-TD2, and cdm8-FD2-TD4 in 3GPP TS 38.211 Table 7.4.1.5.3-1.

density:

The frequency density of the CSI-RS resource. It can be one of 0.5, 1, or 3. The value 3 is only available if numPorts is set to 1. This is the value \(\rho\) in 3GPP TS 38.211 Table 7.4.1.5.3-1.

freqMap:

A bitmap string that specifies the frequency-domain locations of this CSI-RS resource. See 3GPP TS 38.211 Section 7.4.1.5.3 for more information. This value determines which resource elements in each resource block are used by this CSI-RS resource.

symbols:

The list of time symbol indexes in each slot that are used by this CSI-RS resource.

powerDb:

The power (in dB) used by this CSI-RS resource for the NZP resources. This is ignored for Zero-Power (ZP) resources. The default value is 0. This contains the value of \(\beta_{CSIRS}\) as specified 3GPP TS 38.211 Section 7.4.1.5.3.

scramblingID:

The scrambling identity which is used for generating pseudo-random sequences. The default is 0. This is ignored for ZP resources.

Other Properties:

All of the parameters mentioned above except freqMap and symbols are directly available. Here is a list of additional properties:

ls:

The time-domain symbol indexes used by this CSI-RS resource. This is a list of integers which is extracted from the symbols parameter explained above. This list contains the \(l_0\) and \(l_1\) values in the 5^th column of 3GPP TS 38.211 Table 7.4.1.5.3-1 (The column titled \((\bar k, \bar l)\)).

ks:

The frequency-domain RE indexes used by this CSI-RS resource. This is a list of integers which is extracted from the freqMap parameter explained above. This list contains the \(k_0\), \(k_1\), \(k_2\), and \(k_3\) values in the 5^th column of 3GPP TS 38.211 Table 7.4.1.5.3-1 (The column titled \((\bar k, \bar l)\)).

row:

The row index of 3GPP TS 38.211 Table 7.4.1.5.3-1 corresponding to the configuration of this CSI-RS resource (The column titled “Row”). This class determines the row index using the parameters numPorts, cdmSize, density, and freqMap.

mySet:

The CsiRsSet object containing this CSI-RS resource.

Additionally you can access the CsiRsSet class parameters period, bwp, csiType, resourceType, active, startRb, and numRbs directly. The parameter mySet is internally used to return these values from the CsiRsSet class containing this CSI-RS resource.

print(indent=0, title='CSI-RS Properties:', getStr=False)

Prints the properties of this CSI-RS resource.

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

class neoradium.csirs.CsiRsSet(csiType, bwp, **kwargs)

This class implements a CSI-RS resource set which contains one or more CSI-RS resources (CsiRs objects). A CSI-RS resource set can be either Zero-Power (ZP) or Non-Zero-Power (NZP). All of the CSI-RS resources in a set are the same type (ZP or NZP). By default, a CSI-RS resource set is configured with one CSI-RS resource. More CSI-RS resources can be added using the addCsiRs() method.

Parameters:

csiType (str) – The type of this CSI-RS resource set. It must be either 'NZP' or 'ZP'.
bwp (BandwidthPart) – The bandwidth part used by this CSI-RS resource set.
kwargs (dict) –
A set of optional arguments.

rsId:

The resource set identifier of this CSI-RS resource set. This is set to zero by default. This represents the values nzp-CSI-ResourceSetId or zp-CSI-RS-ResourceSetId in 3GPP TS 38.214 for NZP and ZP resource sets correspondingly.

startRb:

The index of starting resource block (RB) used by this CSI-RS resource set. By default this is set to bwp.startRb. The resources specified by startRb and numPorts must be inside the specified bandwidth part bwp.

numRbs:

The number of resource blocks used by this CSI-RS resource set starting at startRb. By default this is set to bwp.numRbs. The resources specified by startRb and numPorts must be inside the specified bandwidth part bwp.

resourceType:

The time-domain resource type of this CSI-RS resource set. It can be one of 'aperiodic', 'semiPersistent', or 'periodic' (default). See Time-Domain Configuration below for more information.

period:

The period (in number of slots) of this CSI-RS resource set in time domain. This is the value \(T_{CSI-RS}\) in 3GPP TS 38.211 section 7.4.1.5.3. By default, it is set to 4 which means CSI-RS is transmitted every 4^th slot (for example slots numbers 0, 4, 8, …). The period can be 4, 5, 8, 10, 16, 20, 32, 40, 64, 80, 160, 320, or 640 slots. This parameter is ignored if resourceType is set to 'aperiodic'. See Time-Domain Configuration below for more information.

active:

This boolean flag is used to trigger an 'aperiodic' or activate a 'semiPersistent' CSI-RS resource set. It is ignored if resourceType is set to 'periodic'. This is set to True by default. See Time-Domain Configuration below for more information.

csiRsList:

A list of CsiRs objects contained in this CSI-RS resource set. If not specified, this class creates a single CSI-RS resource and puts it in the list. More CsiRs objects can be added using the addCsiRs() method.

Other Properties:

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

numPorts:

This read-only parameter returns the maximum number of ports of all CSI-RS resources in this CSI-RS resource set.

Time-Domain Configuration:

In time-Domain, CSI-RS can be configured for periodic, semi-persistent, or aperiodic transmission.

Periodic:: In this case, the CSI-RS transmission occurs every N^th slot, where N ranges from 4 to 640. In this case, each CSI-RS resource is also configured with an offset value. Please note that while the period N is the same for all CSI-RS resources in a set, the offset can be different for different CSI-RS resources in the set. That is why the period is a property if the CSI-RS resource set while offset is a property of CSI-RS resource.

The time-domain period and offset examples [1]
Semi-persistent:: In this case, the periodicity and offset of the CSI-RS transmissions is configured similar to the periodic case but the actual transmission can be disabled/enabled using the active flag defined above. Once activated, the CSI-RS transmission behavior is just like the periodic case until it is deactivated. All CSI-RS resources in the set are activated/deactivated together. (The active flag is a property of CSI-RS resource set)
Aperiodic:: In this case, there is no periodicity. The transmission of the CSI-RS can be triggered by setting the active flag to True. In practice this is signaled in the DCI message. All CSI-RS resources in the set are triggered together. (The active flag is a property of CSI-RS resource set)

Please refer to 3GPP TS 38.211 section 7.4.1.5.3 for more details. See also CSI-RS timing configurations.

print(indent=0, title='CSI-RS Resource Set Properties:', getStr=False)

Prints the properties of this CSI-RS resource set.

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

addCsiRs(csiRsList)

Adds one more CSI-RS resources to this CSI-RS resource set.

Parameters:: csiRsList (list) – A list of CsiRs objects to be added to this CSI-RS resource set.

class neoradium.csirs.CsiRsConfig(csiRsSetList=[], **kwargs)

This class implements the overall CSI-RS configuration. It keeps a list of CSI-RS resource sets (CsiRsSet objects) each of which contains one or more CSI-RS resources (CsiRs objects). By default, this class creates a single CSI-RS resource set. More CSI-RS resources sets can be added using the addCsiResourceSets() method.

Parameters:

csiRsSetList (list) –
A list of CsiRsSet objects contained in this CSI-RS configuration. If this list is not specified, but a BandwidthPart object is specified in kwargs this class creates a single CSI-RS resource set containing a single CSI-RS resource. The parameters passed in kwargs are used to initialize the CSI-RS resource set and its only CSI-RS resource.

If this list is not specified, and a BandwidthPart object is not given, then the list of CSI-RS resource sets remains empty and you must use the addCsiResourceSets() to add CSI-RS resource sets.
kwargs (dict) – A set of optional arguments. These parameters are passed to the CsiRsSet and CsiRs objects when they are created the first time.

Other Properties:

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

numPorts:

This read-only parameter returns the maximum number of ports in all CSI-RS resources in all CSI-RS resource sets.

print(indent=0, title='CSI-RS Configuration:', getStr=False)

Prints the properties of this CSI-RS Configuration.

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

addCsiResourceSets(csiRsSetList)

Adds one more CSI-RS resource sets to this CSI-RS configuration.

Parameters:: csiRsSetList (list) – A list of CsiRsSet objects to be added to this CSI-RS configuration.

addCsiRs(setIndex=0, csiRs=None, **kwargs)

Adds the CSI-RS resource given in csiRs to the CSI-RS resource set specified by setIndex to this CSI-RS configuration.

Parameters:

setIndex (int (default: 0)) – The index of CSI-RS resource set in this CSI-RS configuration that receives the new CSI-RS resource.
csiRs (CsiRs (default: None)) – If specified, the CsiRs object is added to the CSI-RS resource set specified by setIndex. Otherwise, a new CSI-RS resource object is created based on the information in kwargs and then it is added to the CSI-RS resource set specified by setIndex.
kwargs (dict) –
These parameters are only used if this CSI-RS configuration is empty and/or if csiRs=None.

If this CSI-RS configuration is empty, the information in kwargs is first used to create a CSI-RS resource set.

If csiRs is not specified, then the information in kwargs is first used to create a CSI-RS resource and add to the specified CSI-RS resource set.

populateGrid(grid)

Uses the information in this CSI-RS configuration to calculate reference signal values and updates the Grid object specified by grid.

Parameters:: grid (Grid) – The Grid object that gets populated with CSI-RS based on this CSI-RS configuration.

DMRS and PTRS

The module dmrs.py implements the DMRS and PTRS classes which encapsulate Demodulation Reference Signals and Phase-Tracking Reference Signals correspondingly.

Demodulation reference signals are intended for channel estimation on the receiver side and enable coherent demodulation. They are used with all types of communication channels for both data and control, and downlink and uplink. This means DMRS object can be associated with PDSCH, PDCCH, PUSCH, or PUCCH classes.

PTRS is used for tracking the phase of the local oscillators at the receiver and transmitter. If transmitted, PTRS is always associated with one DMRS port.

class neoradium.dmrs.DMRS(pxxch=None, **kwargs)

This class encapsulates the configuration and functionality of Demodulation Reference Signals. A DMRS object can be associated with a PDSCH, a PDCCH, a PUSCH, or a PUCCH. (Currently only PDSCH is implemented in NeoRadium. Support for other channels are coming soon.)

For every PDSCH, it is mandatory to have at least one OFDM symbol of DMRS. We can also have one, two, or three additional OFDM symbols assigned to DMRS.

Parameters:

pxxch (PDSCH) – The PDSCH object associated with this DMRS object. Technically this can be any of PDSCH, PDCCH, PUSCH, or PUCCH classes, but currently only PDSCH is implemented in NeoRadium.
kwargs (dict) –
A set of optional arguments.

configType:

The DMRS configuration type. It can be either 1 (default) or 2. In Configuration type 1, the minimum resource element group in frequency domain is one RE. In Configuration type 2, the minimum resource element group in frequency domain is two consecutive REs.

symbols:

The number of OFDM symbols used with each group of DMRS REs. It can be 1 (Single) or 2 (Double). The default is Single.

typeA1stPos:

This is the OFDM symbol index for the first DMRS symbol when Mapping type A is being used. It can be either 2 (default) or 3.

additionalPos:

Position(s) for additional DMRS symbols. For symbols==1, it can be 0, 1, 2, or 3 and for symbols==2 it can be 0 or 1. This allows up to a maximum of 4 OFDM symbols used for DMRS.

portSet:

A list of port numbers used for DMRS allocation. See 3GPP TS 38.211, Table 7.4.1.1.2-5 for more information. If not specified, it is set based on the number of layers in pxxch. If specified, the number of items in the list should match the number of layers in pxxch.

otherCdmGroups:

A list of CDM groups used by other PXXCH objects (For example, in PDSCH, some CDM groups may be used for other UEs). When allocating resources, this class makes sure that no data is allocated in the CDM groups used for other UEs. See Using otherCdmGroups parameter for examples of how to use this parameter.

scID:

The number specifying which one of the nIDs (see below) should be used for scrambling. It can be 0 (default) or 1.

nIDs:

A list of one or 2 integer values (nIDs[scID] ∈ {0,1,...,65535}, scID ∈ {0,1}) The nIDs[0] and nIDs[1] are explained in 3GPP TS 38.211, Section 7.4.1.1.1 (scramblingID0, scramblingID1).

sameSeq:

A boolean value set to True by default. If True, the same binary sequence is created for all CDM Groups. Otherwise the sequences for different CDM Groups are initialized differently. This corresponds to the parameter dmrs-Downlink in 3GPP TS 38.211, Section 7.4.1.1.1.

epreRatioDb:

The ratio of PXXCH energy per resource element (EPRE) to DMRS EPRE in dB. If not specified, 3GPP TS 38.214, Table 4.1-1 is used to set this parameter.

Other Properties:

cdmGroups:

A list of CDM groups used by this DMRS. This property is set based on the portSet and configType parameters.

symSet:

A numpy array containing the indexes of the OFDM symbols used by this DMRS.

ptrs:

The PTRS object associated with this DMRS object or None if PTRS is not configured.

ptrsEnabled:

A boolean read-only property. If True it means PTRS is enabled and therefore the ptrs property above should not be None. Otherwise PTRS is disabled and the ptrs property above should be set to None.

The notebook Configuring DMRS shows some examples of configuring DMRS.

print(indent=0, title='DMRS Properties:', getStr=False)

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

setPTRS(**kwargs): Creates a new PTRS object based on the parameters given in kwargs and associates it with this DMRS object. For more information please refer to the PTRS documentation.

populateGrid(grid)

Uses the information in this DMRS to calculate Demodulation Reference Signal values and update the Grid object specified by grid.

If PTRS is enabled, it calls the populateGrid() method of the PTRS class to update the specified grid with Phase Tracking Reference Signals.

Parameters:: grid (Grid) – The Grid object that gets populated with the Demodulation Reference Signals.

class neoradium.dmrs.PTRS(dmrs, **kwargs)

This class encapsulates the functionality of Phase Tracking Reference Signals (PTRS). A PTRS object can be associated with a PDSCH or a PUSCH. (Currently only PDSCH is implemented in NeoRadium. Support for other channels are coming soon.)

PTRS is used for tracking the phase of the local oscillators at the receiver and transmitter. This enables suppression of phase noise and common phase error, particularly important at high carrier frequencies such as millimeter wave. Due to the properties of phase noise, PTRS can have low density in the frequency domain but high density in the time domain. If transmitted, PTRS is always associated with one DMRS port.

This implementation is mostly based on 3GPP TS 38.211, Section 7.4.1.2 and 3GPP TS 38.214, Section 5.1.6.3.

Parameters:

dmrs (DMRS) – The DMRS object associated with this PTRS.
kwargs (dict) –
A set of optional arguments.

mcsi:

A list of 3 values for ptrs-MCS1, ptrs-MCS2, and ptrs-MCS3 in 3GPP TS 38.214, table 5.1.6.3-1 or None (default). This is used with iMCS and nRBi to determine time and frequency density of the PTRS signals. See Specifying Time and Frequency density below for more information.

iMCS:

The value from 3GPP TS 38.214 tables 5.1.3.1-1 to 5.1.3.1-4 or None (default). This is used with mcsi and nRBi to determine time and frequency density of the PTRS signals. See Specifying Time and Frequency density below for more information.

nRBi:

A list of 2 values for nRB0 and nRB1 in 3GPP TS 38.214, table 5.1.6.3-2 or None (default). This is used with mcsi and iMCS to determine time and frequency density of the PTRS signals. See Specifying Time and Frequency density below for more information.

timeDensity:

The time density of the PTRS signals. It can be 1 (default), 2, or 4. This is ignored if parameters mcsi, iMCS, and nRBi are all specified. See Specifying Time and Frequency density below for more information.

freqDensity:

The frequency density of the PTRS signals. It can be 2 (default) or 4. This is ignored if parameters mcsi, iMCS, and nRBi are all specified. See Specifying Time and Frequency density below for more information.

reOffset:

The resource element (RE) offset. It can be one of 0 (default), 1, 2, or 3. This is the resourceElementOffset value in 3GPP TS 38.211, Table 6.4.1.2.2.1-1.

portSet:

The set of antenna ports associated with this PTRS. If not specified, the first port of the associated DMRS is used.

epreRatio:

The epre-Ratio value in 3GPP TS 38.214, Table 4.1-2. It is used to determine the ratio of PTRS energy per resource element (EPRE) to PDSCH EPRE in dB. It can be 0 (default) or 1. See 3GPP TS 38.214, Table 4.1-2 for more information.

Specifying Time and Frequency density:

There are two different ways to specify time and frequency density of the PTRS signals.

Using MCS Info:

In this method, all of the values mcsi, iMCS, and nRBi must be specified. The values timeDensity and freqDensity are then derived from the provided MCS information based on 3GPP TS 38.214, Tables 5.1.6.3-1 and 5.1.6.3-2.

Direct Setting:

In this method, the values timeDensity and freqDensity are provided directly. In this case all of the values mcsi, iMCS, and nRBi must be set to None (default).

Other Properties:

symSet:

A numpy array containing the indexes of the OFDM symbols used by this PTRS.

The notebook Configuring PTRS shows some examples of configuring PTRS.

print(indent=0, title='PTRS Properties:', getStr=False)

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

populateGrid(grid)

Uses the information in this PTRS object to calculate the Phase Tracking Reference Signal values and update the Grid object specified by grid.

Normally you don’t need to call this function directly. Since every PTRS object is associated with a DMRS object, this function is called automatically when the populateGrid() method of the DMRS class is called.

Parameters:: grid (Grid) – The Grid object that gets populated with the Phase Tracking Reference Signals.

References: