README.md

---
license: mit
tags:
- pytorch
- safetensors
- threshold-logic
- neuromorphic
- error-correction
- hamming-code
---

# 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:

| s3 | s2 | s1 | Decimal | Meaning |
|----|----|----|---------|---------|
| 0 | 0 | 0 | 0 | No error |
| 0 | 0 | 1 | 1 | Error in c1 (parity) |
| 0 | 1 | 0 | 2 | Error in c2 (parity) |
| 0 | 1 | 1 | 3 | Error in c3 (d1) |
| 1 | 0 | 0 | 4 | Error in c4 (parity) |
| 1 | 0 | 1 | 5 | Error in c5 (d2) |
| 1 | 1 | 0 | 6 | Error in c6 (d3) |
| 1 | 1 | 1 | 7 | Error in c7 (d4) |

**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

| Stage | Component | Neurons | Layers |
|-------|-----------|---------|--------|
| Syndrome | 3 × 4-way XOR | 18 | 4 |
| Error Locator | 4 detectors | 4 | 1 |
| Corrector | 4 × 2-way XOR | 12 | 2 |
| **Total** | | **34** | **6** |

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

```python
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