kaira.models.fec.encoders.LDPCCodeEncoder

Inheritance diagram for LDPCCodeEncoder

class kaira.models.fec.encoders.LDPCCodeEncoder(check_matrix: Tensor = None, rptu_database: bool = False, *args: Any, **kwargs: Any)

Bases: LinearBlockCodeEncoder

Encoder for LDPC code [Gallager, 1962], [Gallager, 1963].

This encoder follows conventional approach of linear block codes and transforms binary input messages into codewords according to the calculated generator matrix. It serves as the encoding component of a linear block code system.

The encoder applies the formula: c = mG, where:

• c is the codeword

• m is the message

• G is the generator matrix

This implementation follows the standard approach to linear block coding described in the error control coding literature [Lin and Costello, 2004, Moon, 2005, Sklar, 2001].

generator_matrix

The generator matrix G of the code

Type:

torch.Tensor

check_matrix

The parity check matrix H

Type:

torch.Tensor

Methods

__init__	Initializes the linear block encoder for LDPC codes.
calculate_syndrome	Calculate the syndrome of a received word.
extract_message	Extract the message bits from a codeword.
forward	Applies the encoding mapping Enc: B^k → B^n of the code.
get_generator_matrix	Derive the generator matrix from a parity check matrix.
inverse_encode	Decode the input tensor using the generator matrix right inverse.

Attributes

code_dimension	Get the code dimension (k).
code_length	Get the codeword length (n).
code_rate	Get the rate of the code (k/n).
parity_bits	Get the number of parity bits (synonym for redundancy).
parity_check_matrix	Get the check matrix H of the code.
redundancy	Get the code redundancy (r = n - k).

__init__(check_matrix: Tensor = None, rptu_database: bool = False, *args: Any, **kwargs: Any)

Initializes the linear block encoder for LDPC codes.

Parameters:

• check_matrix (torch.Tensor, optional) – The parity check matrix for encoding. Should be a binary matrix of shape (code_length - code_dimension, code_length), where code_dimension is the message length and code_length is the codeword length. If None and rptu_database is True, the matrix will be loaded from the RPTU database.

• rptu_database (bool, optional) – If True, loads the check matrix from the RPTU code database using parameters provided in kwargs. Default is False.

• *args – Additional positional arguments passed to the base class.

• **kwargs – Additional keyword arguments. Expected keys when rptu_database is True: - code_length (int): Codeword length. - code_dimension (int): Message length. - rptu_standart (str, optional): Standard name for the LDPC code. If not provided, the first available standard is used. - device (str, optional): Device to place the tensors on (e.g., “cpu” or “cuda”).

Raises:

ValueError – If the requested (code_length, code_dimension) code or standard is not found in the RPTU database.

get_generator_matrix(check_matrix_: Tensor) → Tensor

Derive the generator matrix from a parity check matrix.

This method computes the generator matrix for an LDPC code by: 1. Transposing the parity check matrix 2. Appending an identity matrix to obtain [H | I] 3. Performing Gaussian elimination (row reduction) to obtain [A | B] 4. Extracting the generator matrix from the result

The process ensures that G·Hᵀ = 0, which is the defining property of a valid generator matrix for the code.

Parameters:

check_matrix – The parity check matrix of the LDPC code

Returns:

The generator matrix for the LDPC code

calculate_syndrome(x: Tensor) → Tensor

Calculate the syndrome of a received word.

The syndrome is computed as s = xH^T and is used to detect errors. A non-zero syndrome indicates the presence of errors [Lin and Costello, 2004, Moon, 2005]. This approach is a fundamental technique in error detection and correction for linear block codes [Sklar, 2001].

Parameters:

x – Received word tensor of shape (…, codeword_length) or (…, b*codeword_length) where b is a positive integer.

Returns:

Syndrome tensor of shape (…, redundancy) or (…, b*redundancy)

property code_dimension: int

Get the code dimension (k).

Returns:

The number of information bits encoded in each codeword

property code_length: int

Get the codeword length (n).

Returns:

The number of bits in each codeword after encoding

property code_rate: float

Get the rate of the code (k/n).

The code rate is a measure of efficiency, representing the proportion of the total bits that carry information (as opposed to redundancy).

Returns:

The ratio of information bits to total bits (between 0 and 1)

extract_message(codeword: Tensor) → Tensor

Extract the message bits from a codeword.

By default, this calls inverse_encode and returns just the decoded message. Subclasses can override this method to provide more efficient implementations.

Parameters:

codeword – Codeword tensor with shape (…, n) where n is the code length

Returns:

Extracted message tensor with shape (…, k) where k is the code dimension

Note

This implementation assumes the inverse_encode method can handle a single codeword correctly. Specific code types may override this with more efficient implementations.

forward(x: Tensor, *args: Any, **kwargs: Any) → Tensor

Applies the encoding mapping Enc: B^k → B^n of the code.

This method takes one or more sequences of messages and returns their corresponding codeword sequences. The encoding process follows standard linear block code principles [Lin and Costello, 2004, Richardson and Urbanke, 2008].

Parameters:

• x – The input tensor. Can be either a single sequence whose length is a multiple of k, or a multidimensional tensor where the last dimension is a multiple of k.

• *args – Additional positional arguments (unused).

• **kwargs – Additional keyword arguments (unused).

Returns:

The output tensor. Has the same shape as the input, with the last dimension expanded from b*k to b*n, where b is a positive integer.

Raises:

ValueError – If the last dimension of the input is not a multiple of k.

inverse_encode(x: Tensor, *args: Any, **kwargs: Any) → Tuple[Tensor, Tensor]

Decode the input tensor using the generator matrix right inverse.

This method takes one or more sequences of codewords and returns their corresponding decoded messages along with syndromes. The decoding approach follows standard techniques in error control coding literature [Lin and Costello, 2004, Sklar, 2001].

Parameters:

• x – The input tensor. Can be either a single sequence whose length is a multiple of n, or a multidimensional tensor where the last dimension is a multiple of n.

• *args – Additional positional arguments (unused).

• **kwargs – Additional keyword arguments (unused).

Returns:

• Decoded tensor of shape (…, b*k). Has the same shape as the input, with the last dimension reduced from b*n to b*k, where b is a positive integer.

• Syndrome tensor for error detection of shape (…, b*r), where r is the redundancy.

Return type:

Tuple containing

Raises:

ValueError – If the last dimension of the input is not a multiple of n.

property parity_bits: int

Get the number of parity bits (synonym for redundancy).

Returns:

The number of parity/check bits in each codeword

property parity_check_matrix: Tensor

Get the check matrix H of the code.

The check matrix H satisfies the property: GH^T = 0

Returns:

The check matrix H of the code

property redundancy: int

Get the code redundancy (r = n - k).

Returns:

The number of redundant bits added during encoding