README.md

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

# threshold-hamming74encoder

Hamming(7,4) encoder. Transforms 4 data bits into a 7-bit codeword with single-error correction capability.

## Circuit Overview

```
     d1  d2  d3  d4
      │   │   │   │
      ├───┼───┼───┤
      │   │   │   │
      │   │   │   └────────────────────────────► c7 = d4
      │   │   └───────────────────────► c6 = d3
      │   └──────────────────► c5 = d2
      └─────────────► c3 = d1
      │   │   │   │
      ▼   ▼   │   ▼
    ┌───────────────┐
    │ d1 XOR d2 XOR │──────► c1 = p1
    │      d4       │
    └───────────────┘
      │       │   │
      ▼       ▼   ▼
    ┌───────────────┐
    │ d1 XOR d3 XOR │──────► c2 = p2
    │      d4       │
    └───────────────┘
          │   │   │
          ▼   ▼   ▼
        ┌───────────────┐
        │ d2 XOR d3 XOR │──► c4 = p3
        │      d4       │
        └───────────────┘
```

## The Hamming(7,4) Code

Richard Hamming invented this code in 1950. It encodes 4 data bits into 7 bits such that any single-bit error can be detected and corrected.

**Codeword structure:**

| Position | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|----------|---|---|---|---|---|---|---|
| Bit | p1 | p2 | d1 | p3 | d2 | d3 | d4 |
| Type | parity | parity | data | parity | data | data | data |

**Parity equations:**
- p1 = d1 ⊕ d2 ⊕ d4 (covers positions 1,3,5,7)
- p2 = d1 ⊕ d3 ⊕ d4 (covers positions 2,3,6,7)
- p3 = d2 ⊕ d3 ⊕ d4 (covers positions 4,5,6,7)

## 3-Way XOR Implementation

Each parity bit requires a 3-input XOR. In threshold logic:

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

      a   b
      │   │
      └─┬─┘
        ▼
    ┌───────┐
    │ XOR   │  (2 layers)
    └───────┘
        │
        │   c
        └─┬─┘
          ▼
      ┌───────┐
      │ XOR   │  (2 more layers)
      └───────┘
          │
          ▼
     XOR(a,b,c)
```

Total depth: 4 layers per parity. All three parities compute in parallel.

## Code Properties

| Property | Value |
|----------|-------|
| Data bits (k) | 4 |
| Codeword bits (n) | 7 |
| Parity bits (n-k) | 3 |
| Minimum distance | 3 |
| Error correction | 1 bit |
| Error detection | 2 bits |

## Example Encoding

```
Data: 1011

p1 = 1 ⊕ 0 ⊕ 1 = 0
p2 = 1 ⊕ 1 ⊕ 1 = 1
p3 = 0 ⊕ 1 ⊕ 1 = 0

Codeword: 0110011
          ↑↑ ↑
          p1p2p3
```

## Architecture

| Component | Neurons | Parameters |
|-----------|---------|------------|
| p1 (3-way XOR) | 6 | 22 |
| p2 (3-way XOR) | 6 | 22 |
| p3 (3-way XOR) | 6 | 22 |
| d1-d4 pass-through | 4 | 20 |
| **Total** | **22** | **86** |

**Layers: 4** (two cascaded XOR stages)

## All 16 Codewords

| Data | Codeword | HW |
|------|----------|-----|
| 0000 | 0000000 | 0 |
| 1000 | 1110000 | 3 |
| 0100 | 1001100 | 3 |
| 1100 | 0111100 | 4 |
| 0010 | 0101010 | 3 |
| 1010 | 1011010 | 4 |
| 0110 | 1100110 | 4 |
| 1110 | 0010110 | 3 |
| 0001 | 1101001 | 4 |
| 1001 | 0011001 | 3 |
| 0101 | 0100101 | 3 |
| 1101 | 1010101 | 4 |
| 0011 | 1000011 | 3 |
| 1011 | 0110011 | 4 |
| 0111 | 0001111 | 4 |
| 1111 | 1111111 | 7 |

Note: Minimum Hamming distance between any two codewords is 3.

## Usage

```python
from safetensors.torch import load_file

w = load_file('model.safetensors')

def hamming74_encode(d1, d2, d3, d4):
    """Encode 4 data bits to 7-bit Hamming codeword"""
    # See model.py for full implementation
    pass

# Encode data word 1011
codeword = hamming74_encode(1, 0, 1, 1)
# Returns [0, 1, 1, 0, 0, 1, 1]
```

## Files

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

## License

MIT