Refactor FEC encoder and decoder modules for improved structure and documentation

- Updated the SyndromeLookupDecoder to inherit from BaseBlockDecoder and enhanced its documentation with detailed explanations and examples.
- Refined the WagnerSoftDecisionDecoder to inherit from BaseBlockDecoder, ensuring it adheres to a consistent interface and improved its documentation.
- Introduced a new BaseBlockCodeEncoder class to serve as a foundation for various block code encoders, promoting code reuse and clarity.
- Enhanced the BCHCodeEncoder, CyclicCodeEncoder, GolayCodeEncoder, HammingCodeEncoder, LinearBlockCodeEncoder, and SystematicLinearBlockCodeEncoder with clearer documentation and removed redundant attributes.
- Improved utility functions in the utils module for better clarity and added examples for better usability.
- Updated the __init__.py file to reflect the new structure and imports.

Author: selimfirat

docs/api_reference.rst

@@ -281,8 +281,8 @@ Forward Error Correction (FEC) decoders for Kaira.
    :template: class.rst
    :nosignatures:
 
+   BaseBlockDecoder
    BerlekampMasseyDecoder
-   BlockDecoder
    BruteForceMLDecoder
    ReedMullerDecoder
    SyndromeLookupDecoder
@@ -302,7 +302,7 @@ Forward Error Correction encoders for Kaira.
    :nosignatures:
 
    BCHCodeEncoder
-   BlockCodeEncoder
+   BaseBlockCodeEncoder
    CyclicCodeEncoder
    GolayCodeEncoder
    HammingCodeEncoder
@@ -472,6 +472,7 @@ Data utilities for Kaira, including data generation and correlation models.
 
    BinaryTensorDataset
    UniformTensorDataset
+   WynerZivCorrelationDataset
 
 
 .. currentmodule:: kaira.data

docs/references.bib

@@ -729,3 +729,88 @@ @article{golay1949notes
   publisher={IEEE},
   doi={10.1109/JRPROC.1949.233620}
 }
+
+@book{macwilliams1977theory,
+  title={The Theory of Error-Correcting Codes},
+  author={MacWilliams, F. Jessie and Sloane, Neil J. A.},
+  year={1977},
+  publisher={North-Holland Publishing Company},
+  isbn={978-0-444-85193-2}
+}
+
+@article{reed1954class,
+  title={A class of multiple-error-correcting codes and the decoding scheme},
+  author={Reed, Irving S.},
+  journal={Transactions of the IRE Professional Group on Information Theory},
+  volume={4},
+  number={4},
+  pages={38--49},
+  year={1954},
+  publisher={IEEE},
+  doi={10.1109/TIT.1954.1057465}
+}
+
+@article{muller1954application,
+  title={Application of Boolean algebra to switching circuit design and to error detection},
+  author={Muller, David E.},
+  journal={Transactions of the IRE Professional Group on Electronic Computers},
+  volume={EC-3},
+  number={3},
+  pages={6--12},
+  year={1954},
+  publisher={IEEE},
+  doi={10.1109/IREPGELC.1954.6499441}
+}
+
+@book{berlekamp1968algebraic,
+  title={Algebraic Coding Theory},
+  author={Berlekamp, Elwyn R.},
+  year={1968},
+  publisher={McGraw-Hill},
+  address={New York}
+}
+
+@article{massey1969shift,
+  title={Shift-register synthesis and BCH decoding},
+  author={Massey, James L.},
+  journal={IEEE Transactions on Information Theory},
+  volume={15},
+  number={1},
+  pages={122--127},
+  year={1969},
+  publisher={IEEE},
+  doi={10.1109/TIT.1969.1054260}
+}
+
+@article{wagner1986simple,
+  title={A simple algorithm for the exact decoding of the single-parity-check code},
+  author={Wagner, B. J.},
+  journal={IEEE Transactions on Information Theory},
+  volume={32},
+  number={3},
+  pages={430--433},
+  year={1986},
+  publisher={IEEE},
+  doi={10.1109/TIT.1986.1057195}
+}
+
+@article{hagenauer1989iterative,
+  title={Iterative decoding of binary block and convolutional codes},
+  author={Hagenauer, Joachim and Hoeher, Peter},
+  journal={IEEE Transactions on Information Theory},
+  volume={42},
+  number={2},
+  pages={429--445},
+  year={1996},
+  publisher={IEEE},
+  doi={10.1109/18.485714}
+}
+
+@book{proakis2008digital,
+  title={Digital Communications},
+  author={Proakis, John G. and Salehi, Masoud},
+  year={2008},
+  edition={5th},
+  publisher={McGraw-Hill Higher Education},
+  isbn={978-0-07-295716-7}
+}

