README.md

---
license: mit
tags:
- pytorch
- safetensors
- threshold-logic
- neuromorphic
- modular-arithmetic
---

# threshold-mod5

Computes Hamming weight mod 5 for 8-bit inputs. Multi-layer network with thermometer encoding.

## Circuit

```
  x₀ x₁ x₂ x₃ x₄ x₅ x₆ x₇
   │  │  │  │  │  │  │  │
   └──┴──┴──┴──┼──┴──┴──┴──┘
               ▼
       ┌─────────────┐
       │ Thermometer │  Layer 1: 9 neurons
       │  Encoding   │
       └─────────────┘
               │
               ▼
       ┌─────────────┐
       │  MOD-5      │  Layer 2: 4 neurons
       │  Detection  │  Pattern (1,1,1,1,-4)
       └─────────────┘
               │
               ▼
       ┌─────────────┐
       │  Classify   │  Output: 5 classes
       └─────────────┘
               │
               ▼
        {0, 1, 2, 3, 4}
```

## Algebraic Insight

Pattern `(1, 1, 1, 1, -4)` causes cumulative sums to cycle mod 5:

```
HW=0: sum=0 → 0 mod 5
HW=1: sum=1 → 1 mod 5
HW=2: sum=2 → 2 mod 5
HW=3: sum=3 → 3 mod 5
HW=4: sum=4 → 4 mod 5
HW=5: sum=0 → 0 mod 5  (reset: 1+1+1+1-4=0)
HW=6: sum=1 → 1 mod 5
HW=7: sum=2 → 2 mod 5
HW=8: sum=3 → 3 mod 5
```

## Architecture

| Layer | Neurons | Function |
|-------|---------|----------|
| Input | 8 | Binary bits |
| Hidden 1 | 9 | Thermometer encoding |
| Hidden 2 | 4 | MOD-5 detection |
| Output | 5 | One-hot classification |

**Total: 18 neurons, 146 parameters**

## Output Distribution

| Class | HW values | Count/256 |
|-------|-----------|-----------|
| 0 | 0, 5 | 57 |
| 1 | 1, 6 | 36 |
| 2 | 2, 7 | 36 |
| 3 | 3, 8 | 57 |
| 4 | 4 | 70 |

## Usage

```python
from safetensors.torch import load_file
import torch

w = load_file('model.safetensors')

def forward(x):
    x = x.float()
    x = (x @ w['layer1.weight'].T + w['layer1.bias'] >= 0).float()
    x = (x @ w['layer2.weight'].T + w['layer2.bias'] >= 0).float()
    out = x @ w['output.weight'].T + w['output.bias']
    return out.argmax(dim=-1)
```

## Files

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

## License

MIT