Upload routing/routing_schema.md with huggingface_hub

routing/routing_schema.md

@@ -0,0 +1,103 @@
+# Routing Schema for 8-bit Threshold Computer
+
+## Overview
+
+The routing file (`routing.json`) defines how gates are interconnected. Each entry maps a gate path to its input sources.
+
+## Schema Format
+
+```json
+{
+  "version": 1,
+  "external_inputs": {
+    "circuit_path": ["input_name", ...]
+  },
+  "routing": {
+    "gate_path": ["source1", "source2", ...]
+  }
+}
+```
+
+## Input Source Types
+
+1. **External input**: `"$input_name"` - Named input to the circuit
+   - Example: `"$a"`, `"$b"`, `"$cin"`
+
+2. **Gate output**: `"path.to.gate"` - Output of another gate
+   - Example: `"ha1.sum"`, `"layer1.or"`
+
+3. **Bit extraction**: `"$input[i]"` - Single bit from multi-bit input
+   - Example: `"$a[0]"` (LSB), `"$a[7]"` (MSB for 8-bit)
+
+4. **Constant**: `"#0"` or `"#1"` - Fixed value
+   - Example: `"#1"` for carry-in in two's complement
+
+5. **Relative reference**: `"../sibling.gate"` - Reference to sibling in hierarchy
+   - Example: `"../fa0.cout"` from fa1
+
+## Circuit Types
+
+### Single-Layer Gates
+Gates with just `.weight` and `.bias`:
+```json
+"boolean.and": ["$a", "$b"]
+```
+
+### Two-Layer Gates (XOR, XNOR)
+Gates decomposed into layer1 + layer2:
+```json
+"boolean.xor.layer1.or": ["$a", "$b"],
+"boolean.xor.layer1.nand": ["$a", "$b"],
+"boolean.xor.layer2": ["layer1.or", "layer1.nand"]
+```
+
+### Hierarchical Circuits
+Complex circuits with sub-components:
+```json
+"arithmetic.fulladder": {
+  "external_inputs": ["$a", "$b", "$cin"],
+  "gates": {
+    "ha1.sum.layer1.or": ["$a", "$b"],
+    "ha1.sum.layer1.nand": ["$a", "$b"],
+    "ha1.sum.layer2": ["ha1.sum.layer1.or", "ha1.sum.layer1.nand"],
+    "ha1.carry": ["$a", "$b"],
+    "ha2.sum.layer1.or": ["ha1.sum", "$cin"],
+    "ha2.sum.layer1.nand": ["ha1.sum", "$cin"],
+    "ha2.sum.layer2": ["ha2.sum.layer1.or", "ha2.sum.layer1.nand"],
+    "ha2.carry": ["ha1.sum", "$cin"],
+    "carry_or": ["ha1.carry", "ha2.carry"]
+  },
+  "outputs": {
+    "sum": "ha2.sum",
+    "cout": "carry_or"
+  }
+}
+```
+
+### Bit-Indexed Circuits
+Circuits operating on multi-bit values:
+```json
+"arithmetic.ripplecarry8bit": {
+  "external_inputs": ["$a[0:7]", "$b[0:7]"],
+  "gates": {
+    "fa0": {"inputs": ["$a[0]", "$b[0]", "#0"], "type": "fulladder"},
+    "fa1": {"inputs": ["$a[1]", "$b[1]", "fa0.cout"], "type": "fulladder"},
+    ...
+  }
+}
+```
+
+## Naming Conventions
+
+- External inputs: `$name` or `$name[bit]`
+- Constants: `#0`, `#1`
+- Internal gates: relative path from circuit root
+- Outputs: named in `outputs` section
+
+## Validation Rules
+
+1. Every gate in routing must exist in tensors file
+2. Every tensor must have routing entry
+3. Input count must match weight dimensions
+4. No circular dependencies (DAG only)
+5. All referenced sources must exist