CSI Reporting

The module csireport.py implements the CsiReport and CsiReportMan classes used to process CSI information on the UE side and create CSI-feedback reports such as CRI, RI, PMI, and CQI.

class neoradium.csireport.CsiReport(csiRsSets, **kwargs)

Represents one CSI feedback report configuration (referred to as a CSI-ReportConfig in 3GPP TS 38.214) and the associated UE-side processing state.

This class consumes CSI-RS observations from a received resource grid and generates CSI feedback information according to the configured report quantity. Supported feedback quantities include:

Cri:

CSI-RS Resource Indicator, channel/beam selection based on CSI-RS RSRP

RiPmiCqi:

Rank indicator (RI), precoding matrix indicator (PMI), and channel quality indicator (CQI), jointly referred to as channel-state information (CSI)

RiPmi:

Rank indicator (RI) and precoding matrix indicator (PMI)

A report may be configured as periodic, semi-persistent-on-PUCCH, semi-persistent-on-PUSCH, or aperiodic. The object maintains internal measurement state across slots when needed (for example, when CRI requires measurements from multiple CSI-RS resources before selecting the best one).

Parameters:

  • csiRsSets (CsiRsSet or list of CsiRsSet) – One CSI-RS resource set or a list of CSI-RS resource sets used by this report. All resource sets are assumed to belong to the same bandwidth part.

  • kwargs (dict) –

    Optional configuration parameters:

    reportId:

    Report identifier. If not specified, csiRsSets[0].rsId + 10 is used.

    reportType:

    CSI reporting type. Supported values are "periodic" (default), "spOnPUCCH", "spOnPUSCH", and "aperiodic".

    period:

    Reporting period in slots for periodic and semi-persistent reporting modes. The default is 5.

    offset:

    Slot offset for periodic and semi-persistent reporting modes. The default is 0.

    active:

    Initial active state for semi-persistent reporting modes. The default is 0 (inactive)

    quantity:

    Type of CSI quantity to report. Supported values are "Cri" (default), "RiPmiCqi", "CriRiPmiCqi", and "RiPmi".

    txAntenna:

    Transmit antenna configuration used for PMI/RI/CQI processing (An AntennaPanel object). This is required when quantity is set to "RiPmiCqi" or "RiPmi".

    codebookType:

    Precoder codebook type. Currently only "Type1SP" is supported.

    allowedRanks:

    List of allowed transmission ranks considered during RI/PMI selection. The default is [1, 2, 3, 4].

    prgSize:

    Size of precoding resource groups (PRGs). A value of 0 (default) means wideband PMI.

    pmiGranularity:

    PMI granularity, either "wideband" or "subband".

    cqiTable:

    CQI table index as defined by 3GPP TS 38.214. The default is 1.

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

Prints the properties of this CSI report.

Parameters:

  • indent (int) – The number of indentation characters.

  • title (str or None) – If specified, it is used as the title for the printed information. If None (the default), the text “CSI Report Properties:” is used for the title.

  • getStr (bool) – If True, returns a string instead of printing it.

Returns:

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

Return type:

None or str

trigger()

Trigger an aperiodic CSI report. For reports configured with reportType="aperiodic", this method activates the report so that feedback can be generated the next time the reporting condition is met. For other report types, this method has no effect.

property isActive

Whether this CSI report is currently active.

Returns:

True if the report is currently active; otherwise False.

Return type:

bool

Notes

  • Periodic reports are always considered active.

  • Aperiodic and semi-persistent reports depend on the current internal activation state.

class neoradium.csireport.CsiReportMan(csiReports, **kwargs)

Manages a set of CSI reports and collects CSI feedback across slots. This class acts as a container and dispatcher for multiple CsiReport objects. It forwards received-grid processing to each report and aggregates the resulting CSI feedback.

