phanerozoic / threshold-hamming74decoder

threshold-hamming74decoder

Hamming(7,4) decoder with single-error correction. Takes a 7-bit codeword (possibly corrupted) and outputs the corrected 4 data bits.

Circuit Overview

c1 c2 c3 c4 c5 c6 c7
 │  │  │  │  │  │  │
 └──┴──┴──┴──┴──┴──┴─────────────────────┐
 │  │  │  │  │  │  │                     │
 ▼  ▼  ▼  ▼  ▼  ▼  ▼                     │
┌─────────────────────┐                  │
│  Syndrome Computer  │                  │
│  s1 = c1⊕c3⊕c5⊕c7  │                  │
│  s2 = c2⊕c3⊕c6⊕c7  │                  │
│  s3 = c4⊕c5⊕c6⊕c7  │                  │
└─────────────────────┘                  │
         │ s1,s2,s3                      │
         ▼                               │
┌─────────────────────┐                  │
│  Error Locator      │                  │
│  flip3 = s1∧s2∧¬s3  │   ┌──────────────┘
│  flip5 = s1∧¬s2∧s3  │   │ c3,c5,c6,c7
│  flip6 = ¬s1∧s2∧s3  │   │
│  flip7 = s1∧s2∧s3   │   │
└─────────────────────┘   │
         │                │
         ▼                ▼
┌─────────────────────────────┐
│  Corrector                  │
│  d1 = c3 ⊕ flip3            │
│  d2 = c5 ⊕ flip5            │
│  d3 = c6 ⊕ flip6            │
│  d4 = c7 ⊕ flip7            │
└─────────────────────────────┘
         │
         ▼
    d1 d2 d3 d4

Decoding Algorithm

Step 1: Compute Syndrome

The syndrome is a 3-bit value that indicates the error position:

Step 2: Locate and Correct

Only data positions (3, 5, 6, 7) need correction in the output. Parity bit errors (positions 1, 2, 4) don't affect data extraction.

Step 3: Extract Data

Data bits are at positions 3, 5, 6, 7 of the codeword, XORed with their flip signals.

4-Way XOR Implementation

Each syndrome bit requires a 4-input XOR:

XOR(a,b,c,d) = XOR(XOR(a,b), XOR(c,d))

    a   b       c   d
    │   │       │   │
    └─┬─┘       └─┬─┘
      ▼           ▼
   ┌─────┐     ┌─────┐
   │ XOR │     │ XOR │   Layer 1-2
   └─────┘     └─────┘
      │           │
      └─────┬─────┘
            ▼
         ┌─────┐
         │ XOR │         Layer 3-4
         └─────┘
            │
            ▼
      XOR(a,b,c,d)

Architecture

Note: Syndrome computation and final XOR stages run in parallel where possible.

Error Correction Examples

Original:     1011 → encode → 0110011
Corrupted:    0110011 → flip bit 5 → 0110111
Syndrome:     s1=1, s2=0, s3=1 → position 5
Corrected:    d1=1, d2=0, d3=1, d4=1 ✓

Original:     0000 → encode → 0000000
Corrupted:    0000000 → flip bit 7 → 0000001
Syndrome:     s1=1, s2=1, s3=1 → position 7
Corrected:    d1=0, d2=0, d3=0, d4=0 ✓

Limitations

• Corrects single-bit errors only
• Detects double-bit errors (non-zero syndrome, wrong correction)
• Cannot distinguish 2-bit errors from 1-bit errors

For stronger protection, use Hamming(7,4) + overall parity (SECDED).

Usage

from safetensors.torch import load_file

w = load_file('model.safetensors')

def hamming74_decode(codeword):
    """Decode 7-bit Hamming codeword to 4 data bits with error correction"""
    # See model.py for full implementation
    pass

# Received corrupted codeword (error at position 3)
received = [0, 1, 0, 0, 0, 1, 1]  # Should be [0,1,1,0,0,1,1]
data = hamming74_decode(received)
# Returns [1, 0, 1, 1] (corrected)

Files

threshold-hamming74decoder/
├── model.safetensors
├── model.py
├── config.json
└── README.md

License

MIT