Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,98 @@
+---
+license: mit
+tags:
+- formal-verification
+- coq
+- threshold-logic
+- neuromorphic
+- modular-arithmetic
+---
+
+# tiny-mod9-verified
+
+Formally verified MOD-9 circuit. Single-layer threshold network computing modulo-9 arithmetic with 100% accuracy.
+
+## Architecture
+
+| Component | Value |
+|-----------|-------|
+| Inputs | 8 |
+| Outputs | 1 (per residue class) |
+| Neurons | 9 (one per residue 0-8) |
+| Parameters | 81 (9 × 9) |
+| Weights | [1, 1, 1, 1, 1, 1, 1, 1] |
+| Bias | 0 |
+| Activation | Heaviside step |
+
+## Key Properties
+
+- 100% accuracy (256/256 inputs correct)
+- Coq-proven correctness
+- All-ones weight pattern (m > input width)
+- Computes Hamming weight mod 9
+- Compatible with neuromorphic hardware
+
+## Algebraic Pattern
+
+MOD-9 uses all-ones weights because the reset position (position 9) is beyond the 8-bit input width:
+- All positions 1-8: weight = 1
+- Position 9 (beyond input): would be weight = 1-9 = -8
+
+The circuit tracks cumulative sum mod 9 using the Hamming weight directly.
+
+## Usage
+
+```python
+import torch
+from safetensors.torch import load_file
+
+weights = load_file('mod9.safetensors')
+
+def mod9_circuit(bits):
+    # bits: list of 8 binary values
+    inputs = torch.tensor([float(b) for b in bits])
+    weighted_sum = (inputs * weights['weight']).sum() + weights['bias']
+    # Weighted sum equals Hamming weight for all-ones weights
+    return int(weighted_sum.item()) % 9
+
+# Test
+print(mod9_circuit([1,1,1,1,1,1,1,1]))  # 8 mod 9 = 8
+print(mod9_circuit([1,1,1,1,1,1,1,1]))  # 8 mod 9 = 8
+```
+
+## Verification
+
+**Coq Theorem**:
+```coq
+Theorem mod9_correct_residue_0 : forall x0 x1 x2 x3 x4 x5 x6 x7,
+  mod9_is_zero [x0; x1; x2; x3; x4; x5; x6; x7] =
+  Z.eqb ((Z.of_nat (hamming_weight [x0; x1; x2; x3; x4; x5; x6; x7])) mod 9) 0.
+```
+
+Proven axiom-free using algebraic weight patterns.
+
+Full proof: [coq-circuits/Modular/Mod9.v](https://github.com/CharlesCNorton/coq-circuits/blob/main/coq/Modular/Mod9.v)
+
+## Residue Distribution
+
+For 8-bit inputs (256 total):
+- Residue 0: 1 inputs
+- Residue 1: 8 inputs
+- Residue 2: 28 inputs
+- Residue 3: 56 inputs
+- Residue 4: 70 inputs
+- Residue 5: 56 inputs
+- Residue 6: 28 inputs
+- Residue 7: 8 inputs
+- Residue 8: 1 inputs
+
+## Citation
+
+```bibtex
+@software{tiny_mod9_verified_2025,
+  title={tiny-mod9-verified: Formally Verified MOD-9 Circuit},
+  author={Norton, Charles},
+  url={https://huggingface.co/phanerozoic/tiny-mod9-verified},
+  year={2025}
+}
+```