kaira/models/fec/__init__.py

@@ -1,8 +1,22 @@
 """Forward Error Correction (FEC) package for Kaira.
 
-This package provides implementations of various forward error correction techniques, particularly
-focusing on binary error correction codes like block codes, cyclic codes, and more advanced
-algebraic codes like BCH codes.
+This package provides implementations of various forward error correction techniques, enabling
+robust data transmission over noisy channels. FEC codes add redundant information to transmitted
+data, allowing receivers to detect and correct errors without retransmission.
+
+Key components:
+- algebra: Mathematical foundations for finite fields and binary polynomials
+- encoders: Various channel encoding schemes (block codes, algebraic codes, etc.)
+- decoders: Implementations of corresponding decoding algorithms
+- utils: Utility functions for binary operations and code manipulation
+
+Common FEC codes implemented:
+- Block codes: Linear block codes, systematic codes, single parity check
+- Cyclic codes: BCH, Reed-Solomon, Golay codes
+- Other codes: Hamming, repetition codes, Reed-Muller
+
+These implementations can be used in communication system simulations, coded modulation
+schemes, and for educational purposes in information theory and coding :cite:`lin2004error,moon2005error`.
 """
 
 from . import algebra, decoders, encoders, utils

kaira/models/fec/algebra.py

@@ -1,8 +1,19 @@
 """Finite field algebra utilities for forward error correction.
 
 This module provides mathematical utilities for working with binary polynomials and finite fields,
-which are essential for many error correction codes such as BCH codes, Reed-Solomon codes, and
-other algebraic codes.
+which are essential for algebraic error correction codes such as BCH, Reed-Solomon, and others.
+
+The module implements:
+- Binary polynomials over GF(2) with efficient arithmetic operations
+- Finite fields GF(2^m) with complete field arithmetic
+- Field element operations including inverses, minimal polynomials, and traces
+
+These implementations form the mathematical foundation for more complex error correction codes
+and are optimized for both correctness and computational efficiency. The module supports both
+symbolic manipulations and numeric computations compatible with PyTorch tensors.
+
+    :cite:`lin2004error`
+    :cite:`blahut2003algebraic`
 """
 
 from typing import Any, Dict, List

kaira/models/fec/decoders/__init__.py

@@ -28,15 +28,15 @@
 >>> decoded = decoder(received)
 """
 
-from .base import BlockDecoder
+from .base import BaseBlockDecoder
 from .berlekamp_massey import BerlekampMasseyDecoder
 from .brute_force_ml import BruteForceMLDecoder
 from .reed_muller_decoder import ReedMullerDecoder
 from .syndrome_lookup import SyndromeLookupDecoder
 from .wagner_soft_decision_decoder import WagnerSoftDecisionDecoder
 
 __all__ = [
-    "BlockDecoder",
+    "BaseBlockDecoder",
     "SyndromeLookupDecoder",
     "BerlekampMasseyDecoder",
     "ReedMullerDecoder",

kaira/models/fec/decoders/base.py

@@ -4,8 +4,13 @@
 Decoders are responsible for recovering the original message from received codewords that
 may contain errors introduced during transmission over noisy channels.
 
-The implementation provides base classes for various types of decoders, following
-standard conventions in coding theory :cite:`lin2004error,moon2005error,richardson2008modern`.
+The module provides a type-generic architecture that ensures correct pairing between encoders
+and their corresponding decoders, while maintaining flexibility for different decoding
+algorithms and implementation strategies.
+
+:cite:`lin2004error`
+:cite:`moon2005error`
+:cite:`richardson2008modern`
 """
 
 from abc import ABC, abstractmethod
@@ -15,36 +20,56 @@
 
 from kaira.models.base import BaseModel
 
-from ..encoders.block_code import BlockCodeEncoder
+from ..encoders.base import BaseBlockCodeEncoder
 
