Channel Coding

The module chancodebase.py implements the base class ChanCodeBase for all NeoRadium’s channel coding classes. It encapsulates some basic functionality such as creating, appending, and checking various types of CRC processing based on 3GPP TS 38.212.

Here is the hierarchy of current channel coding classes in NeoRadium:

class neoradium.chancodebase.ChanCodeBase

Base class for all channel coding classes in NeoRadium. Provides shared CRC helpers and constants used by Polar and LDPC code paths per 3GPP TS 38.212, Section 5.1.

Inherited members

  • LARGE_LLR — a large LLR magnitude (1e20) representing absolute certainty, used by decoders to encode filler bits as “definitely zero”.

  • getCrc() — computes the CRC bits for a 1-D or 2-D bit array given a polynomial name.

  • checkCrc() — validates that a bit array (with CRC appended at the end) is consistent.

  • appendCrc() — convenience wrapper that returns the input bits with the CRC appended.

  • getCrcLen() — returns the CRC length in bits for a given polynomial name.

Known subclasses

classmethod getCrc(bits, poly)

Calculates and returns the CRC based on the bitstream bits and the generator polynomial specified by poly.

Parameters:

  • bits (NumPy array) – A 1D or 2D NumPy array of bits. If it is a 1D NumPy array, the CRC bits are calculated for the given bitstream and a 1D NumPy array containing the CRC bits is returned. If bits is an N x L NumPy array, it is assumed that we have N bitstreams of length L. In this case the CRC bits are calculated for each one of N bitstreams and an N x C NumPy array is returned where C is the CRC length.

  • poly (str) –

    The string specifying the generator polynomial. The following generator polynomials are supported.

    The value of poly

    Generator polynomial

    ’6’

    1100001

    ’11’

    111000100001

    ’16’

    10001000000100001

    ’24A’

    1100001100100110011111011

    ’24B’

    1100000000000000001100011

    ’24C’

    1101100101011000100010111

    For more details please refer to 3GPP TS 38.212, Section 5.1.

Returns:

If bits is a 1D NumPy array, the CRC bits are returned in a 1D NumPy array. If bits is an N x L NumPy array, the CRC bits of N bitstreams are returned in an N x C NumPy array where C is the CRC length.

Return type:

NumPy array

classmethod checkCrc(bits, poly)

Checks the CRC bits at the end of the bitstream bits and returns True if the CRC is valid and False if it is not.

Parameters:

  • bits (NumPy array) – A 1D or 2D NumPy array of bits. If it is a 1D NumPy array, the CRC bits are checked for the given bitstream and a boolean value is returned. If bits is an N x L NumPy array, it is assumed that we have N bitstreams of length L. In this case the CRC bits are checked for each one of N bitstreams and a boolean NumPy array of length N is returned, specifying the CRC check result for each bitstream.

  • poly (str) – The string specifying the generator polynomial. See the getCrc() method above for a list of generator polynomials.

Returns:

If bits is a 1D NumPy array, the CRC check result is returned as a boolean value. If bits is an N x L NumPy array, the CRC check results of N bitstreams are returned in a boolean NumPy array of length N.

Return type:

boolean or NumPy array

classmethod appendCrc(bits, poly)

Calculates the CRC bits for the bitstream bits, appends them to the end of the bitstream, and returns the new bitstream containing the original bits followed by the CRC bits.

This function calls the getCrc() method to get the CRC bits and then appends them to the end of bits.

Parameters:

  • bits (NumPy array) – A 1D or 2D NumPy array of bits. If it is a 1D NumPy array, the CRC bits are calculated for the given bitstream and a 1D NumPy array containing the original bitstream and the CRC bits is returned. If bits is an N x L NumPy array, it is assumed that we have N bitstreams of length L. In this case the CRC bits are calculated and appended to the end of each one of N bitstreams and an N x M NumPy array is returned where M=L+C and C is the CRC length.

  • poly (str) – The string specifying the generator polynomial. See the getCrc() method above for a list of generator polynomials.

Returns:

If bits is a 1D NumPy array, the new bitstream with CRC appended to the end is returned in a 1D NumPy array. If bits is an N x L NumPy array, the CRC bits for each one of N bitstreams are appended to the end and an N x M NumPy array is returned where M=L+C and C is the CRC length.

Return type:

NumPy array

LDPC

The module ldpccodec.py implements the new Low-Density Parity Check (LDPC) coding API for NeoRadium. It provides the LdpcCodec class, which encapsulates both LDPC encoding and decoding functionality for one or two codewords, and the LdpcCodecCW class, which handles the complete LDPC processing chain for a single codeword.

This module replaces the legacy ldpc.py API, which used separate LdpcEncoder and LdpcDecoder classes. In the new design, a single LdpcCodec object creates and manages one or two LdpcCodecCW objects depending on the number of codewords implied by the number of transmission layers. Each codeword codec handles:

  • transport-block CRC attachment and checking,

  • code-block segmentation and reassembly,

  • LDPC encoding and decoding,

  • rate matching and rate recovery,

  • code-block CRC attachment and checking.

This implementation is based on 3GPP TS 38.212 and is intended for NR data-channel processing such as PDSCH and PUSCH, where one or two LDPC-coded codewords may be transmitted depending on the layer configuration.

Migration Guide (LdpcEncoder/LdpcDecoder → LdpcCodec)

The legacy classes LdpcEncoder and LdpcDecoder are deprecated and will be removed in future releases. Users are encouraged to migrate to the new unified LdpcCodec class, which provides a simpler and more compact API for both encoding and decoding. The following examples illustrate how to update existing code.

  • Instantiation:

modulation = "16QAM"       # Modulation scheme
coderate = 490/1024        # Target code rate
txBlockSize = pdsch.getTxBlockSize(coderate)

# Old method -------------------------------------------------------------------------------
ldpcEncoder = LdpcEncoder(baseGraphNo=1, modulation=modulation,
                          txLayers=1, targetRate=coderate)

# New method 1 -----------------------------------------------------------------------------
# Changes:
#   1) 'baseGraphNo' is no longer required (automatically selected).
#   2) 'txBlockSizes' must be provided.
#   3) 'numIter' is specified once during initialization.
ldpc = LdpcCodec(modulations=modulation,
                 coderates=coderate,
                 txBlockSizes=txBlockSize,
                 numLayers=1,
                 numIter=5)

# New method 2 -----------------------------------------------------------------------------
ldpc = pdsch.getLdpcCodec(coderate)

  • Encoding:

# Old method -------------------------------------------------------------------------------
grid = pdsch.getGrid()                                # Create resource grid (with DMRS)
txBlockSize = pdsch.getTxBlockSize(coderate)[0]       # Transport block size (single codeword)
txBlock = random.bits(txBlockSize)                    # Generate random data
numBits = pdsch.getBitSizes(grid)[0]                  # Available bits in grid

rateMatchedCodeBlocks = ldpcEncoder.getRateMatchedCodeBlocks(txBlock, numBits)

# New method -------------------------------------------------------------------------------
pdsch.initGrid()                                     # Initialize grid (replaces 'getGrid')
txBlockSize = pdsch.getTxBlockSize(coderate)[0]
txBlock = random.bits(txBlockSize)
numBits = pdsch.getBitCapacity()[0]                   # Replaces 'getBitSizes'

rateMatchedCodeBlocks = ldpc.encode(txBlock, numBits)

  • Decoding:

# Old method -------------------------------------------------------------------------------
ldpcDecoder = ldpcEncoder.getDecoder()

rxCodedBlocks = ldpcDecoder.recoverRate(llrs[0], txBlockSize[0])
decodedBlocks = ldpcDecoder.decode(rxCodedBlocks, numIter=20)

# Check code block CRCs and merge:
decodedTxBlockWithCRC, crcMatch = ldpcDecoder.checkCrcAndMerge(decodedBlocks)

# Check transport block CRC:
txBlockCrcMatch = ldpcDecoder.checkCrc(decodedTxBlockWithCRC, '24A')

# Remove CRC:
decodedTxBlock = decodedTxBlockWithCRC[:-24]