Parameters:

  • csiReports (list of CsiReport) – CSI reports managed by this object.

  • kwargs (dict) –

    Optional configuration parameters:

    upDelay:

    Uplink delay, in slots, between CSI measurement time and CSI report transmission time. The default is 2.

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

Prints the properties of this CSI report manager.

Parameters:

  • indent (int) – The number of indentation characters.

  • title (str or None) – If specified, it is used as the title for the printed information. If None (the default), the text “CSI Report Manager Properties:” is used for the title.

  • getStr (bool) – If True, returns a string instead of printing it.

Returns:

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

Return type:

None or str

processRxGrid(rxGrid, csiRsResources)

Forward a received grid to all managed CSI reports for processing. Refer to the notebook Downlink CSI Feedback Using a Single Multi-Port CSI-RS for an example of using this method.

Parameters:

  • rxGrid (Grid) – Received resource grid.

  • csiRsResources (dict) – CSI-RS resource information organized by CSI-RS resource-set ID.

getFeedback()

Returns the CSI feedback generated for each configured CSI report. The returned value is a dictionary that maps each CSI-Report ID to a CsiFeedback object. Each entry corresponds to one CSI report configuration and contains the feedback quantities computed for that report, such as CRI, RI, PMI, and/or CQI.

Refer to the notebook Downlink CSI Feedback Using a Single Multi-Port CSI-RS for an example of using this method.

Returns:

Dictionary of the form: { reportId: csiFeedback }, where:

reportIdint

CSI-Report ID associated with a CSI report object. This ID is used as the dictionary key so that the feedback for each configured CSI report can be accessed independently.

csiFeedbackCsiFeedback

Dataclass containing the CSI feedback generated for the CSI report identified by reportId. Depending on the CSI report configuration, some feedback components may be present while others may be None. The CsiFeedback object has the following fields:

criCriFeedback or None

CRI feedback. This field is populated when CSI-RS resource indication feedback is requested (e.g. the quantity of the CsiReport object corresponding to reportId is set to "Cri"). Otherwise, it is set to None. CriFeedback contains:

criint

CSI-RS resource indicator. This identifies the CSI-RS resource selected by the receiver, corresponding to the strongest beam.

rsrpfloat

RSRP value (in dB) associated with the selected CSI-RS resource. This is the computed reference signal received power for the selected beam/resource.

riRiFeedback or None

RI feedback. This field is populated when rank indication feedback is requested (e.g. the quantity of the CsiReport object corresponding to reportId is set to "RiPmiCqi" or "RiPmi"). Otherwise, it is set to None. RiFeedback contains:

riint

Selected rank, i.e., the preferred number of PDSCH transmission layers.

scorefloat

Score associated with the selected rank which is the average of spectral efficiency over all layers.

pmiPmiFeedback or None

PMI feedback. This field is populated when precoder matrix indication feedback is requested (e.g. the quantity of the CsiReport object corresponding to reportId is set to "RiPmiCqi" or "RiPmi"). Otherwise, it is set to None.

PmiFeedback contains wideband PMI information and, when configured, subband PMI information. It contains:

wbPMIPmiIndex

Selected wideband PMI index. This describes the preferred wideband precoder over the CSI reporting bandwidth. PmiIndex contains:

i1list[int]

First part of the PMI index. It contains the three parts of I1 PMI index (e.g. [I11, I12, I13]).

i2int

Second part of the PMI index.

wbWcomplex numpy array

Wideband precoding matrix corresponding to the selected wideband PMI/codebook entry. This matrix is the precoder associated with wbPMI.

sbPMIslist[PmiIndex] or None

List of selected subband PMI indices, one entry per reported subband. This field is None when subband PMI feedback is not configured (See pmiGranularity).

Each element of sbPMIs is a PmiIndex object with the same structure as wbPMI above.

sbWslist of tuples or None

A list of tuples of the form (groupRBs, groupW). For each entry in the list, the Nt x Nl precoding matrix groupW is used for all subcarriers of the resource blocks listed in groupRBs. This is the same format used by the getPrecodingMatrix() and precodeTo() methods of the PDSCH class.

