Upload folder using huggingface_hub

README.md

@@ -0,0 +1,175 @@
+---
+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

config.json

@@ -0,0 +1,9 @@
+{
+  "name": "threshold-3to2-compressor",
+  "description": "3:2 compressor (carry-save adder) for multiplier trees",
+  "inputs": 3,
+  "outputs": 2,
+  "neurons": 7,
+  "layers": 4,
+  "parameters": 22
+}

create_safetensors.py

@@ -0,0 +1,75 @@
+import torch
+from safetensors.torch import save_file
+
+weights = {}
+
+# 3:2 Compressor
+# Inputs: x, y, z
+# Outputs: sum = x XOR y XOR z, carry = MAJ(x,y,z)
+# Preserves: x + y + z = sum + 2*carry
+
+# XOR block helper
+def add_xor(prefix):
+    weights[f'{prefix}.or.weight'] = torch.tensor([[1.0, 1.0]], dtype=torch.float32)
+    weights[f'{prefix}.or.bias'] = torch.tensor([-1.0], dtype=torch.float32)
+    weights[f'{prefix}.nand.weight'] = torch.tensor([[-1.0, -1.0]], dtype=torch.float32)
+    weights[f'{prefix}.nand.bias'] = torch.tensor([1.0], dtype=torch.float32)
+    weights[f'{prefix}.and.weight'] = torch.tensor([[1.0, 1.0]], dtype=torch.float32)
+    weights[f'{prefix}.and.bias'] = torch.tensor([-2.0], dtype=torch.float32)
+
+# XOR gates for sum
+add_xor('xor1')  # XOR(x, y)
+add_xor('xor2')  # XOR(xor1, z)
+
+# Majority gate for carry
+weights['maj.weight'] = torch.tensor([[1.0, 1.0, 1.0]], dtype=torch.float32)
+weights['maj.bias'] = torch.tensor([-2.0], dtype=torch.float32)
+
+save_file(weights, 'model.safetensors')
+
+def xor2(a, b, prefix):
+    inp = torch.tensor([float(a), float(b)])
+    or_out = int((inp @ weights[f'{prefix}.or.weight'].T + weights[f'{prefix}.or.bias'] >= 0).item())
+    nand_out = int((inp @ weights[f'{prefix}.nand.weight'].T + weights[f'{prefix}.nand.bias'] >= 0).item())
+    l1 = torch.tensor([float(or_out), float(nand_out)])
+    return int((l1 @ weights[f'{prefix}.and.weight'].T + weights[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 @ weights['maj.weight'].T + weights['maj.bias'] >= 0).item())
+
+    return sum_out, carry
+
+print("Verifying 3:2 compressor...")
+errors = 0
+for x in [0, 1]:
+    for y in [0, 1]:
+        for z in [0, 1]:
+            s, c = compress_3to2(x, y, z)
+            input_sum = x + y + z
+            output_sum = s + 2 * c
+            if input_sum != output_sum:
+                errors += 1
+                print(f"ERROR: {x}+{y}+{z}={input_sum}, but s={s},c={c} gives {output_sum}")
+
+if errors == 0:
+    print("All 8 test cases passed!")
+else:
+    print(f"FAILED: {errors} errors")
+
+print(f"Magnitude: {sum(t.abs().sum().item() for t in weights.values()):.0f}")
+print(f"Parameters: {sum(t.numel() for t in weights.values())}")
+
+print("\nTruth Table:")
+print("x y z | sum carry | x+y+z = s+2c")
+print("------+-----------+-------------")
+for x in [0, 1]:
+    for y in [0, 1]:
+        for z in [0, 1]:
+            s, c = compress_3to2(x, y, z)
+            print(f"{x} {y} {z} |  {s}    {c}   |   {x+y+z}   =  {s+2*c}")

model.py

@@ -0,0 +1,34 @@
+import torch
+from safetensors.torch import load_file
+
+def load_model(path='model.safetensors'):
+    return load_file(path)
+
+def xor2(a, b, prefix, w):
+    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, weights):
+    """3:2 compressor: returns (sum, carry) where x+y+z = sum + 2*carry."""
+    xor_xy = xor2(x, y, 'xor1', weights)
+    sum_out = xor2(xor_xy, z, 'xor2', weights)
+
+    inp = torch.tensor([float(x), float(y), float(z)])
+    carry = int((inp @ weights['maj.weight'].T + weights['maj.bias'] >= 0).item())
+
+    return sum_out, carry
+
+if __name__ == '__main__':
+    w = load_model()
+    print('3:2 Compressor Truth Table:')
+    print('x y z | sum carry | verify')
+    print('------+-----------+-------')
+    for x in [0, 1]:
+        for y in [0, 1]:
+            for z in [0, 1]:
+                s, c = compress_3to2(x, y, z, w)
+                check = 'OK' if (x + y + z) == (s + 2 * c) else 'FAIL'
+                print(f'{x} {y} {z} |  {s}    {c}   | {check}')

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e5976fe24a7ece79751d3d87419e1db05976c6fd80f0aa5b92e3438c6ba60b0
+size 1056