# New method -------------------------------------------------------------------------------
# Changes:
#   1) Single call to 'decode'.
#   2) 'numIter' is configured during initialization.
#   3) 'crcMatch' is a boolean array:
#        - First element: transport block CRC result
#        - Remaining elements: code block CRC results
#   4) 'decodedTxBlock' excludes the CRC bits.
decodedTxBlock, crcMatch = ldpc.decode(llrs)

  • HARQ:

# Old method -------------------------------------------------------------------------------
ldpcEncoder = LdpcEncoder(baseGraphNo=1, modulation=modulation,
                          txLayers=1, targetRate=coderate)
harq = HarqEntity(ldpcEncoder, harqType, numProc)

# ...
rateMatchedCodeBlocks = harq.getRateMatchedCodeBlocks(txBlocks)      # Encoding
# ...
decodedTxBlocks, blockErrors = harq.decodeLLRs(llrs, txBlockSizes)  # Decoding

# New method -------------------------------------------------------------------------------
# Changes:
#   1) Use 'LdpcCodec' instead of 'LdpcEncoder'.
#   2) Use 'harq.encode' instead of 'getRateMatchedCodeBlocks'.
#   3) Use 'harq.decode' instead of 'decodeLLRs'.
#   4) 'crcMatches' contains CRC results for transport blocks and code blocks.
#   5) 'decodedTxBlocks' contains decoded transport block(s) without CRC.
ldpc = pdsch.getLdpcCodec(coderate)
harq = HarqEntity(ldpc, harqType, numProc)

# ...
rateMatchedCodeBlocks = harq.encode(txBlocks)
# ...
decodedTxBlocks, crcMatches = harq.decode(llrs)
class neoradium.ldpccodec.LdpcCodec(modulations, coderates, txBlockSizes, numLayers=1, numIter=5, nRef=0)

This class encapsulates the complete LDPC encoding and decoding functionality used for NR shared-channel communication based on 3GPP TS 38.212.

A LdpcCodec object manages one or two LdpcCodecCW objects depending on the number of transmission layers. For one-codeword operation (numLayers <= 4), it creates a single LdpcCodecCW object. For two-codeword operation (numLayers > 4), it creates two independent LdpcCodecCW objects, one for each codeword.

This class provides a simplified high-level API that groups together the LDPC processing steps for each codeword, including:

  • transport block CRC attachment,

  • code block segmentation,

  • LDPC encoding,

  • rate matching,

  • rate recovery,

  • LDPC decoding, and

  • CRC checking after decoding.

The two-codeword case is relevant for multi-layer PDSCH transmissions using more than four layers, where the two codewords may use different modulation schemes, target code rates, and transport block sizes.

Parameters:

  • modulations (str, list, or tuple) –

    The modulation scheme or schemes used by the physical channel according to 3GPP TS 38.211, Table 7.3.1.2-1. Supported values are:

    Modulation Scheme

    Modulation Order (qm)

    BPSK

    1

    QPSK

    2

    16QAM

    4

    64QAM

    6

    256QAM

    8

    1024QAM

    10

    If there are two codewords (that is, numLayers > 4), then modulations may contain one or two modulation schemes. If only one modulation is provided, it is used for both codewords.

  • coderates (float, list, or tuple) – One or two target code-rate values. Each value is the ratio of information bits to transmitted bits for one codeword. If there are two codewords and only one value is provided, the same code rate is used for both codewords.

  • txBlockSizes (int, list, or tuple) –

    One or two transport block sizes (TBS), one for each codeword. Each value is the transport block size excluding the 24-bit transport-block CRC. This is the value \(A\) in 3GPP TS 38.212, Section 5.1.

    The method getTxBlockSize() may be used to obtain these values.

  • numLayers (int) – The number of transmission layers used by the physical channel. It must be in the range 1 to 8. The default is 1.

  • numIter (int) – The number of iterations used by the layered belief-propagation decoder in each LdpcCodecCW object. The default is 5. Larger values may improve decoding performance at the cost of increased complexity. For example, see the notebook Effect of LDPC Decoding Iterations on PDSCH BLER.

  • nRef (int) – The value \(N_{ref}\) used for Low-Buffer Rate Matching (LBRM), as described in 3GPP TS 38.212, Section 5.4.2.1. The default is 0, which disables LBRM.

Please refer to the notebook Low-Density Parity Check (LDPC) for examples of using this class.

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

Prints the properties of this LdpcCodec object.

Parameters:

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

  • title (str) – If specified, it is used as the title for the printed information.

  • 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

classmethod getBaseGraphNo(tbs, coderate)

This class method selects the LDPC base graph number based on the specified transport block size (tbs) and coderate (coderate), in accordance with 3GPP TS 38.212, Section 7.2.2.

Parameters:

  • tbs (int) – Transport block size in bits. This value can be obtained using getTxBlockSize() method of the PDSCH class.

  • coderate (float) – The coderate used for transmission.

Returns:

The selected LDPC base graph number (1 or 2).

Return type:

int

encode(txBlocks, g=None, concatCBs=True)

Encodes one or two transport blocks using LDPC coding and returns rate-matched bitstreams ready for modulation.

For each codeword, this function performs the following steps based on 3GPP TS 38.212:

  • Appends a 24-bit transport-block CRC (CRC24A),

  • Performs code block segmentation (and code-block CRC attachment if needed),

  • Applies LDPC encoding,

  • Performs rate matching (including bit selection and interleaving).

Parameters:

  • txBlocks (NumPy array, list, or tuple) –

    The transport block(s) to be encoded.

    • If there is only one codeword (numLayers <= 4), a single NumPy array or a list or tuple containing only one NumPy array may be provided.

    • If there are two codewords (numLayers > 4), a list or tuple of two NumPy arrays must be provided, one for each codeword.

  • g (int, list, tuple, or None) –

    The total number of bits available for transmission (rate-matched output length) for each codeword. This corresponds to \(G\) in 3GPP TS 38.212, Section 5.4.2.1.

    • If a single codeword is used, this can be a single integer.

    • If two codewords are used, this must be a list or tuple of two integers.

    • If not provided (None), it is computed internally for each codeword as:

      \(G = \lceil A / R \rceil\)

      where \(A\) is the transport block size, and \(R\) is the target code rate.

  • concatCBs (bool) –

    If True (default), the rate-matched coded blocks for each codeword are concatenated into a single 1D NumPy array.

    If False, a 2D C x Er NumPy array is returned for each codeword, where C is the number of code blocks and Er is the rate-matched length per code block.

Returns:

The encoded and rate-matched output(s):

  • For a single codeword:

    • If concatCBs=True: a 1D NumPy array of length \(G\).

    • Otherwise: a 2D NumPy array of shape C x Er.

  • For two codewords:

    • A list of two elements is returned, one per codeword.

    • Each element follows the same structure as the single-codeword case.

Return type:

NumPy array or list

Notes

This function operates independently on each codeword when numLayers > 4. Each codeword may have different modulation, code rate, and transport block size.

decode(llrs)

Decodes one or two sets of log-likelihood ratios (LLRs) into transport blocks using LDPC decoding.

For each codeword, this function performs the following steps based on 3GPP TS 38.212:

  • Rate recovery (inverse of rate matching),

  • LDPC decoding using layered belief propagation,

  • Code-block CRC checking and merging,

  • Transport-block CRC checking (CRC24A),

  • Removal of the transport-block CRC.

Parameters:

llrs (NumPy array, list, or tuple) –

The input log-likelihood ratios (LLRs) corresponding to the received bits.

  • If there is only one codeword (numLayers <= 4), a single NumPy array or a list or tuple containing only one NumPy array must be provided.

  • If there are two codewords (numLayers > 4), a list or tuple of two NumPy arrays must be provided, one for each codeword.

Each LLR value is a real number, where positive values indicate higher likelihood of bit 0 and negative values indicate higher likelihood of bit 1.

Returns:

A tuple containing:

  • decodedTxBlocksNumPy array or list

    The decoded transport block(s) (without CRC bits).

    • For a single codeword: a 1D NumPy array of length \(A\).

    • For two codewords: a list of two NumPy arrays.

  • crcMatchesNumPy array or list

    CRC check results for each codeword.

    Each element is a boolean array of length C + 1:

    • The first element corresponds to the transport-block CRC (CRC24A),

    • The remaining elements correspond to code-block CRCs (CRC24B) when segmentation is used.

    For two codewords, a list of two such arrays is returned.

