README.md

---
license: mit
tags:
- pytorch
- safetensors
- threshold-logic
- neuromorphic
- arithmetic
- multiplier
- compressor
---

# threshold-3to2-compressor

3:2 compressor (carry-save adder). Reduces 3 input bits to 2 output bits (sum and carry) while preserving arithmetic value. Essential building block for fast multipliers.

## Circuit

```
    x       y       z
    │       │       │
    └───┬───┴───┬───┘
        │       │
    ┌───┴───┐   │
    │  XOR  │   │
    │ (x,y) │   │
    └───┬───┘   │
        │       │
    ┌───┴───────┴───┐
    │               │
    ▼               ▼
┌───────┐       ┌───────┐
│  XOR  │       │ MAJ   │
│(xy^,z)│       │(x,y,z)│
└───────┘       └───────┘
    │               │
    ▼               ▼
   Sum            Carry
```

## Function

```
compress(x, y, z) -> (sum, carry)

where: x + y + z = sum + 2*carry
```

The compressor preserves the arithmetic sum while reducing bit count from 3 to 2.

## Truth Table

| x | y | z | Sum | x+y+z | Sum | Carry | Sum+2*Carry |
|---|---|---|-----|:-----:|:---:|:-----:|:-----------:|
| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| 0 | 0 | 1 | 1 | 1 | 1 | 0 | 1 |
| 0 | 1 | 0 | 1 | 1 | 1 | 0 | 1 |
| 0 | 1 | 1 | 2 | 2 | 0 | 1 | 2 |
| 1 | 0 | 0 | 1 | 1 | 1 | 0 | 1 |
| 1 | 0 | 1 | 2 | 2 | 0 | 1 | 2 |
| 1 | 1 | 0 | 2 | 2 | 0 | 1 | 2 |
| 1 | 1 | 1 | 3 | 3 | 1 | 1 | 3 |

## Mechanism

The 3:2 compressor is identical to a full adder, computing:

- **Sum** = x XOR y XOR z (odd parity of inputs)
- **Carry** = MAJ(x, y, z) = majority function (at least 2 inputs high)

**Sum computation (6 neurons):**
```
xor_xy = XOR(x, y)     # 3 neurons
sum = XOR(xor_xy, z)   # 3 neurons
```

**Carry computation (1 neuron):**
```
carry = (x + y + z >= 2)  # Threshold gate with weights [1,1,1], bias -2
```

## Architecture

| Component | Function | Neurons | Layers |
|-----------|----------|---------|--------|
| XOR(x,y) | First XOR | 3 | 2 |
| XOR(xy,z) | Sum output | 3 | 2 |
| MAJ(x,y,z) | Carry output | 1 | 1 |

**Total: 7 neurons**

Note: Sum requires 4 layers (2 sequential XORs), Carry requires 1 layer. Overall depth is 4.

## Parameters

| | |
|---|---|
| Inputs | 3 |
| Outputs | 2 (sum, carry) |
| Neurons | 7 |
| Layers | 4 |
| Parameters | 22 |
| Magnitude | 23 |

## Why "Compressor"?

In multiplier design, partial products create columns of bits that must be summed. A 3:2 compressor reduces 3 bits in a column to 2 bits, with the carry going to the next column:

```
Before:  x  y  z     (3 bits in one column)
After:   s  c        (1 bit in this column, 1 in next)
```

Multiple compressors work in parallel to reduce partial products.

## Usage

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

w = load_file('model.safetensors')

def xor2(a, b, prefix):
    inp = torch.tensor([float(a), float(b)])
    or_out = int((inp @ w[f'{prefix}.or.weight'].T + w[f'{prefix}.or.bias'] >= 0).item())
    nand_out = int((inp @ w[f'{prefix}.nand.weight'].T + w[f'{prefix}.nand.bias'] >= 0).item())
    l1 = torch.tensor([float(or_out), float(nand_out)])
    return int((l1 @ w[f'{prefix}.and.weight'].T + w[f'{prefix}.and.bias'] >= 0).item())

def compress_3to2(x, y, z):
    # Sum = x XOR y XOR z
    xor_xy = xor2(x, y, 'xor1')
    sum_out = xor2(xor_xy, z, 'xor2')

    # Carry = MAJ(x, y, z)
    inp = torch.tensor([float(x), float(y), float(z)])
    carry = int((inp @ w['maj.weight'].T + w['maj.bias'] >= 0).item())

    return sum_out, carry

# Examples
print(compress_3to2(0, 0, 0))  # (0, 0) -> 0
print(compress_3to2(1, 1, 0))  # (0, 1) -> 2
print(compress_3to2(1, 1, 1))  # (1, 1) -> 3
```

## Applications

- Wallace tree multipliers
- Dadda tree multipliers
- Carry-save adder arrays
- Multi-operand addition
- DSP accumulator chains

## Related Circuits

- `threshold-4to2-compressor`: Reduces 4+carry to 2+carry
- `threshold-fulladder`: Same circuit, different context
- `threshold-wallace-tree-3x3`: Uses multiple 3:2 compressors

## Files

```
threshold-3to2-compressor/
├── model.safetensors
├── model.py
├── create_safetensors.py
├── config.json
└── README.md
```

## License

MIT