README.md

---
license: mit
tags:
- pytorch
- safetensors
- threshold-logic
- neuromorphic
- encoder
---

# threshold-priorityencoder

8-to-3 priority encoder. Outputs the binary index of the highest-priority active input.

## Circuit

```
  x₀ x₁ x₂ x₃ x₄ x₅ x₆ x₇
   │  │  │  │  │  │  │  │
   └──┴──┴──┴──┼──┴──┴──┴──┘
               │
    ┌──────────┼──────────┐
    │          │          │
    ▼          ▼          ▼
┌──────┐   ┌──────┐   ┌──────┐
│win₀  │...│win₃  │...│win₇  │    Layer 1: Winner detectors
│+1,0..│   │inhibit│   │just  │    (8 neurons)
│b=-1  │   │higher │   │x₇    │
└──────┘   └──────┘   └──────┘
    │          │          │
    └────┬─────┴────┬─────┘
         │          │
    ┌────┴────┐┌────┴────┐
    │  y₀ OR  ││  y₂ OR  │        Layer 2: Output encoding
    │ 1,3,5,7 ││ 4,5,6,7 │        (4 neurons)
    └─────────┘└─────────┘
         │          │
         ▼          ▼
        y₀   y₁   y₂   valid
```

## Mechanism

**Winner Detection**: Each position has a neuron that fires only when:
1. That input is active (weight +1)
2. No higher-priority input is active (weight -1 on each higher input)

```
winner₅: fires when x₅=1 AND x₆=0 AND x₇=0
weights: [0, 0, 0, 0, 0, +1, -1, -1]
bias: -1
```

**Output Encoding**: The 3-bit output is assembled by OR-ing the appropriate winners:
- y₀ = OR(win₁, win₃, win₅, win₇) — odd indices
- y₁ = OR(win₂, win₃, win₆, win₇) — indices with bit 1 set
- y₂ = OR(win₄, win₅, win₆, win₇) — indices with bit 2 set

## Truth Table (samples)

| Active inputs | Winner | Output (y₂y₁y₀) | Index |
|---------------|--------|-----------------|-------|
| x₀ only | win₀ | 000 | 0 |
| x₃ only | win₃ | 011 | 3 |
| x₇ only | win₇ | 111 | 7 |
| x₀, x₃ | win₃ | 011 | 3 |
| x₂, x₅, x₆ | win₆ | 110 | 6 |
| all | win₇ | 111 | 7 |
| none | none | 000 | 0* |

*valid=0 when no inputs active

## Priority Convention

Highest index wins. x₇ has absolute priority over all others.

| Input | Priority |
|-------|----------|
| x₇ | Highest |
| x₆ | ... |
| ... | ... |
| x₀ | Lowest |

## Architecture

| Layer | Neurons | Function |
|-------|---------|----------|
| 1 | 8 | Winner detectors |
| 2 | 4 | Output OR gates (y₀, y₁, y₂, valid) |

**Total: 12 neurons, 96 parameters, 2 layers**

## The Inhibition Principle

The key insight: each winner neuron is *inhibited* by all higher-priority inputs.

```
winner₃ weights: [0, 0, 0, +1, -1, -1, -1, -1]
                          x₃  x₄  x₅  x₆  x₇
```

If any of x₄-x₇ is active, the negative weight cancels x₃'s contribution.

## Usage

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

w = load_file('model.safetensors')

def priority_encode(bits):
    """Returns (y2, y1, y0, valid)"""
    # See model.py for full implementation
    pass

# Multiple active: highest wins
bits = [1, 0, 1, 0, 0, 1, 0, 0]  # x0, x2, x5 active
y2, y1, y0, valid = priority_encode(bits)
# Result: (1, 0, 1, 1) = index 5
```

## Files

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

## License

MIT