kaira.models.fec.encoders.GolayCodeEncoder

Inheritance diagram for GolayCodeEncoder

class kaira.models.fec.encoders.GolayCodeEncoder(extended: bool = False, information_set: List[int] | Tensor | str = 'left', dtype: dtype = torch.float32, **kwargs: Any)

Bases: SystematicLinearBlockCodeEncoder

Encoder for binary Golay codes.

The binary Golay code is a perfect [23,12,7] linear error-correcting code that can correct up to 3 errors in a 23-bit word. The extended Golay code is a [24,12,8] code that can also correct up to 3 errors in a 24-bit word and detect up to 4 errors.

These codes are named after Marcel J. E. Golay who discovered them in 1949 [Golay, 1949]. The binary Golay code is one of the few known perfect codes [Lin and Costello, 2004, Moon, 2005].

The parity submatrix for the binary Golay code is:

\[\begin{split}P = \begin{bmatrix} 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 0 \\ 0 & 0 & 0 & 0 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\ 0 & 1 & 1 & 1 & 0 & 0 & 0 & 1 & 1 & 1 & 1 \\ 1 & 0 & 1 & 1 & 0 & 1 & 1 & 0 & 0 & 1 & 1 \\ 1 & 1 & 0 & 1 & 1 & 0 & 1 & 0 & 1 & 0 & 1 \\ 1 & 1 & 1 & 0 & 1 & 1 & 0 & 1 & 0 & 0 & 1 \\ 0 & 0 & 1 & 1 & 1 & 1 & 0 & 0 & 1 & 0 & 1 \\ 0 & 1 & 0 & 1 & 0 & 1 & 1 & 1 & 0 & 0 & 1 \\ 0 & 1 & 1 & 0 & 1 & 0 & 1 & 0 & 0 & 1 & 1 \\ 1 & 0 & 0 & 1 & 1 & 0 & 0 & 1 & 0 & 1 & 1 \\ 1 & 0 & 1 & 0 & 0 & 0 & 1 & 1 & 1 & 0 & 1 \\ 1 & 1 & 0 & 0 & 0 & 1 & 0 & 0 & 1 & 1 & 1 \end{bmatrix}\end{split}\]

The extended Golay code adds an additional parity check column to ensure the overall parity of each codeword is even.

Parameters:

• extended (bool, optional) – Whether to use the extended version of the Golay code. Default is False.

• information_set (Union[List[int], torch.Tensor, str], optional) – Information set specification. Default is “left”.

• dtype (torch.dtype, optional) – Data type for internal tensors. Default is torch.float32.

• **kwargs – Additional keyword arguments passed to the parent class.

Examples

>>> encoder = GolayCodeEncoder()
>>> print(f"Length: {encoder.length}, Dimension: {encoder.dimension}, Redundancy: {encoder.redundancy}")
Length: 23, Dimension: 12, Redundancy: 11
>>> message = torch.tensor([1., 0., 1., 1., 0., 1., 0., 1., 1., 0., 0., 1.])
>>> codeword = encoder(message)
>>> print(codeword)
tensor([1., 0., 1., 1., 0., 1., 0., 1., 1., 0., 0., 1., 0., 1., 1., 0., 1., 0., 1., 0., 0., 0., 1.])

>>> # Using the extended version
>>> ext_encoder = GolayCodeEncoder(extended=True)
>>> print(f"Length: {ext_encoder.length}, Dimension: {ext_encoder.dimension}, Redundancy: {ext_encoder.redundancy}")
Length: 24, Dimension: 12, Redundancy: 12
>>> message = torch.tensor([1., 0., 1., 1., 0., 1., 0., 1., 1., 0., 0., 1.])
>>> codeword = ext_encoder(message)
>>> print(codeword)
tensor([1., 0., 1., 1., 0., 1., 0., 1., 1., 0., 0., 1., 0., 1., 1., 0., 1., 0., 1., 0., 0., 0., 1., 0.])

Methods

__init__	Initialize the Golay code encoder.
calculate_syndrome	Calculate the syndrome of a received word.
create_extended_golay_code	Create an extended Golay code encoder.
create_standard_golay_code	Create a standard Golay code encoder.
extract_message	Extract the message bits from a codeword.
forward	Encode the input tensor using systematic encoding.
inverse_encode	Decode the input tensor using the generator matrix right inverse.
minimum_distance	Calculate the minimum Hamming distance of the code.
project_word	Project a codeword onto the information set.

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).
error_correction_capability	Number of errors the code can correct (3).
extended	Whether this is an extended Golay code.
information_set	Either indices of information positions, which must be a k-sublist of [0...n), or one of the strings 'left' or 'right'.
parity_bits	Get the number of parity bits (synonym for redundancy).
parity_check_matrix	Get the check matrix H of the code.
parity_set	Parity set M of the code.
parity_submatrix	Parity submatrix P of the code.
redundancy	Get the code redundancy (r = n - k).

__init__(extended: bool = False, information_set: List[int] | Tensor | str = 'left', dtype: dtype = torch.float32, **kwargs: Any)

Initialize the Golay code encoder.

Parameters:

• extended (bool, optional) – Whether to use the extended version of the Golay code. Default is False.

• information_set (Union[List[int], torch.Tensor, str], optional) – Either indices of information positions, which must be a k-sublist of [0…n), or one of the strings ‘left’ or ‘right’. Default is ‘left’.

• dtype (torch.dtype, optional) – Data type for internal tensors. Default is torch.float32.

• **kwargs – Additional keyword arguments passed to the parent class.

property extended: bool

Whether this is an extended Golay code.

property error_correction_capability: int

Number of errors the code can correct (3).

minimum_distance() → int

Calculate the minimum Hamming distance of the code.

Returns:

The minimum Hamming distance:

• 7 for standard Golay code

• 8 for extended Golay code

Return type:

int

classmethod create_extended_golay_code(**kwargs: Any) → GolayCodeEncoder

Create an extended Golay code encoder.

This is a convenience method for creating the extended version of the code.

Parameters:

**kwargs – Additional arguments passed to the constructor.

Returns:

Extended Golay code encoder.

Return type:

GolayCodeEncoder

classmethod create_standard_golay_code(**kwargs: Any) → GolayCodeEncoder

Create a standard Golay code encoder.

This is a convenience method for creating the standard version of the code.

Parameters:

**kwargs – Additional arguments passed to the constructor.

Returns:

Standard Golay code encoder.

Return type:

GolayCodeEncoder

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

Encode the input tensor using systematic encoding.

For systematic codes, encoding can be done efficiently by placing information bits directly in the information positions and calculating parity bits only. This implementation is optimized compared to the general matrix multiplication used in the parent class.

Parameters:

• x – The input tensor of shape (…, message_length) or (…, b*message_length) where b is a positive integer.

• *args – Additional positional arguments (unused).

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

Returns:

Encoded tensor of shape (…, codeword_length) or (…, b*codeword_length)

Raises:

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

property information_set: Tensor

Either indices of information positions, which must be a k-sublist of [0…n), or one of the strings ‘left’ or ‘right’.

Default is ‘left’.

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 parity_set: Tensor

Parity set M of the code.

property parity_submatrix: Tensor

Parity submatrix P of the code.

project_word(x: Tensor) → Tensor

Project a codeword onto the information set.

This extracts the information bits directly from a codeword without decoding, which is a key advantage of systematic codes.

Parameters:

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

Returns:

Projected tensor of shape (…, message_length) or (…, b*message_length)

Raises:

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

property redundancy: int

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

Returns:

The number of redundant bits added during encoding