-T = TypeVar("T", bound=BlockCodeEncoder)
+T = TypeVar("T", bound=BaseBlockCodeEncoder)
 
 
-class BlockDecoder(BaseModel, Generic[T], ABC):
+class BaseBlockDecoder(BaseModel, Generic[T], ABC):
     """Base class for block code decoders.
 
     This abstract class provides a common interface and functionality for all types of
     block code decoders. It serves as a foundation for specific implementations like
-    syndrome decoders, Viterbi decoders, BCJR decoders, etc.
+    syndrome decoders, maximum likelihood decoders, algebraic decoders, and soft-decision
+    decoders.
+
+    The class uses a generic type parameter T to ensure type safety when pairing
+    encoders with their corresponding decoders. This allows the compiler to catch
+    type mismatches at development time rather than during runtime.
 
     Attributes:
-        encoder (T): The encoder instance associated with this decoder
+        encoder (T): The encoder instance associated with this decoder, providing
+                     access to code parameters and encoding/syndrome calculation methods
 
     Args:
         encoder (T): The encoder instance for the code being decoded
         *args: Variable positional arguments passed to the base class
         **kwargs: Variable keyword arguments passed to the base class
+
+    Note:
+        All concrete implementations must override the forward method to implement
+        specific decoding algorithms. Decoders may operate on hard-decision (binary)
+        or soft-decision (real-valued reliability information) inputs depending on
+        their implementation.
     """
 
     def __init__(self, encoder: T, *args: Any, **kwargs: Any):
-        """Initialize the block code decoder."""
+        """Initialize the block code decoder with an encoder instance.
+
+        The encoder provides essential information about the code parameters and may be used by the
+        decoder to perform syndrome calculations or other encoding-related operations during the
+        decoding process.
+        """
         super().__init__(*args, **kwargs)
         self.encoder = encoder
 
     @property
     def code_length(self) -> int:
         """Get the code length (n).
 
+        The code length is the total number of bits in each codeword,
+        including both information bits and redundancy bits.
+
         Returns:
             The length of the code (number of bits in a codeword)
         """
@@ -54,6 +79,9 @@ def code_length(self) -> int:
     def code_dimension(self) -> int:
         """Get the code dimension (k).
 
+        The code dimension is the number of information bits in each codeword,
+        representing the actual data being transmitted.
+
         Returns:
             The dimension of the code (number of information bits)
         """
@@ -63,6 +91,9 @@ def code_dimension(self) -> int:
     def redundancy(self) -> int:
         """Get the code redundancy (r = n - k).
 
+        The redundancy represents the number of parity or check bits added
+        to the information bits to enable error detection and correction.
+
         Returns:
             The redundancy of the code (number of parity bits)
         """
@@ -72,6 +103,10 @@ def redundancy(self) -> int:
     def code_rate(self) -> float:
         """Get the code rate (k/n).
 
+        The code rate is the ratio of information bits to the total bits,
+        indicating the coding efficiency. Higher rates mean more efficient
+        use of the channel but typically lower error correction capability.
+
         Returns:
             The rate of the code (ratio of information bits to total bits)
         """
@@ -81,18 +116,28 @@ def code_rate(self) -> float:
     def forward(self, received: torch.Tensor, *args: Any, **kwargs: Any) -> Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]:
         """Decode received codewords to recover the original messages.
 
+        This method implements the decoding algorithm to estimate the original
+        message from a potentially corrupted received codeword. Different decoder
+        implementations will use different algorithms based on the code structure
+        and desired performance characteristics.
+
         Args:
-            received: Received codeword tensor. The last dimension should be
-                    a multiple of the code length (n).
-            *args: Additional positional arguments.
-            **kwargs: Additional keyword arguments.
+            received: Received codeword tensor with shape (..., n) or (..., m*n)
+                    where n is the code length and m is some multiple.
+            *args: Additional positional arguments for specific decoder implementations.
+            **kwargs: Additional keyword arguments for specific decoder implementations.
 
         Returns:
             Either:
-            - Decoded tensor containing estimated messages
-            - A tuple of (decoded tensor, additional decoding information)
+            - Decoded tensor containing estimated messages with shape (..., k) or (..., m*k)
+            - A tuple of (decoded tensor, additional decoding information such as syndromes,
+              reliability metrics, or error patterns)
 
         Raises:
             ValueError: If the last dimension of received is not a multiple of n.
+
+        Note:
+            The decoding may not perfectly recover the original message if the number
+            of errors exceeds the error-correcting capability of the code.
         """
         raise NotImplementedError("Subclasses must implement forward method")