kaira.models.fec.encoders.HammingCodeEncoder

Inheritance diagram for HammingCodeEncoder

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

Bases: SystematicLinearBlockCodeEncoder

Encoder for Hamming codes.

Hamming codes are linear error-correcting codes that can detect up to two-bit errors and correct single-bit errors. They are perfect codes, meaning they achieve the theoretical limit for the number of correctable errors given their length and dimension [Lin and Costello, 2004, Richardson and Urbanke, 2008].

For a given parameter μ ≥ 2, a Hamming code has the following parameters: - Length: n = 2^μ - 1 - Dimension: k = 2^μ - μ - 1 - Redundancy: m = μ - Minimum distance: d = 3

In its extended version, the Hamming code has the following parameters: - Length: n = 2^μ - Dimension: k = 2^μ - μ - 1 - Redundancy: m = μ + 1 - Minimum distance: d = 4

The implementation follows standard techniques in error control coding literature [Lin and Costello, 2004, Moon, 2005, Sklar, 2001].

Parameters:

• mu (int) – The parameter μ of the code. Must satisfy μ ≥ 2.

• extended (bool, optional) – Whether to use the extended version of the Hamming 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 = HammingCodeEncoder(mu=3)
>>> print(f"Length: {encoder.length}, Dimension: {encoder.dimension}, Redundancy: {encoder.redundancy}")
Length: 7, Dimension: 4, Redundancy: 3
>>> message = torch.tensor([1., 0., 1., 1.])
>>> codeword = encoder(message)
>>> print(codeword)
tensor([1., 0., 1., 1., 0., 1., 1.])

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

Methods

__init__	Initialize the Hamming code encoder.
calculate_syndrome	Calculate the syndrome of a received word.
extract_message	Extract the message bits from a codeword.
forward	Encode the input tensor using systematic encoding.
inverse_encode	Decode a codeword back to its original message, correcting single-bit errors.
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).
extended	Get whether this is an extended Hamming 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'.
mu	Get the parameter μ of the code.
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__(mu: int, extended: bool = False, information_set: List[int] | Tensor | str = 'left', dtype: dtype = torch.float32, **kwargs: Any)

Initialize the Hamming code encoder.

Parameters:

• mu – The parameter μ of the code. Must satisfy μ ≥ 2.

• extended – Whether to use the extended version of the Hamming code. Default is False.

• information_set – 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 – Data type for internal tensors. Default is torch.float32.

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

Raises:

ValueError – If mu < 2.

property mu: int

Get the parameter μ of the code.

property extended: bool

Get whether this is an extended Hamming code.

minimum_distance() → int

Calculate the minimum Hamming distance of the code.

Returns:

• 3 for standard Hamming code

• 4 for extended Hamming code

Return type:

The minimum Hamming distance

inverse_encode(y)

Decode a codeword back to its original message, correcting single-bit errors.

Parameters:

y – A tensor of codewords to decode. The last dimension should match the code length. Supports batch processing with arbitrary batch dimensions.

Returns:

(decoded_message, syndrome)

• decoded_message: The decoded information bits with corrected errors

• syndrome: The syndrome vectors for each codeword

Return type:

tuple

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’.

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