kaira.models.fec.encoders.SingleParityCheckCodeEncoder

Inheritance diagram for SingleParityCheckCodeEncoder

class kaira.models.fec.encoders.SingleParityCheckCodeEncoder(dimension: int, *args: Any, **kwargs: Any)

Bases: LinearBlockCodeEncoder

Encoder for single parity-check codes.

A single parity-check code extends a message of k bits with a single parity bit, creating a codeword of length n = k + 1. The parity bit is chosen so that the total number of 1s in the codeword is even.

The resulting code has the following properties: - Length: n = k + 1 - Dimension: k - Minimum distance: d = 2

This code can detect a single error but cannot correct any errors. Its dual is the repetition code.

dimension

The dimension k of the code (number of information bits)

Type:

int

minimum_distance

The minimum Hamming distance of the code (always 2)

Type:

int

Parameters:

• dimension (int) – The dimension k of the code (number of information bits)

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

• **kwargs – Variable keyword arguments passed to the base class.

Methods

__init__	Initialize the single parity-check encoder.
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.
from_length	Create a single parity-check encoder from the code length.
from_parameters	Create a single parity-check encoder from parameters.
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__(dimension: int, *args: Any, **kwargs: Any)

Initialize the single parity-check encoder.

Parameters:

• dimension – The dimension k of the code (number of information bits)

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

• **kwargs – Variable keyword arguments passed to the base class.

Raises:

ValueError – If the dimension is not a positive integer

classmethod from_parameters(dimension: int, *args: Any, **kwargs: Any) → SingleParityCheckCodeEncoder

Create a single parity-check encoder from parameters.

This is an alternative constructor that creates the encoder directly from the single parity-check parameters.

Parameters:

• dimension – The dimension k of the code (number of information bits)

• *args – Variable positional arguments passed to the constructor.

• **kwargs – Variable keyword arguments passed to the constructor.

Returns:

A SingleParityCheckCodeEncoder instance

classmethod from_length(length: int, *args: Any, **kwargs: Any) → SingleParityCheckCodeEncoder

Create a single parity-check encoder from the code length.

This is an alternative constructor that creates the encoder given the desired code length n. The dimension k will be n-1.

Parameters:

• length – The length n of the code

• *args – Variable positional arguments passed to the constructor.

• **kwargs – Variable keyword arguments passed to the constructor.

Returns:

A SingleParityCheckCodeEncoder instance

Raises:

ValueError – If the length is less than 2

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