Return type:

tuple

Notes

  • The decoding process uses the layered belief propagation algorithm with min-sum approximation.

  • The number of decoding iterations is controlled by the numIter parameter provided during initialization.

  • When HARQ is used internally (via lower-level APIs), soft combining is supported through the rate recovery stage.

class neoradium.ldpccodec.LdpcCodecCW(modulation, coderate, txBlockSize, numLayers, numIter, nRef)

This class implements the LDPC encoding and decoding functionality for a single codeword based on 3GPP TS 38.212.

A LdpcCodecCW object contains all configuration and processing logic needed for one codeword, including:

  • base-graph selection,

  • transport block CRC attachment,

  • code block segmentation,

  • code-block CRC attachment when segmentation is used,

  • lifting-size selection,

  • LDPC encoding,

  • rate matching,

  • rate recovery,

  • LDPC decoding using layered belief propagation with min-sum approximation, and

  • CRC checking and code-block merging after decoding.

This class is usually created internally by LdpcCodec and is not normally instantiated directly by the user unless per-codeword control is specifically desired.

Parameters:

  • modulation (str) –

    The modulation scheme used by the physical channel for this codeword according to 3GPP TS 38.211, Table 7.3.1.2-1. Supported values are:

    Modulation Scheme

    Modulation Order (qm)

    BPSK

    1

    QPSK

    2

    16QAM

    4

    64QAM

    6

    256QAM

    8

    1024QAM

    10

  • coderate (float) – The target code rate for this codeword. It is used together with the transport block size to determine the LDPC base graph and the default rate-matched output length.

  • txBlockSize (int) – The transport block size (TBS) for this codeword, excluding the 24-bit transport-block CRC. This is the value \(A\) in 3GPP TS 38.212, Section 5.1.

  • numLayers (int) – The total number of transmission layers for this codeword. This value is used in rate matching because the rate-matched code-block lengths must be multiples of numLayers * qm.

  • numIter (int) – The number of decoder iterations used by the layered belief-propagation algorithm. Larger values may improve decoding performance at the cost of increased complexity.

  • nRef (int) – The value \(N_{ref}\) used for Low-Buffer Rate Matching (LBRM), as defined in 3GPP TS 38.212, Section 5.4.2.1. A value of 0 disables LBRM.

Other Properties:

qm:

The modulation order corresponding to modulation.

baseGraphNo:

The selected base-graph number, either 1 or 2, determined from txBlockSize and coderate according to LdpcCodec.getBaseGraphNo().

baseGraph:

The lifted base-graph matrix used by the encoder and decoder. It is derived from the selected base graph in 3GPP TS 38.212, Tables 5.3.2-2 and 5.3.2-3 and the selected lifting size.

numCodeBlocks:

The number of code blocks obtained after transport-block segmentation. This is the value \(C\) in 3GPP TS 38.212, Section 5.2.2.

codeBlockSize:

The code-block size \(K\), including the code-block CRC if segmentation is used, and including filler bits.

liftingSize:

The selected lifting size \(Z_c\), chosen from 3GPP TS 38.212, Table 5.3.2-1.

setIndex:

The set index \(i_{LS}\) corresponding to the selected lifting size.

numFillerBits:

The number of filler bits appended to each code block after segmentation.

Notes

The transport-block CRC is always 24 bits and uses CRC24A.

If segmentation results in more than one code block, each code block is appended with a 24-bit CRC using CRC24B.

The encoding process implemented by this class corresponds to:

  • transport-block CRC attachment,

  • code-block segmentation,

  • LDPC encoding, and

  • rate matching.

The decoding process implemented by this class corresponds to:

  • rate recovery,

  • LDPC decoding,

  • code-block CRC checking,

  • code-block merging, and

  • transport-block CRC checking.

isValidCodedBlock(codedBlock)

Checks whether the given codedBlock is a valid LDPC coded bitstream.

Parameters:

codedBlock (NumPy array) – A NumPy array of bits representing the coded block. The length of codedBlock must be a multiple of the property liftingSize (\(Z_c\)).

Returns:

True is returned if this is a valid LDPC coded block. Otherwise, this function returns False.

Return type:

boolean

doSegmentation(txBlock)

The first step in LDPC encoding process is breaking down the transport block into smaller more manageable code blocks. This function receives a transport block txBlock, performs segmentation based on 3GPP TS 38.212, Section 5.2.2, and outputs a 2D C x K NumPy array containing C code blocks of length K.

../../_images/TxpBlock.jpg

Transport Block Segmentation [1]

Parameters:

txBlock (NumPy array) – A NumPy array of bits containing the transport block information (including the 24-bit CRC).

Returns:

A 2D C x K NumPy array containing C code blocks of length K.

Return type:

NumPy array

encodeCodeBlocks(codeBlocks, puncture=True)

This function encodes a set of code blocks and returns a set of LDPC coded blocks based on the procedure explained in 3GPP TS 38.212, Section 5.3.2.

Parameters:

  • codeBlocks (NumPy array) – A C x K NumPy array containing C code blocks of length K being LDPC-encoded by this function.

  • puncture (bool) – By default, the first \(2Z_c\) bits of the code blocks are punctured (removed). If puncture=False, then the first \(2Z_c\) bits are kept in the returned encoded blocks.

Returns:

A C x N NumPy array containing the C encoded blocks.

Return type:

NumPy array

rateMatch(codedBlocks, g=None, concatCBs=True, rv=0)

This function receives a set of encoded blocks and returns the rate-matched output based on the configured code rate. It performs bit selection and interleaving based on 3GPP TS 38.212, Section 5.4.2

Parameters:

  • codedBlocks (NumPy array) – A C x N NumPy array containing C encoded code blocks of length N being rate-matched by this function.

  • g (int or None) – This is the total number of bits available for transmission of the transport block. It is the value \(G\) in the bit selection process explained in 3GPP TS 38.212, Section 5.4.2.1. If not provided (default), it is calculated as \(G=\lceil \frac A R \rceil\) where \(A\) is the transport block size and \(R\) is the code rate.

  • concatCBs (bool) – If True (Default), the rate-matched coded blocks are concatenated and a single array of bits is returned. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

  • rv (int) – The Redundancy Version used with Hybrid Automatic Repeat Request (HARQ). It must be one of 0, 1, 2, or 3. Please refer to 3GPP TS 38.212, Table 5.4.2.1-2 for more details. The default is 0 which means first transmission.

Returns:

If concatCBs is True, a 1-D NumPy array is returned containing the concatenation of all rate-matched coded blocks. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

Return type:

NumPy array or list of NumPy arrays

encode(txBlock, g=None, concatCBs=True, harqCW=None)

Encodes a single transport block using LDPC coding and returns a rate-matched bitstream ready for modulation.

This function performs the complete LDPC encoding pipeline for one codeword based on 3GPP TS 38.212:

  • Appends a 24-bit transport-block CRC (CRC24A),

  • Performs code block segmentation (and code-block CRC attachment if required),

  • Applies LDPC encoding,

  • Performs rate matching (including bit selection and interleaving).

Parameters:

  • txBlock (NumPy array) – A 1D NumPy array of bits representing the transport block of size \(A\) (without CRC).

  • g (int or None) –

    The total number of bits available for transmission after rate matching. This corresponds to \(G\) in 3GPP TS 38.212, Section 5.4.2.1.

    If None, it is computed internally as:

    \(G = \lceil A / R \rceil\)

    where \(A\) is the transport block size, and \(R\) is the target code rate.

  • concatCBs (bool) –

    If True, the rate-matched coded blocks are concatenated into a single 1D NumPy array.

    If False, a 2D C x Er NumPy array is returned, where:

    • C is the number of code blocks,

    • Er is the rate-matched length per code block.

  • harqCW (HarqCW) – The HarqCW object handling retransmissions for each codeword. If specified, this method updates the encoding buffer in the HarqCW object with the encoded code blocks.

Returns:

The encoded and rate-matched output:

  • If concatCBs=True: a 1D NumPy array of length \(G\).

  • Otherwise: a 2D NumPy array of shape C x Er.

Return type:

NumPy array

