# SWARM_VISUALIZATION.md

Documents exactly how computational values become visual properties in the SnapKitty Parallel Swarm Space.

Every visual element listed below has a computational source. Nothing is decorative.

---

## Visual Property Map

| Visual Element | Computational Source | Transformation | File |
|----------------|----------------------|----------------|------|
| Node X (3D) | `event.tick` | Direct: x = tick | `swarm_engine.py` |
| Node Y (3D) | Swarm type | Layer: resonance=0, subleq=1, dag=2, quantum=3, algebra=4 | `swarm_engine.py` |
| Node Z (3D) | State value | Normalized per swarm (see table below) | `swarm_engine.py` |
| Node color | Event outcome | Branch=#00ff88, Fall=#ff4444, swarm base otherwise | `swarm_engine.py` |
| Node size | Magnitude | 5 + scaled(payload mod 6, |result|/50, comm_norm×30, round×3) | `swarm_engine.py` |
| Connection line | Cross-swarm link | Resonance→SUBLEQ: payload→activation; SUBLEQ→DAG; DAG→Algebra | `swarm_engine.py` |
| Radial angle | Event index within swarm | θ = 2π × index / count | `app.py` |
| Radial radius | Layer + Z | r = 1.0 + layer×0.8 + z×0.35 | `app.py` |
| Bit pattern pixel | 64-bit Resonance Word | Binary decomposition of GF(p) element: bit[k] = (word >> (63-k)) & 1 | `app.py` |
| Branch arrow direction | SUBLEQ step PC→next_pc | Arrow from (step, PC) to (step+1, next_PC) | `app.py` |
| Convergence curve | Jordan ‖[U,ρ]‖ per iter | Log scale; color #44ff66 when < 0.001 | `app.py` |
| Fusion node position | Anyon fusion round | (index, round) grid; size proportional to round | `app.py` |
| Fusion node color | Fusion outcome | τ=#cc66ff (non-abelian), 1=#9944aa (trivial) | `app.py` |

---

## Z-Axis Encoding Per Swarm

| Swarm | Z value | Source |
|-------|---------|--------|
| Resonance | `lattice_idx / 12288` | Payload mod LATTICE_ORDER, normalized to [0,1] |
| SUBLEQ | `result / max(|result|, 1) × 0.5` | Signed M[B]-M[A] result, clamped |
| DAG | `node_index / 5` | Fixed ordering: EVIDENCE=0 → EXECUTION=1 |
| Quantum | `fusion_round / 5` | Depth in fusion tree |
| Algebra | `commutator_norm` (clamped to [0,1]) | ‖[U,ρ]‖ at each iteration |

---

## Swarm Descriptions

### Resonance Swarm
**Algorithm:** GF(2⁶⁴ − 2³² + 1) field arithmetic.
**What each node is:** One character of input text → 64-bit Goldilocks field element.
**Format:** 8-bit class tag (high) | 56-bit Abjad payload (low).
**Source:** `j-matrix-twin/resonance_word.ijs`, ported to `resonance_word.py`.

### SUBLEQ Swarm
**Algorithm:** Subtract and Branch if Less than or Equal to Zero.
**What each node is:** One execution step of the SUBLEQ machine.
**Memory layout:** 256 cells i32. Program region [0-127]: [A,B,C] triads from quantized activations. Weight region [128-191]: activation magnitudes seeded from resonance payloads.
**Branch condition:** M[B] := M[B] - M[A]; if M[B] ≤ 0 goto C.
**Source:** `j-matrix-twin/subleq_attention.ijs`, ported to `subleq_engine.py`.

### ICP-DAG Swarm
**Algorithm:** Integrity Constraint Propagation — governance DAG with 10 invariants.
**What each node is:** One stage in the governance pipeline.
**Flow:** EVIDENCE → CLAIM → PROOF → DECISION → EXECUTION.
**Rule:** Nothing executes without passing every prior node.
**Source:** `ICP-DAG.m` (MUMPS), `ICP-DAG.lp` (ASP / Clingo).

### Quantum Swarm
**Algorithm:** Fibonacci anyon fusion model.
**What each node is:** One pairwise fusion event.
**Fusion rule:** τ⊗τ = 1⊕τ with probabilities P(1)=φ⁻²≈0.382, P(τ)=φ⁻¹≈0.618.
**Determinism:** Seeded from SHA-256 of input text. Same input → same outcomes.
**EXPLICITLY LABELED:** Classical simulation of Fibonacci anyon fusion. Not physical quantum hardware. No quantum advantage claimed.
**Source:** `FibonacciAnyon.lean` (Lean 4 formalization, incomplete pentagon/hexagon axioms).

### Algebra Swarm
**Algorithm:** Jordan fixed-point iteration.
**What each node is:** One iteration of T(ρ) = φ⁻¹·U·ρ·U† + φ⁻²·ρ.
**Convergence condition:** ‖[U, ρ]‖ → 0 (proved in Lean 4, 0 sorry).
**θ parameter:** Derived from SHA-256(input)[0] / 255 × 2π — input-specific rotation.
**Source:** `sov-kernel-monster/lean/JordanMatrixProof.lean` (0 sorry).

---

## Determinism Guarantee

Same input text → same SHA-256 seed → same numpy RNG state → same quantum fusion outcomes → same Jordan θ → same visualization.

This means the artwork is reproducible. It is a fingerprint of the input computation, not a random animation.

---

## Cross-Swarm Connections

| Connection | Source → Target | What it represents |
|------------|----------------|-------------------|
| Resonance → SUBLEQ | Last resonance event → first SUBLEQ step | Payloads become SUBLEQ activation inputs via phase-magnitude encoding |
| SUBLEQ → DAG | Last SUBLEQ step → DAG EVIDENCE | Execution output triggers governance pipeline entry |
| DAG EXECUTION → Algebra | DAG EXECUTION node → final algebra iteration | Governance completion enables algebraic state update |

---

## What Is NOT Claimed

- No performance benchmark vs. softmax attention (data does not exist — shown as "unavailable")
- No quantum advantage (explicitly labeled "classical simulation")
- No implication that the Fibonacci anyon simulation runs on physical quantum hardware
- No invented measurements (all fields say "unavailable" when no data exists)
- The Jacobian has 0 nonzero entries when inputs don't cross quantization boundaries — this is shown honestly, not hidden

---

## Scientific Separation

| Category | Example in this Space |
|----------|----------------------|
| Algorithm | SUBLEQ M[B]-M[A] subtraction logic |
| Simulation | Fibonacci anyon fusion (classical Monte Carlo) |
| Visualization | Radial mandala, bit constellation, convergence plot |
| Benchmark | "Unavailable" for all performance comparisons |
| Hypothesis | SUBLEQ as attention replacement — unverified |