Upload README.md with huggingface_hub

README.md

@@ -9,7 +9,7 @@ tags:
 
 # threshold-exactly3outof8
 
-Exactly-3-out-of-8 detector. Fires when exactly three inputs are active.
+Exactly-3-out-of-8 detector. Fires when precisely three inputs are active. The triple detector.
 
 ## Circuit
 
@@ -21,9 +21,8 @@ Exactly-3-out-of-8 detector. Fires when exactly three inputs are active.
        ┌───────┴───────┐
        ▼               ▼
   ┌─────────┐     ┌─────────┐
-  │ AtLeast3│     │ AtMost3 │
-  │ w: +1×8 │     │ w: -1×8 │
-  │ b:  -3  │     │ b:  +3  │
+  │  ≥ 3    │     │  ≤ 3    │
+  │ b = -3  │     │ b = +3  │
   └─────────┘     └─────────┘
        │               │
        └───────┬───────┘
@@ -33,26 +32,100 @@ Exactly-3-out-of-8 detector. Fires when exactly three inputs are active.
           └─────────┘
                │
                ▼
-          (HW = 3?)
+         exactly 3?
 ```
 
-## Mechanism
+## Why Three Matters
 
-- **AtLeast3**: Fires when HW ≥ 3 (bias -3)
-- **AtMost3**: Fires when HW ≤ 3 (weights -1, bias +3)
-- **AND**: Exactly3 = AtLeast3 AND AtMost3
+Three is the smallest odd number greater than one. In voting:
 
-## Truth Table
+- **Byzantine fault tolerance**: 3f+1 nodes tolerate f failures
+- **Quorum systems**: Often require ⌈n/2⌉ + 1 = 3 for n=4
+- **Graph theory**: A triangle is the minimal clique
 
-| HW | Result |
-|----|--------|
-| 0-2 | 0 |
-| 3 | **1** |
-| 4-8 | 0 |
+There are C(8,3) = 56 input patterns that fire this circuit - exactly double the pairs.
 
-## Architecture
+## The Threshold Sandwich
 
-**3 neurons, 21 parameters, 2 layers**
+The circuit squeezes Hamming weight between two bounds:
+
+```
+Lower bound (AtLeast3):     Upper bound (AtMost3):
+  +x₀ + x₁ + ... + x₇         -x₀ - x₁ - ... - x₇
+  ─────────────────────       ─────────────────────
+           -3                          +3
+
+  fires if HW ≥ 3             fires if HW ≤ 3
+```
+
+The AND gate demands both conditions simultaneously. Only HW = 3 satisfies both.
+
+## Input Distribution
+
+| HW | Count | Exactly3 |
+|----|-------|----------|
+| 0 | 1 | 0 |
+| 1 | 8 | 0 |
+| 2 | 28 | 0 |
+| **3** | **56** | **1** |
+| 4 | 70 | 0 |
+| 5 | 56 | 0 |
+| 6 | 28 | 0 |
+| 7 | 8 | 0 |
+| 8 | 1 | 0 |
+
+The binomial distribution peaks at HW=4, but HW=3 and HW=5 are tied at 56 patterns each.
+
+## Parameters
+
+| Component | Weights | Bias |
+|-----------|---------|------|
+| AtLeast3 | all +1 | -3 |
+| AtMost3 | all -1 | +3 |
+| AND | [+1, +1] | -2 |
+
+**Total: 3 neurons, 21 parameters, 2 layers**
+
+## Duality with Exactly5
+
+Exactly3 and Exactly5 are complementary around the center:
+
+| Circuit | Fires on | Count | Complement |
+|---------|----------|-------|------------|
+| Exactly3 | HW = 3 | 56 | HW = 5 |
+| Exactly5 | HW = 5 | 56 | HW = 3 |
+
+If you flip all 8 bits, an Exactly3 input becomes Exactly5, and vice versa.
+
+## Usage
+
+```python
+from safetensors.torch import load_file
+import torch
+
+w = load_file('model.safetensors')
+
+def exactly3(bits):
+    inp = torch.tensor([float(b) for b in bits])
+    atleast = int((inp * w['atleast.weight']).sum() + w['atleast.bias'] >= 0)
+    atmost = int((inp * w['atmost.weight']).sum() + w['atmost.bias'] >= 0)
+    comb = torch.tensor([float(atleast), float(atmost)])
+    return int((comb * w['and.weight']).sum() + w['and.bias'] >= 0)
+
+# Triangle: positions 0, 3, 7 active
+bits = [1, 0, 0, 1, 0, 0, 0, 1]
+print(exactly3(bits))  # 1
+```
+
+## Files
+
+```
+threshold-exactly3outof8/
+├── model.safetensors
+├── model.py
+├── config.json
+└── README.md
+```
 
 ## License