Notes

  • This function operates on a single codeword.

  • The transport-block CRC (CRC24A) is always added internally.

  • Code-block CRCs (CRC24B) are added only when segmentation is performed.

recoverRate(rxBlock, harqCW=None)

This function receives an array of log-likelihood ratios (LLRs) in rxBlock, and the transport block size txBlockSize, and returns a set of rate-recovered LLRs for each code block that is ready for LDPC decoding. This function does the exact opposite of the rateMatch() method. Note that while the rateMatch() works with bits, this method works on LLRs.

The LLRs are usually obtained by performing demodulation process. For example, the getLLRsFromGrid() method of the PDSCH class can be used to get LLRs from a received resource grid.

Parameters:

  • rxBlock (NumPy array) – A NumPy array of log-likelihood ratios (LLRs) obtained as a result of demodulation process. Each element is a real LLR value corresponding to each received bit. The larger the LLR value, the more likely it is for that bit to be a 0.

  • harqCW (HarqCW) – The HarqCW object handling retransmissions for each codeword. If specified, this method uses this object to obtain the ‘Redundancy Version’ and the circular buffer of the previous transmission of the same transport block.

Returns:

A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block ready to be LDPC-decoded.

Return type:

NumPy array

decodeCodeBlocks(rxCodeBlock, onlyInfoBits=True, outputBelief=False)

This function implements the Layered Belief Propagation algorithm for LDPC-decoding of LLRs into decoded code blocks. This implementation was inspired mostly by LDPC and Polar Codes in 5G Standard set of videos and was written from scratch to efficiently perform the decoding process.

Parameters:

  • rxCodeBlock (NumPy array) – A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block.

  • onlyInfoBits (bool) – If True (default), only the information bits are returned. Otherwise, the parity bits are also included in the returned values together with the information bits.

  • outputBelief (bool) – If True, the calculated final belief values are returned for each bit which is the LLR for the decoded bits. Otherwise (default), hard decision is applied to the final belief values and the decoded bits are returned.

Returns:

If onlyInfoBits is set to True, a C x K NumPy array of C code blocks of length K is returned, where K is the codeBlockSize. Otherwise, the parity bit information is also included in the returned NumPy array which makes each code block longer than K. The contents of the return NumPy array can be bits or belief values based on the outputBelief parameter.

Return type:

NumPy array

checkCrcAndMerge(rxCodedBlocks)

This function performs CRC checking on the each code block, re-assembles the transport block by combining the code blocks, and returns the transport block together with the results of CRC checks for each code block.

Note that the returned value of this function includes the 24 bits of transport block CRC. The transport block CRC can be checked using the checkCrc() method.

Parameters:

rxCodedBlocks (NumPy array) – A C x K NumPy array of C code blocks of length K. Each code block contains a CRC as its last 24 bits. The rxCodedBlocks is usually the returned value of the decode() method explained above.

Returns:

  • txBlock (NumPy array of bits) – The NumPy array containing the transport block together with its 24-bit CRC at the end which can be verified using the checkCrc() method.

  • crcCheckResults (NumPy array of booleans) – The boolean NumPy array containing the CRC check results for each code block. To have a valid transport block, all of the values in this NumPy array must be True.

decode(llrs, harqCW=None)

Decodes a single codeword from log-likelihood ratios (LLRs) into a transport block using LDPC decoding.

This function performs the complete LDPC decoding pipeline for one codeword based on 3GPP TS 38.212:

  • Rate recovery (inverse of rate matching),

  • LDPC decoding using layered belief propagation,

  • Code-block CRC checking and merging,

  • Transport-block CRC checking (CRC24A),

  • Removal of the transport-block CRC.

Parameters:

  • llrs (NumPy array) –

    A 1D NumPy array of log-likelihood ratios (LLRs) corresponding to the received bits.

    Each LLR is a real value where:

    • Positive values indicate higher likelihood of bit 0,

    • Negative values indicate higher likelihood of bit 1.

  • harqCW (HarqCW) – The HarqCW object handling retransmissions for each codeword. If specified, this method uses this object to obtain the ‘Redundancy Version’ and the circular buffer of the previous transmission of the same transport block.

Returns:

A tuple containing:

  • decodedTxBlockNumPy array

    A 1D NumPy array of decoded transport block bits of length \(A\) (CRC removed).

  • crcMatchNumPy array of bool

    A boolean array of length C + 1 indicating CRC check results:

    • The first element corresponds to the transport-block CRC (CRC24A),

    • The remaining elements correspond to code-block CRCs (CRC24B) if segmentation is used.

Return type:

tuple

Notes

  • The LDPC decoding uses a layered belief propagation algorithm with min-sum approximation.

  • The number of decoding iterations is controlled by the numIter parameter of the class.

  • Soft combining for HARQ can be supported via the recoverRate method when used with a HARQ buffer.

Polar Coding

The module polar.py contains the API used for Polar coding. It implements the class PolarBase, which is the base class for other polar coding classes and is derived from the ChanCodeBase class. It also implements the classes PolarEncoder and PolarDecoder both of which are derived from PolarBase. This implementation is based on 3GPP TS 38.212.

Please refer to the notebook Polar Coding for examples of using PolarEncoder and PolarDecoder classes.

class neoradium.polar.PolarBase(payloadSize=0, rateMatchedLen=0, dataType=None, **kwargs)

This is the base class for all polar coding classes. Both PolarEncoder and PolarDecoder classes are derived from it. In 5G NR, polar coding is used for the following cases:

  • Downlink Control Information (DCI)

  • Uplink Control Information (UCI)

  • Physical Broadcast Channel (PBCH)

