Upload README.md with huggingface_hub

README.md

@@ -9,7 +9,7 @@ tags:
 
 # threshold-exactly2outof8
 
-Exactly-2-out-of-8 detector. Fires when exactly two inputs are active.
+Exactly-2-out-of-8 detector. Fires when precisely two inputs are active. The pair detector.
 
 ## Circuit
 
@@ -22,8 +22,7 @@ Exactly-2-out-of-8 detector. Fires when exactly two inputs are active.
        ▼               ▼
   ┌─────────┐     ┌─────────┐
   │ AtLeast2│     │ AtMost2 │
-  │ w: +1×8 │     │ w: -1×8 │
-  │ b:  -2  │     │ b:  +2  │
+  │  HW ≥ 2 │     │  HW ≤ 2 │
   └─────────┘     └─────────┘
        │               │
        └───────┬───────┘
@@ -36,25 +35,86 @@ Exactly-2-out-of-8 detector. Fires when exactly two inputs are active.
           (HW = 2?)
 ```
 
+## The Pair Detection Problem
+
+Detecting exactly two active inputs is useful in:
+
+- **Error detection**: Exactly 2 bit flips in a codeword
+- **Voting systems**: Detecting ties in 4-person subcommittees
+- **Combinatorics**: Enumerating pairs from a set
+
+There are C(8,2) = 28 input patterns that fire this circuit.
+
 ## Mechanism
 
-- **AtLeast2**: Fires when HW ≥ 2 (bias -2)
-- **AtMost2**: Fires when HW ≤ 2 (weights -1, bias +2)
-- **AND**: Exactly2 = AtLeast2 AND AtMost2
+Two threshold neurons work in concert:
+
+**AtLeast2** (lower bound):
+```
+sum = x₀ + x₁ + ... + x₇ - 2
+fires when sum ≥ 0, i.e., HW ≥ 2
+```
+
+**AtMost2** (upper bound):
+```
+sum = -x₀ - x₁ - ... - x₇ + 2
+fires when sum ≥ 0, i.e., -HW + 2 ≥ 0, i.e., HW ≤ 2
+```
+
+The AND gate computes the intersection: HW ≥ 2 AND HW ≤ 2 = HW = 2.
 
 ## Truth Table
 
-| HW | AtLeast2 | AtMost2 | Exactly2 |
-|----|----------|---------|----------|
+| HW | AtLeast2 | AtMost2 | Output |
+|----|----------|---------|--------|
 | 0 | 0 | 1 | 0 |
 | 1 | 0 | 1 | 0 |
-| 2 | 1 | 1 | **1** |
+| **2** | **1** | **1** | **1** |
 | 3 | 1 | 0 | 0 |
-| ... | 1 | 0 | 0 |
+| 4+ | 1 | 0 | 0 |
 
-## Architecture
+## Parameters
 
-**3 neurons, 21 parameters, 2 layers**
+| Component | Weights | Bias |
+|-----------|---------|------|
+| AtLeast2 | [+1, +1, +1, +1, +1, +1, +1, +1] | -2 |
+| AtMost2 | [-1, -1, -1, -1, -1, -1, -1, -1] | +2 |
+| AND | [+1, +1] | -2 |
+
+**Total: 3 neurons, 21 parameters, 2 layers**
+
+## Contrast with At-Least-2
+
+| Circuit | Condition | Fires on HW |
+|---------|-----------|-------------|
+| 2-out-of-8 | HW ≥ 2 | 2, 3, 4, 5, 6, 7, 8 |
+| **Exactly-2** | HW = 2 | 2 only |
+
+The existing `threshold-2outof8` fires on 247 of 256 inputs. This circuit fires on only 28.
+
+## Usage
+
+```python
+from safetensors.torch import load_file
+import torch
+
+w = load_file('model.safetensors')
+
+def exactly2(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)
+
+# Pair: positions 2 and 5 active
+bits = [0, 0, 1, 0, 0, 1, 0, 0]
+print(exactly2(bits))  # 1
+
+# Three active - not a pair
+bits = [1, 0, 1, 0, 0, 1, 0, 0]
+print(exactly2(bits))  # 0
+```
 
 ## Files