cqiCqiFeedback or None

CQI feedback. This field is populated when channel quality indication feedback is requested (e.g. the quantity of the CsiReport object corresponding to reportId is set to "RiPmiCqi"). Otherwise, it is set to None. CqiFeedback contains:

cqislist[int]

CQI values reported for the corresponding CSI report. The list contains one CQI value per codeword. For single-codeword transmission, this list has length 1. For dual-codeword transmission, this list has length 2.

blerslist[float]

The predicted BLER values corresponding to the CQI values in cqis. The length should match cqis. Each element represents the predicted BLER associated with the corresponding codeword CQI.

cqiint

Convenience property returning the first CQI value, equivalent to cqis[0]. This is useful for the common single-codeword case.

blerfloat

Convenience property returning the first BLER value, equivalent to blers[0]. This is useful for the common single-codeword case.

Return type:

dict

classmethod makeTypicalReports(csiRsConfig, txAntenna, prgSize=0, allowedRanks=[1])

DEPRECATED: This method is deprecated and will be removed in future releases. Please use the beamformingReports() method instead.

classmethod beamformingReports(csiRsConfig, txAntenna, **kwargs)

Creates the typical CSI report configuration for a beamforming CSI-RS configuration created by beamformingConfig(). The returned report manager contains three CSI reports:

  1. A periodic CRI report for beam sweeping.

  2. An aperiodic CRI report for beam probing.

  3. A semi-persistent RI/PMI/CQI report transmitted on the PUSCH.

The report IDs are derived from the corresponding CSI-RS resource-set IDs by adding 10. Unless explicitly overridden, the periodic reports use the same reporting periods as their corresponding CSI-RS resource sets. Default report offsets allow two slots between CSI-RS reception and CSI reporting to accommodate receiver processing.

Parameters:

  • csiRsConfig (CsiRsConfig) –

    A CSI-RS configuration created by beamformingConfig(). It must contain three resource sets in the following order:

    1. Periodic beam-sweeping resource set.

    2. Aperiodic beam-probing resource set.

    3. Semi-persistent RI/PMI/CQI resource set.

  • txAntenna (AntennaPanel) – The transmit antenna array used when computing PMI, RI, and CQI for the multi-port CSI report.

  • kwargs (dict) –

    Optional configuration parameters.

    sweepPeriod:

    Reporting period for the periodic beam-sweeping CRI report. By default, the period of the beam-sweeping CSI-RS resource set is used.

    sweepOffset:

    Slot offset of the periodic beam-sweeping CRI report. The default is two slots after the last beam-sweeping CSI-RS resource in the sweep sequence.

    pmiPeriod:

    Reporting period for the RI/PMI/CQI report. By default, the period of the RI/PMI/CQI CSI-RS resource set is used.

    pmiOffset:

    Slot offset of the RI/PMI/CQI report. The default is two slots after the corresponding CSI-RS transmission.

    rxAntenna:

    The receive antenna array used for PMI, RI, and CQI computation. If omitted, the underlying CsiReport implementation assumes its default receiver configuration.

    prgSize:

    Precoding Resource Group (PRG) size used for PMI computation. A value of 0 selects wideband PMI. The default is 0.

    allowedRanks:

    List of transmission ranks considered during RI/PMI optimization. The default is [1, 2].

    cqiTable:

    CQI table index as defined by 3GPP TS 38.214. The default is 1.

Returns:

A CSI report manager containing the periodic beam-sweeping CRI report, the aperiodic beam-probing CRI report, and the semi-persistent RI/PMI/CQI report.

Return type:

CsiReportMan

Note

The beam-probing CRI report is configured as an aperiodic report and must be triggered explicitly before it is transmitted. The beam-sweeping CRI report and the RI/PMI/CQI report are configured as periodic and semi-persistent reports, respectively, and follow their configured periods and offsets.