Parameters:

  • payloadSize (int) – The size of input bitstream not including the CRC bits. This is the value \(A\) in 3GPP TS 38.212, Section 5.2.1.

  • rateMatchedLen (int) – The total length of rate-matched output bitstream. This is the value \(E\) in 3GPP TS 38.212, Sections 5.3.1 and 5.4.1.

  • dataType (str or None) –

    The type of data using this Polar encoder/decoder. It can be one of the following:

    ”DCI”:

    Downlink Control Information

    ”UCI”:

    Uplink Control Information

    ”PBCH”:

    Physical Broadcast Channel

    None:

    Customized Polar Coding.

  • kwargs (dict) –

    A set of optional arguments depending on the dataType:

    iBIL:

    Coded bits Interleaving flag. This is a boolean value that indicates whether coded bits interleaving is enabled (True) or disabled (False). By default iBIL=False. This is the value \(I_{BIL}\) in 3GPP TS 38.212, Section 5.4.1.3. This parameter is ignored if the dataType is not None. In this case, iBIL is set to True for dataType="UCI", and False for dataType="DCI" and dataType="PBCH" cases.

    nMax:

    Max value of \(n\) where \(N=2^n\) is the length of the polar code. By default this is set to 10 (which means \(N=1024\). This is the value \(N_{max}\) in 3GPP TS 38.212, Section 5.3.1.2. This parameter is ignored if the dataType is not None. In this case, nMax=10 when dataType="UCI", and nMax=9 for dataType="DCI" and dataType="PBCH" cases.

    iIL:

    Input Interleaving flag. This is a boolean value that indicates whether input interleaving is enabled (True) or disabled (False). By default iIL=False. This is the value \(I_{IL}\) in 3GPP TS 38.212, Section 5.3.1.1. This parameter is ignored if the dataType is not None. In this case, iIL is set to False for dataType="UCI", and True for dataType="DCI" and dataType="PBCH" cases.

    nPC:

    Total number of parity-check bits. By default this is set to 0. This is the value \(N_{PC}\) in 3GPP TS 38.212, Section 5.3.1. This parameter is ignored if the dataType is not None. In this case, nPC=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 3 which is determined based on the procedure explained in 3GPP TS 38.212, Section 5.3.1.2.

    nPCwm:

    The number of Low-weight, High-Reliability parity-check bits out of the total parity-check bits nPC. By default this is set to 0. This is the value \(n_{PC}^{wm}\) in 3GPP TS 38.212, Sections 5.3.1.2, 6.3.1.3.1, and 6.3.2.3.1. This parameter is ignored if the dataType is not None. In this case, nPCwm=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 1 which is determined based on the procedure explained in 3GPP TS 38.212, Sections 6.3.1.3.1 and 6.3.2.3.1.

    iSeg:

    Segmentation flag. This is a boolean value that indicates whether segmentation is enabled (True) or disabled (False). By default iSeg=False. This is the value \(I_{seg}\) in 3GPP TS 38.212, Section 5.2.1. This parameter is ignored if the dataType is not None. In this case, iSeg=False when dataType="DCI" or dataType="PBCH". When dataType="UCI", iSeg is set based on the value of payloadSize.

    crcPoly:

    The CRC polynomial. This is a string specifying the CRC polynomial or None. If specified, it must be one of the values specified in getCrc() for the poly parameter. The default value is "11". This parameter is ignored if the dataType is not None. In this case crcPoly is set to "6" or "11" depending on payloadSize for dataType="UCI", and "24C" for dataType="DCI" and dataType="PBCH" cases.

Other Properties:

rateMatchedBlockLen:

The number of rate-matched bits transmitted for each code block when segmented. This is the same as rateMatchedLen if segmentation is disabled. This is the value \(E_r\) in 3GPP TS 38.212, Section 5.5.

codeBlockSize:

The code block size. This is the value \(K\) in 3GPP TS 38.212, Section 5.3.1 which includes the CRC bits (if any).

polarCodeSize:

The polar code size \(N\). This is always a power of 2.

msgBits:

A list of indices of the message bits in the coded bitstream.

frozenBits:

A list of indices of the frozen bits in the coded bitstream.

pcBits:

A list of indices of the parity-check bits in the coded bitstream. This can be empty depending on nPC.

generator:

The polar coding generator matrix as a 2-D NumPy array.

setIoSizes(payloadSize, rateMatchedLen)

This function can be called to re-initialize the class properties. When the payloadSize or rateMatchedLen parameters change but other properties remain the same, you can either create a new polar encoder/decoder object or reuse the existing objects and re-initialize them using this method.

Note that if there is no change in the values of payloadSize and rateMatchedLen, this function returns without doing anything.

Parameters:

  • payloadSize (int) – The new size of input bitstream not including the CRC bits. This is the value \(A\) in 3GPP TS 38.212, Section 5.2.1.

  • rateMatchedLen (int) – The new total length of rate-matched output bitstream. This is the value \(E\) in 3GPP TS 38.212, Sections 5.3.1 and 5.4.1.

class neoradium.polar.PolarEncoder(payloadSize=0, rateMatchedLen=0, dataType=None, **kwargs)

This class is used to encode a bitstream using Polar coding. It is derived from the PolarBase class and performs the following tasks:

  • Segmentation of the transport block based on 3GPP TS 38.212, Section 5.2.1

  • Polar encoding based on 3GPP TS 38.212, Section 5.3.1

  • Rate Matching with Sub-block interleaving, bit selection, and interleaving of coded bits based on 3GPP TS 38.212, Section 5.4.1

Parameters:

  • payloadSize (int) – The size of input bitstream not including the CRC bits. This is the value \(A\) in 3GPP TS 38.212, Section 5.2.1.

  • rateMatchedLen (int) – The total length of rate-matched output bitstream. This is the value \(E\) in 3GPP TS 38.212, Sections 5.3.1 and 5.4.1.

  • dataType (str or None) –

    The type of data using this Polar encoder/decoder. It can be one of the following:

    ”DCI”:

    Downlink Control Information

    ”UCI”:

    Uplink Control Information

    ”PBCH”:

    Physical Broadcast Channel

    None:

    Customized Polar Coding.

  • kwargs (dict) –

    A set of optional arguments depending on the dataType:

    iBIL:

    Coded bits Interleaving flag. This is a boolean value that indicates whether coded bits interleaving is enabled (True) or disabled (False). By default iBIL=False. This is the value \(I_{BIL}\) in 3GPP TS 38.212, Section 5.4.1.3. This parameter is ignored if the dataType is not None. In this case, iBIL is set to True for dataType="UCI", and False for dataType="DCI" and dataType="PBCH" cases.

    nMax:

    Max value of \(n\) where \(N=2^n\) is the length of the polar code. By default this is set to 10 (which means \(N=1024\). This is the value \(N_{max}\) in 3GPP TS 38.212, Section 5.3.1.2. This parameter is ignored if the dataType is not None. In this case, nMax=10 when dataType="UCI", and nMax=9 for dataType="DCI" and dataType="PBCH" cases.

    iIL:

    Input Interleaving flag. This is a boolean value that indicates whether input interleaving is enabled (True) or disabled (False). By default iIL=False. This is the value \(I_{IL}\) in 3GPP TS 38.212, Section 5.3.1.1. This parameter is ignored if the dataType is not None. In this case, iIL is set to False for dataType="UCI", and True for dataType="DCI" and dataType="PBCH" cases.

    nPC:

    Total number of parity-check bits. By default this is set to 0. This is the value \(N_{PC}\) in 3GPP TS 38.212, Section 5.3.1. This parameter is ignored if the dataType is not None. In this case, nPC=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 3 which is determined based on the procedure explained in 3GPP TS 38.212, Section 5.3.1.2.

    nPCwm:

    The number of Low-weight, High-Reliability parity-check bits out of the total parity-check bits nPC. By default this is set to 0. This is the value \(n_{PC}^{wm}\) in 3GPP TS 38.212, Sections 5.3.1.2, 6.3.1.3.1, and 6.3.2.3.1. This parameter is ignored if the dataType is not None. In this case, nPCwm=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 1 which is determined based on the procedure explained in 3GPP TS 38.212, Sections 6.3.1.3.1 and 6.3.2.3.1.

    iSeg:

    Segmentation flag. This is a boolean value that indicates whether segmentation is enabled (True) or disabled (False). By default iSeg=False. This is the value \(I_{seg}\) in 3GPP TS 38.212, Section 5.2.1. This parameter is ignored if the dataType is not None. In this case, iSeg=False when dataType="DCI" or dataType="PBCH". When dataType="UCI", iSeg is set based on the value of payloadSize.

    crcPoly:

    The CRC polynomial. This is a string specifying the CRC polynomial or None. If specified, it must be one of the values specified in getCrc() for the poly parameter. The default value is "11". This parameter is ignored if the dataType is not None. In this case crcPoly is set to "6" or "11" depending on payloadSize for dataType="UCI", and "24C" for dataType="DCI" and dataType="PBCH" cases.

Other Properties:

rateMatchedBlockLen:

The number of rate-matched bits transmitted for each code block when segmented. This is the same as rateMatchedLen if segmentation is disabled. This is the value \(E_r\) in 3GPP TS 38.212, Section 5.5.

codeBlockSize:

The code block size. This is the value \(K\) in 3GPP TS 38.212, Section 5.3.1 which includes the CRC bits (if any).

polarCodeSize:

The polar code size \(N\). This is always a power of 2.

msgBits:

A list of indices of the message bits in the coded bitstream.

frozenBits:

A list of indices of the frozen bits in the coded bitstream.

pcBits:

A list of indices of the parity-check bits in the coded bitstream. This can be empty depending on nPC.

generator:

The polar coding generator matrix as a 2-D NumPy array.

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

Prints the properties of this PolarEncoder object.

Parameters:

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

  • title (str) – If specified, it is used as the title for the printed information.

  • 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

doSegmentation(txBlock)

If segmentation is enabled, the first step in Polar coding process involves breaking down the transport block into smaller code blocks. This function receives a transport block txBlock, performs segmentation depending on the value of iSeg property based on 3GPP TS 38.212, Section 5.2.1, and outputs a 2D C x K NumPy array containing C code blocks of length K. Note that C can only be 1 or 2 and if iSeg=False, then C=1.

Parameters:

txBlock (NumPy array) – A NumPy array of bits containing the transport block information.

Returns:

A 2D C x K NumPy array containing C code blocks of length K.

Return type:

NumPy array

encode(codeBlocks)

This function encodes a set of code blocks and returns a set of Polar-coded code blocks based on the procedure explained in 3GPP TS 38.212, Section 5.3.1.

Parameters:

codeBlocks (NumPy array) – A C x K NumPy array containing C code blocks of length K being Polar-encoded by this function.

Returns:

A C x N NumPy array containing the C encoded code blocks.

Return type:

NumPy array

rateMatch(codeBlocks)

This function receives a set of encoded code blocks and returns the rate-matched code blocks. It first performs Sub-block interleaving based on 3GPP TS 38.212, Section 5.4.1.1, then bit selection is done based on 3GPP TS 38.212, Section 5.4.1.2. Finally, if Coded bits Interleaving is enabled (iBIL=True), this function applies the procedure in 3GPP TS 38.212, Section 5.4.1.3 for Coded bits Interleaving.

Parameters:

codeBlocks (NumPy array) – A C x N NumPy array containing C encoded code blocks of length N being rate-matched by this function.

Returns:

A C x E NumPy array containing the C rate-matched code blocks of length E where E=rateMatchedBlockLen.

Return type:

NumPy array

class neoradium.polar.PolarDecoder(payloadSize=0, rateMatchedLen=0, dataType=None, **kwargs)

This class is used to decode a set of Log-Likelihood-Ratios (LLRs) to a transport block using the Successive Cancellation List (SCL) [2] algorithm. It is derived from the PolarBase class and performs rate recovery and Polar decoding which are basically the opposite of the encoding tasks performed in reverse order.

The following example shows a typical use case for decoding the received Polar-coded information into transport blocks:

An example of Polar decoding
payloadLen = 30             # A
rateMatchedLen = 120        # E

# Creating a polar decoder object for "DCI" data
polarDecoder = PolarDecoder(payloadLen, rateMatchedLen, 'dci', sclListSize=8, useMinsum=True)

# Rate recovery (Assuming "llrs" contains the LLR values from demodulation process)
rateRecoveredRxBlocks = polarDecoder.recoverRate(llrs)

# Polar Decoding using SCL algorithm
decTxBlock, numCrcErrors = polarDecoder.decode(rateRecoveredRxBlocks)
Parameters:

  • payloadSize (int) – The size of input bitstream not including the CRC bits. This is the value \(A\) in 3GPP TS 38.212, Section 5.2.1.

  • rateMatchedLen (int) – The total length of rate-matched output bitstream. This is the value \(E\) in 3GPP TS 38.212, Sections 5.3.1 and 5.4.1.

  • dataType (str or None) –

    The type of data using this Polar decoder. It can be one of the following:

    ”DCI”:

    Downlink Control Information

    ”UCI”:

    Uplink Control Information

    ”PBCH”:

    Physical broadcast channel

    None:

    Customized Polar Coding.

  • kwargs (dict) –

    A set of optional arguments depending on the dataType:

    iBIL:

    Coded bits Interleaving flag. This is a boolean value that indicates whether coded bits interleaving is enabled (True) or disabled (False). By default iBIL=False. This is the value \(I_{BIL}\) in 3GPP TS 38.212, Section 5.4.1.3. This parameter is ignored if the dataType is not None. In this case, iBIL is set to True for dataType="UCI", and False for dataType="DCI" and dataType="PBCH" cases.

    nMax:

    Max value of \(n\) where \(N=2^n\) is the length of the polar code. By default this is set to 10 (which means \(N=1024\). This is the value \(N_{max}\) in 3GPP TS 38.212, Section 5.3.1.2. This parameter is ignored if the dataType is not None. In this case, nMax=10 when dataType="UCI", and nMax=9 for dataType="DCI" and dataType="PBCH" cases.

    iIL:

    Input Interleaving flag. This is a boolean value that indicates whether input interleaving is enabled (True) or disabled (False). By default iIL=False. This is the value \(I_{IL}\) in 3GPP TS 38.212, Section 5.3.1.1. This parameter is ignored if the dataType is not None. In this case, iIL is set to False for dataType="UCI", and True for dataType="DCI" and dataType="PBCH" cases.

    nPC:

    Total number of parity-check bits. By default this is set to 0. This is the value \(N_{PC}\) in 3GPP TS 38.212, Section 5.3.1. This parameter is ignored if the dataType is not None. In this case, nPC=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 3 which is determined based on the procedure explained in 3GPP TS 38.212, Section 5.3.1.2.

    nPCwm:

    The number of Low-weight, High-Reliability parity-check bits out of the total parity-check bits nPC. By default this is set to 0. This is the value \(n_{PC}^{wm}\) in 3GPP TS 38.212, Sections 5.3.1.2, 6.3.1.3.1, and 6.3.2.3.1. This parameter is ignored if the dataType is not None. In this case, nPCwm=0 when dataType is set to "DCI" or "PBCH". For the "UCI" case, this value may be set to 0 or 1 which is determined based on the procedure explained in 3GPP TS 38.212, Sections 6.3.1.3.1 and 6.3.2.3.1.

    iSeg:

    Segmentation flag. This is a boolean value that indicates whether segmentation is enabled (True) or disabled (False). By default iSeg=False. This is the value \(I_{seg}\) in 3GPP TS 38.212, Section 5.2.1. This parameter is ignored if the dataType is not None. In this case, iSeg=False when dataType="DCI" or dataType="PBCH". When dataType="UCI", iSeg is set based on the value of payloadSize.

    crcPoly:

    The CRC polynomial. This is a string specifying the CRC polynomial or None. If specified, it must be one of the values specified in getCrc() for the poly parameter. The default value is "11". This parameter is ignored if the dataType is not None. In this case crcPoly is set to "6" or "11" depending on payloadSize for dataType="UCI", and "24C" for dataType="DCI" and dataType="PBCH" cases.

    sclListSize:

    The list size of the Successive Cancellation List (SCL) algorithm used for decoding. The default is 8.

    useMinsum:

    A boolean value indicating whether the Min-Sum approximation should be used in the SCL algorithm. True (default) means the “Min-Sum” approximation is used resulting in faster decoding with slightly less precise results. False means the actual extrinsic likelihood function based on hyperbolic tangent function is used.

Note

For a pair of PolarEncoder/PolarDecoder objects to work properly, the above parameters used to configure them should match.

Please refer to PolarBase class for a list of properties inherited from the base class.

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

Prints the properties of this PolarDecoder object.

Parameters:

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

  • title (str) – If specified, it is used as the title for the printed information.

  • 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

recoverRate(rxBlock)

This function receives an array of log-likelihood ratios (LLRs) in rxBlock and returns a set of rate-recovered LLRs for each code block which are ready for Polar decoding. This function does the exact opposite of the PolarEncoder’s rateMatch() method. Note that while the rateMatch() works with bits, this method works on LLRs which are usually obtained by performing demodulation process.

Parameters:

rxBlock (NumPy array) – A NumPy array of log-likelihood ratios (LLRs) obtained as a result of demodulation process. Each element is a real LLR value corresponding to a each received bit. The larger the LLR value, the more likely it is for that bit to be a 0.

Returns:

A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block ready to be polar-decoded.

Return type:

NumPy array

decode(rxLlrBlocks)

This function implements the Successive Cancellation List (SCL) algorithm for Polar-decoding of LLRs into decoded transport blocks. This implementation was inspired mostly by LDPC and Polar Codes in 5G Standard set of videos and was written from scratch using a recursive algorithm to efficiently perform the SCL decoding process.

Parameters:

rxLlrBlocks (NumPy array) – A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block.

Returns:

  • txBlock (NumPy array of bits) – A 1D NumPy array of length \(A\) containing the decoded transport block bits where \(A\) is equal to the parameter payloadSize.

  • numCrcErrors (int) – The total number of CRC errors if crcPoly is not None, otherwise, zero.

LDPC (Legacy)

DEPRECATED: The API in this module is deprecated and will be removed in future releases. Please use the LdpcCodec API.

The module ldpc.py contains the API used for Low-Density Parity Check (LDPC) encoding and decoding. It implements the class LdpcBase, which is the base class for LDPC coding and is derived from the ChanCodeBase class. It also implements the classes LdpcEncoder and LdpcDecoder both of which are derived from LdpcBase.

This implementation is based on 3GPP TS 38.212.

class neoradium.ldpc.LdpcBase(baseGraphNo=1, modulation='QPSK', txLayers=1, nRef=0)

This is the base class for LDPC coding. Both LdpcEncoder and LdpcDecoder classes are derived from this class.

Parameters:

  • baseGraphNo (int) – The base graph used by the LDPC encoder/decoder. It can be either 1 or 2. The choice of base graph determines the maximum code block size (8448 bits for base graph 1 and 3840 bits for base graph 2). The base graphs are defined as \(H_{BG}\) in 3GPP TS 38.212, Tables 5.3.2-2 and 5.3.2-3.

  • modulation (str) –

    The modulation scheme used by the physical channel based on table 7.3.1.2-1 in 3GPP TS 38.211. Here is a list of supported Modulation Schemes:

    Modulation Scheme

    Modulation Order (qm)

    BPSK

    1

    QPSK

    2

    16QAM

    4

    64QAM

    6

    256QAM

    8

    1024QAM

    10

  • txLayers (int) – The number of transmission layers in the physical channel using this LDPC encoder/decoder.

  • nRef (int) – This is used for Low-Buffer Rate Matching (LBRM). This is the value \(N_{ref}\) as explained in 3GPP TS 38.212, Section 5.4.2.1.

Other Properties:

baseGraph:

The base graph matrix defined as \(H_{BG}\) in 3GPP 3GPP TS 38.212, Tables 5.3.2-2 and 5.3.2-3.

maxCodeBlockSize:

The maximum code block size. It is set to 8448 for baseGraphNo=1, and 3840 for baseGraphNo=2. This is \(K_{cb}\) in 3GPP TS 38.212, Section 5.2.2.

txBlockSize:

Transport block size. The length of the transport block in bits. The function getTxBlockSize() could be used to obtain the size of the transport block. Note that a transport block is first appended with a 24-bit CRC. The value txBlockSize includes the 24-bit CRC. This is \(B\) in 3GPP TS 38.212, Section 5.2.2.

numCodeBlocks:

The number of code blocks. This is a positive integer, determined based on maxCodeBlockSize and txBlockSize. This is \(C\) in 3GPP TS 38.212, Section 5.2.2.

codeBlockSize:

The code block size. This is \(K\) in 3GPP TS 38.212, Section 5.2.2.

liftingSize:

The lifting size which is used to create a parity-check matrix from the base graph. This value is extracted from 3GPP TS 38.212, Table 5.3.2-1. This is \(Z_c\) in 3GPP TS 38.212, Section 5.2.2.

setIndex:

The Set index (\(i_{LS}\)) in 3GPP TS 38.212, Table 5.3.2-1.

Note

All of these properties are initialized only after a call to doSegmentation() or getRateMatchedCodeBlocks() methods of LdpcEncoder class or the recoverRate() method of LdpcDecoder class.

isValidCodedBlock(codedBlock)

Checks whether the given codedBlock is a valid LDPC coded bitstream.

Parameters:

codedBlock (NumPy array) – A NumPy array of bits representing the coded block. The length of codedBlock must be a multiple of the property liftingSize (\(Z_c\)).

Returns:

True is returned if this is a valid LDPC coded block. Otherwise, this function returns False.

Return type:

boolean

classmethod getBaseGraphNo(tbs, codeRate)

This class method selects the LDPC base graph number based on the specified transport block size (tbs) and coderate (codeRate), in accordance with 3GPP TS 38.212, Section 7.2.2.

Parameters:

  • tbs (int) – Transport block size in bits. This value can be obtained using getTxBlockSize() method of the PDSCH class.

  • codeRate (float) – The coderate used for transmission.

Returns:

The selected LDPC base graph number (1 or 2).

Return type:

int

class neoradium.ldpc.LdpcEncoder(baseGraphNo=1, modulation='QPSK', txLayers=1, nRef=0, targetRate=0.4384765625)

DEPRECATED: This class is deprecated and will be removed in future releases. Please use the LdpcCodec class instead.

This is the Low-Density Parity Check (LDPC) encoder class. It is derived from the LdpcBase class and performs the following tasks:

  • Code block segmentation based on 3GPP TS 38.212, Section 5.2.2

  • LDPC encoding based on 3GPP TS 38.212, Section 5.3.2

  • Rate Matching with bit selection and interleaving based on 3GPP TS 38.212, Section 5.4.2

Parameters:

  • baseGraphNo (int) – The base graph used by this LDPC encoder. It can be either 1 or 2. In NR, base graph 1 is designed for code rates from 1/3 to 22/24 (approximately 0.33-0.92) and base graph 2 from 1/5 to 5/6 (approximately 0.2-0.83). The choice between base graph 1 or 2 is based on the transport block size and the targeted code rate (targetRate). The choice of base graph then determines the maximum code block size (8448 bits for base graph 1 and 3840 bits for base graph 2). The base graphs are defined as \(H_{BG}\) in 3GPP 3GPP TS 38.212, Tables 5.3.2-2 and 5.3.2-3.

  • modulation (str) –

    The modulation scheme used by the physical channel based on table 7.3.1.2-1 in 3GPP TS 38.211. Here is a list of supported Modulation Schemes:

    Modulation Scheme

    Modulation Order (qm)

    BPSK

    1

    QPSK

    2

    16QAM

    4

    64QAM

    6

    256QAM

    8

    1024QAM

    10

  • txLayers (int) – The number of transmission layers in the physical channel using this LDPC encoder.

  • nRef (int) – This is used for Low-Buffer Rate Matching (LBRM). Please refer to 3GPP TS 38.212, Section 5.4.2.1 for more details.

  • targetRate (float) – The desired code rate which is the ratio of the data bits to the total number of bits transmitted (including the LDPC redundancy bits).

Please refer to the LdpcBase class for a list of properties inherited from the base class.

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

Prints the properties of this LdpcEncoder object.

Parameters:

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

  • title (str) – If specified, it is used as the title for the printed information.

  • 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

doSegmentation(txBlock, fillerBit=0)

The first step in LDPC encoding process is breaking down the transport block into smaller more manageable code blocks. This function receives a transport block txBlock, performs segmentation based on 3GPP TS 38.212, Section 5.2.2, and outputs a 2D C x K NumPy array containing C code blocks of length K.

../../_images/TxpBlock.jpg

Transport Block Segmentation [1]

Parameters:

  • txBlock (NumPy array) – A NumPy array of bits containing the transport block information.

  • fillerBit (int) –

    This parameter is ignored.

    Note

    NeoRadium no longer uses the filler bits in its newer versions. This parameter will be removed in future releases.

Returns:

A 2D C x K NumPy array containing C code blocks of length K.

Return type:

NumPy array

encode(codeBlocks, puncture=True)

This function encodes a set of code blocks and returns a set of LDPC coded blocks based on the procedure explained in 3GPP TS 38.212, Section 5.3.2.

Parameters:

  • codeBlocks (NumPy array) – A C x K NumPy array containing C code blocks of length K being LDPC-encoded by this function.

  • puncture (bool) – By default, the first \(2Z_c\) bits of the code blocks are punctured (removed). If puncture=False, then the first \(2Z_c\) bits are kept in the returned encoded blocks.

Returns:

A C x N NumPy array containing the C encoded blocks.

Return type:

NumPy array

rateMatch(codedBlocks, g=None, concatCBs=True, rv=0)

This function receives a set of encoded blocks and returns the rate-matched output based on the configured code rate. It performs bit selection and interleaving based on 3GPP TS 38.212, Section 5.4.2

Parameters:

  • codedBlocks (NumPy array) – A C x N NumPy array containing C encoded code blocks of length N being rate-matched by this function.

  • g (int or None) – This is the total number of bits available for transmission of the transport block. It is the value \(G\) in the bit selection process explained in 3GPP TS 38.212, Section 5.4.2.1. If not provided (default), it is calculated as \(G=\lceil \frac {B-24} R \rceil\) where \(B\) is the transport block size and \(R\) is the code rate.

  • concatCBs (bool) – If True (Default), the rate-matched coded blocks are concatenated and a single array of bits is returned. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

  • rv (int) –

    The Redundancy Version used with Hybrid Automatic Repeat Request (HARQ). It must be one of 0, 1, 2, or 3. Please refer to 3GPP TS 38.212, Table 5.4.2.1-2 for more details. The default is 0 which means first transmission.

Returns:

If concatCBs is True, a 1-D NumPy array is returned containing the concatenation of all rate-matched coded blocks. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

Return type:

NumPy array or list of NumPy arrays

getRateMatchedCodeBlocks(txBlock, g=None, concatCBs=True, addCrc=True)

This function receives a transport block (txBlock) and returns the rate-matched output in a single call. It first appends a 24-bit CRC to the transport block and then uses the functions doSegmentation(), encode(), and rateMatch(), to perform segmentation, encoding, and rate matching.

Parameters:

  • txBlock (NumPy array) – A NumPy array of bits containing the transport block information.

  • g (int or None) – This is the total number of bits available for transmission of the transport block. It is the value \(G\) in the bit selection process explained in 3GPP TS 38.212, Section 5.4.2.1. If not provided (default), it is calculated as \(G=\lceil \frac {B-24} R \rceil\) where \(B\) is the transport block size and \(R\) is the code rate.

  • concatCBs (bool) – If True (Default), the rate-matched coded blocks are concatenated and a single array of bits is returned. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

  • addCrc (bool) – If True a 24-bit CRC is appended to the txBlock before the encoding process. Otherwise, it is assumed that the txBlock already includes the 24-bit CRC and therefore a CRC is not appended.

Returns:

If concatCBs is True, a 1-D NumPy array is returned containing the concatenation of all rate-matched coded blocks. Otherwise, a list of NumPy arrays is returned and each element in the list is the bit array corresponding to each coded block.

Return type:

NumPy array or list of NumPy arrays

getDecoder()

This function creates and returns an LdpcDecoder object based on the configuration of this LdpcEncoder. It makes it easier to create a decoder object based on the existing encoder object.

Returns:

An LDPC decoder object created based on this LdpcEncoder.

Return type:

LdpcDecoder

class neoradium.ldpc.LdpcDecoder(baseGraphNo=1, modulation='QPSK', txLayers=1, nRef=0)

DEPRECATED: This class is deprecated and will be removed in future releases. Please use the LdpcCodec class instead.

This is the Low-Density Parity Check (LDPC) decoder class. It is derived from the LdpcBase class and performs rate recovery, LDPC decoding, and code block merging. These are basically the opposite of the encoding tasks rate matching, LDPC encoding, and segmentation which are performed in reverse order.

The following example shows a typical use case for decoding the received LDPC-coded information into transport blocks:

An example of LDPC decoding
# Rate recovery
# Let's assume we have:
#   An LdpcDecoder object (ldpcDecoder)
#   The LLRs extracted from a received resource grid (llrs)
#   The transport block size (txBlockSize)
rxCodedBlocks = ldpcDecoder.recoverRate(llrs, txBlockSize)

# LDPC-Decoding
decodedBlocks = ldpcDecoder.decode(rxCodedBlocks)

# CRC-checking and de-segmentation
decodedTxBlockWithCRC, crcMatch = ldpcDecoder.checkCrcAndMerge(decodedBlocks)

# Checking the CRC of the transport block
txBlockCrcMatch = ldpcDecoder.checkCrc(decodedTxBlockWithCRC,'24A')

# Removing the transport block CRC
decodedTxBlock = decodedTxBlockWithCRC[:-24]
Parameters:

  • baseGraphNo (int) – The base graph used by this LDPC decoder. It can be either 1 or 2. In NR, base graph 1 is designed for code rates from 1/3 to 22/24 (approximately 0.33-0.92) and base graph 2 from 1/5 to 5/6 (approximately 0.2-0.83). The choice between base graph 1 or 2 is based on the transport block size and the targeted code rate (targetRate). The choice of base graph then determines the maximum code block size (8448 bits for base graph 1 and 3840 bits for base graph 2). The base graphs are defined as \(H_{BG}\) in 3GPP 3GPP TS 38.212, Tables 5.3.2-2 and 5.3.2-3.

  • modulation (str) –

    The modulation scheme used by the physical channel based on table 7.3.1.2-1 in 3GPP TS 38.211. Here is a list of supported Modulation Schemes:

    Modulation Scheme

    Modulation Order (qm)

    BPSK

    1

    QPSK

    2

    16QAM

    4

    64QAM

    6

    256QAM

    8

    1024QAM

    10

  • txLayers (int) – The number of transmission layers in the physical channel using this LDPC decoder.

  • nRef (int) – This is used for Low-Buffer Rate Matching (LBRM). Please refer to 3GPP TS 38.212, Section 5.4.2.1 for more details.

Note

For a pair of LdpcEncoder/LdpcDecoder objects to work properly, all of the above parameters used to configure them should match.

Please refer to the LdpcBase class for a list of properties inherited from the base class.

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

Prints the properties of this LdpcDecoder object.

Parameters:

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

  • title (str) – If specified, it is used as the title for the printed information.

  • 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

recoverRate(rxBlock, txBlockSize, harq=None)

This function receives an array of Log-Likelihood Ratios (LLRs) in rxBlock, and the transport block size txBlockSize, and returns a set of rate-recovered LLRs for each code block that is ready for LDPC decoding. This function does the exact opposite of the LdpcEncoder’s rateMatch() method. Note that while the rateMatch() works with bits, this method works on LLRs.

The LLRs are usually obtained by performing demodulation process. The method getLLRsFromGrid() of the PDSCH for example can be used to get LLRs from a received resource grid.

Parameters:

  • rxBlock (NumPy array) – A NumPy array of Log-Likelihood Ratios (LLRs) obtained as a result of demodulation process. Each element is a real LLR value corresponding to each received bit. The larger the LLR value, the more likely it is for that bit to be a 0.

  • txBlockSize (int) – The transport block size. This is the number of bits in a transport block (Not including the 24-bit CRC that is appended to the transport block). For example, in the case of PDSCH communication, this value can be obtained using the method getTxBlockSize() of the PDSCH class.

  • harq (HarqCW) – The HarqCW object handling retransmissions for each codeword. If specified, this method uses this object to obtain the ‘Redundancy Version’ and the circular buffer of the previous transmission of the same transport block.

Returns:

A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block ready to be LDPC-decoded.

Return type:

NumPy array

decode(rxCodeBlock, numIter=5, onlyInfoBits=True, outputBelief=False)

This function implements the Layered Belief Propagation algorithm for LDPC-decoding of LLRs into decoded code blocks. This implementation was inspired mostly by LDPC and Polar Codes in 5G Standard set of videos and was written from scratch to efficiently perform the decoding process.

Parameters:

  • rxCodeBlock (NumPy array) – A C x N NumPy array of C received coded blocks of length N containing the LLR values for each coded block.

  • numIter (int) – The number of iterations in the Layered Belief Propagation decoding algorithm. Larger values in some cases could result in more accurate decoding while making the whole decoding process slower. The default is 5.

  • onlyInfoBits (bool) – If True (default), only the information bits are returned. Otherwise, the parity bits are also included in the returned values together with the information bits.

  • outputBelief (bool) – If True, the calculated final belief values are returned for each bit which is the LLR for the decoded bits. Otherwise (default), hard decision is applied to the final belief values and the decoded bits are returned.

Returns:

If onlyInfoBits is set to True, a C x K NumPy array of C code blocks of length K is returned, where K is the codeBlockSize. Otherwise, the parity bit information is also included in the returned NumPy array which makes each code block longer than K. The contents of the return NumPy array can be bits or belief values based on the outputBelief parameter.

Return type:

NumPy array

checkCrcAndMerge(rxCodedBlocks)

This function performs CRC checking on the each code block, re-assembles the transport block by combining the code blocks, and returns the transport block together with the results of CRC checks for each code block.

Note that the returned value of this function includes the 24 bits of transport block CRC. The transport block CRC can be checked using the checkCrc() method.

Parameters:

rxCodedBlocks (NumPy array) – A C x K NumPy array of C code blocks of length K. Each code block contains a CRC as its last 24 bits. The rxCodedBlocks is usually the returned value of the decode() method explained above.

Returns:

  • txBlock (NumPy array of bits) – The NumPy array containing the transport block together with its 24-bit CRC at the end which can be verified using the checkCrc() method.

  • crcCheckResults (NumPy array of booleans) – The boolean NumPy array containing the CRC check results for each code block. To have a valid transport block, all of the values in this NumPy array must be True.

References: