Update README with full instructions

README.md

@@ -1,80 +1,94 @@
 # NeuroGolf Solver
 
-Solves ARC-AGI tasks by building minimal ONNX networks.
+Builds minimal ONNX networks for ARC-AGI tasks. Currently solves **127/400** on CPU (15s budget). With more time budget on faster hardware, expected **~140+**.
 
-## Current Results
-- **127/400** tasks solved on CPU with 15s budget per task
-- Expected **~140+** with 30s budget on faster hardware
+## Repo
+https://huggingface.co/rogermt/neurogolf-solver
 
-## How to Run
+## Quick Start
 
-### 1. Clone & setup
 ```bash
+# 1. Clone
 git clone https://huggingface.co/rogermt/neurogolf-solver
 cd neurogolf-solver
-pip install numpy onnx onnxruntime
+
+# 2. Install deps
+pip install numpy onnx onnxruntime   # or onnxruntime-gpu for CUDA
+
+# 3. Get ARC data
 git clone --depth 1 https://github.com/fchollet/ARC-AGI.git
-```
 
-### 2. Run solver
-```bash
-# Default (30s conv budget per task)
-python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 30
+# 4. Run (pick your config)
+# CPU, 30s per task (~5 min total):
+python neurogolf_solver.py --device cpu --conv_budget 30
 
-# Faster but fewer tasks
-python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 15
+# CPU, 60s per task (~10 min, more tasks solved):
+python neurogolf_solver.py --device cpu --conv_budget 60
 
-# More time = more tasks solved (tries larger conv kernels)
-python neurogolf_solver.py --data_dir ARC-AGI/data/training/ --output_dir submission --conv_budget 60
-```
+# CUDA (if onnxruntime-gpu installed):
+python neurogolf_solver.py --device cuda --conv_budget 60
 
-### 3. On Kaggle (if task JSONs are in competition format)
-```bash
-python neurogolf_solver.py --data_dir /kaggle/input/competitions/neurogolf-2026/ --output_dir submission --kaggle --conv_budget 30
+# Auto-detect device:
+python neurogolf_solver.py --conv_budget 60
+
+# 5. Results in submission/ directory
+ls submission/*.onnx | wc -l
 ```
 
-### 4. Create submission zip
+## Create submission.zip for Kaggle
 ```python
 import zipfile, os
 with zipfile.ZipFile('submission.zip', 'w', zipfile.ZIP_DEFLATED) as zf:
     for f in sorted(os.listdir('submission')):
         if f.endswith('.onnx'):
             zf.write(os.path.join('submission', f), f)
+print(f"Created submission.zip: {os.path.getsize('submission.zip')/1024:.0f} KB")
+```
+
+## How It Works
+
+**Format:** Input/output = `[1, 10, 30, 30]` one-hot float32. ONNX opset 10, IR version 10.
+
+**Main pipeline (conv solver):**
 ```
+Input [1,10,30,30] -> Slice [1,10,H,W] -> Conv2d -> ArgMax -> OneHot -> Pad [1,10,30,30]
+```
+
+- Learns optimal conv weights via **least-squares** on one-hot patches
+- Tries kernel sizes 1, 3, 5, ..., 29 (smallest first)
+- Also tries with bias for better boundary handling
+- ArgMax + OneHot eliminates numerical precision issues
+
+**Analytical solvers** (instant, tiny models): identity, color_map (1x1 conv), transpose, flip, rotate, tile, upscale, concat, spatial_gather, constant.
+
+## Key Parameters
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--device` | `auto` | `cpu`, `cuda`, or `auto` |
+| `--conv_budget` | `30` | Seconds per task for conv solver. More = more tasks solved |
+| `--data_dir` | `ARC-AGI/data/training/` | Path to task JSONs |
+| `--output_dir` | `submission` | Where to save .onnx files |
+| `--kaggle` | off | Use Kaggle task format (task001.json) |
+| `--tasks` | all | Comma-separated task numbers (e.g., `1,2,3`) |
+
+## Architecture of generated ONNX models
+
+Each .onnx file is a tiny network, typically:
+- **Same-shape tasks**: Single Conv2d layer (10→10 channels, kernel 1-29)
+- **Different-shape tasks**: GatherElements-based pixel remapping
+- **Cost** = MACs + memory_bytes + params → **Score** = max(1, 25 - ln(cost))
+
+## What's NOT solved yet (273 tasks)
+
+- Variable-shape tasks (input size differs across examples) — need dynamic ONNX
+- Tasks requiring multi-step reasoning (flood fill, gravity, object detection)
+- Tasks where the transformation depends on counting/global properties
+- Large grids where conv kernel > 29 is needed
+
+## Feedback logs
 
-## Architecture
-
-Each ONNX model follows one of these patterns:
-
-1. **Conv solver** (most tasks): `Slice[1,10,H,W] -> Conv2d -> ArgMax -> OneHot -> Pad[1,10,30,30]`
-   - Learns optimal conv weights via least-squares on one-hot encoded patches
-   - Tries kernel sizes 1,3,5,...,29 and picks smallest that fits perfectly
-   - Also tries with bias term for better boundary handling
-
-2. **Analytical solvers** (fast, tiny models):
-   - `identity`: Identity op
-   - `color_map`: 1x1 conv (channel permutation)
-   - `transpose`: Transpose dims 2,3
-   - `flip`: GatherElements with reversed indices
-   - `rotate`: GatherElements with rotated indices
-   - `tile`: Slice -> Tile -> Pad
-   - `upscale`: GatherElements with repeated indices
-   - `concat`: GatherElements with block-transformed indices
-   - `spatial_gather`: GatherElements with per-pixel source mapping
-   - `constant`: Multiply by 0, add constant
-
-## Format
-- Input: `[1, 10, 30, 30]` float32 (one-hot encoded grid, padded to 30x30)
-- Output: `[1, 10, 30, 30]` float32 (one-hot encoded grid)
-- Scoring: `(output > 0.0).astype(float)` must match expected one-hot
-- ONNX opset 10, IR version 10
-
-## Key Insight
-The critical trick is **Slice -> Conv -> ArgMax -> OneHot -> Pad**:
-- Slice extracts the actual grid from the 30x30 padded input (avoiding color-0 boundary issues)
-- Conv applies the learned transformation with zero-padding
-- ArgMax finds the winning color channel
-- OneHot converts back to clean one-hot (eliminates numerical precision issues)
-- Pad restores to 30x30
-
-Without ArgMax+OneHot, slight numerical noise from the conv causes validation failures.
+After running, please share the full terminal output — especially:
+1. The "Solved: X/400" line
+2. Any errors
+3. Total time taken