Please refer to the notebook Hierarchical Beam Management with Sweeping, Probing, and Type-I PMI Feedback for an example of using this function.

class neoradium.csireport.OLLA(harq=None, cqiTable=1, step=None, minCqiOffset=None, maxCqiOffset=None, fixedOffset=0)

Outer Loop Link Adaptation (OLLA) controller for CQI adjustment.

This class maintains a CQI offset for each codeword and updates the offset based on ACK/NACK feedback. The adjusted CQI can then be used by the link adaptation or scheduler to select a more conservative or more aggressive MCS than the one indicated directly by CSI feedback.

The OLLA update targets the nominal BLER associated with the selected CQI table. For CQI table 3, the default target BLER is 1e-5. For other CQI tables, the default target BLER is 0.1.

If a HARQ object is provided, this OLLA object is registered with the HarqEntity, so that the HARQ object can update it when ACK/NACK feedback becomes available.

Please refer to the notebook Link Adaptation with CSI Feedback, HARQ, and OLLA Along a UE Trajectory for an example of using this class.

Parameters:

  • harq (HarqEntity, optional) – HARQ entity associated with this OLLA object. The number of codewords is taken from harq.numCW, and harq.setLA(self) is called to register this OLLA object for ACK/NACK updates.

  • cqiTable (int, default=1) – CQI table index. CQI table 3 uses a default target BLER of 1e-5 and more conservative CQI-offset limits. Other values use a default target BLER of 0.1.

  • step (float, optional) – CQI-offset update step. If not specified, the default is 0.01 for CQI table 3 and 0.05 for other CQI tables.

  • minCqiOffset (float, optional) – Minimum allowed CQI offset. If not specified, the default is -6 for CQI table 3 and -4 for other CQI tables.

  • maxCqiOffset (float, optional) – Maximum allowed CQI offset. If not specified, the default is 2 for CQI table 3 and 4 for other CQI tables.

  • fixedOffset (int, default=0) – Fixed CQI offset added to the dynamic OLLA offset when adjusting CQI values. This can be used to model known calibration mismatch or implementation loss between the conditions used to generate the CQI report and the conditions used for PDSCH transmission. This offset is not modified by OLLA updates and is not reset by reset().

reset()

Reset all CQI offsets to zero.

If the CQI offsets have already been initialized, this method resets the offset of each codeword to zero. If the offsets have not yet been initialized, this method has no effect.

update(ack)

Update the CQI offset using ACK/NACK feedback.

The update follows the OLLA rule. ACK feedback increases the CQI offset by step * targetBler, making future transmissions slightly more aggressive. NACK feedback decreases the CQI offset by step * (1 - targetBler), making future transmissions more conservative. Each offset is clipped to the range [minCqiOffset, maxCqiOffset].

An ACK/NACK value of -1 is treated as “no update” and can be used for events that should not affect OLLA, such as HARQ retransmissions.

Parameters:

ack (int, list, or tuple) –

ACK/NACK feedback for one or more codewords. A scalar value is used for a single codeword. A list or tuple must contain one value per codeword. Supported values are:

  • 1: ACK

  • 0: NACK

  • -1: no update

adjustCqi(cqi)

Apply the current OLLA offset to one or more reported CQI values.

The adjusted CQI is obtained by adding the current CQI offset and the fixedOffset to the reported CQI and clipping the result to the valid CQI range from 1 to 15. A scalar input produces a scalar output, while a list or tuple input produces a list output with one adjusted CQI per codeword.

Parameters:

cqi (int, list, or tuple) – Reported CQI value or values. A scalar value is used for a single codeword. A list or tuple must contain one CQI value per codeword.

Returns:

Adjusted CQI value or values clipped to the range 1 to 15. The return type matches the input: scalar input returns a scalar, and list or tuple input returns a list.

Return type:

int or list of int