--- license: mit library_name: pytorch pipeline_tag: image-segmentation tags: - spatial-reasoning - path-finding - iterative-computation - vision-transformer - maps - amsterdam - from-scratch model-index: - name: spatial-wave-search-512m-hero results: - task: type: path-finding name: route search on map layers, free-running on the network's own scratchpad dataset: type: custom name: Zuid + Centrum (Amsterdam) 512 m validation routes, 500 routes, 40–500 m straight / up to 1.1 km walking metrics: - type: solved-share name: "solved (cell rule: connected, no building cell, ≤ 1.10 × walking length)" value: 0.32 - task: type: path-finding name: zero-shot on a synthetic house maze (never trained on mazes) dataset: type: custom name: house maze, 512 m windows, 500 validation routes metrics: - type: solved-share name: "solved (cell rule)" value: 0.40 --- # A 9 M-parameter transformer that runs a path search on its own scratchpad (512 m windows) ![Free-running search through a house maze it has never seen](wave_search_512m_house_maze_route008_431m.gif) *Figure. A free-running search by this network on a synthetic house maze (512 m window, 2 m cells). Each frame is one pass: the orange cells are the network's whole output, fed back verbatim as its next input. The state token it emits (SEARCH → BACK → DRAW → DONE) chooses the next pass; nothing outside the network decides anything between passes. Route of 431 m walking, 26 passes. The network was trained only on Amsterdam map layers.* This is the network behind the headline animation of [spatial-reasoning-from-scratch](https://github.com/Marvel4U/spatial-reasoning-from-scratch), a study of what spatial reasoning a small vision transformer can learn from spatially aligned city map layers with exact targets. It is **not** a vision-language model: input and output are rasters. ## What it does - **Input:** a 512 m × 512 m window of Amsterdam drawn as 17 aligned planes at 1 m per pixel (buildings, surface classes, road noise, places, sunshine, …), two markers (start and goal) in a marker plane, and a scratchpad plane holding its own previous output. - **Output:** the whole next scratchpad on a 256 × 256 grid of 2 m cells, plus one state token. - **The algorithm it learnt** (from a teacher: one clearance-priced wave per route): spread a front 40 m further each pass until the goal is reached, then walk the way back front by front, then draw the path. Run free, it solves 32 % of 500 held-out 512 m routes (91 / 71 / 33 / 18 / 2 % for routes of 2–3 / 4–5 / 6–8 / 9–12 / 13+ fronts) and 40 % of 500 routes on a synthetic house maze it never saw. One pass takes 2.4 ms on an RTX 3060; a route about 60 ms. ## Model 4 transformer blocks, width 384, 6 heads, 16 px patches (1,024 tokens at 512 m), learned relative position bias, two condition tokens (state, task), a per-cell 2-class head and a 41-class token head; 8.86 M parameters. Trained from scratch: 48k steps at 256 m, one round of training on its own drawings ("natural noise"), then continued for 16k steps at 512 m (batch 64, lr 1e-4). Run id `c5_r5_wave_nat3_tok01_from_ownp50_L4_16k_g256_b64_zc512` in the repository's run ledger. ## How to use The checkpoint is a plain `state_dict` for the `LocalGridViT` class of the repository; it needs that code and the data pipeline (or the released evaluation bundle): ```bash git clone https://github.com/Marvel4U/spatial-reasoning-from-scratch # place this file as runs/checkpoints/c5_r5_wave_nat3_tok01_from_ownp50_L4_16k_g256_b64_zc512.pt # unpack eval_bundle_v0.2.tar.gz of the GitHub release and copy its data/ and runs/ into the clone (REPRODUCE.md section 8) cd harness PYTHONPATH=. python diagnostics/wave_rollout_eval.py c5_r5_wave_nat3_tok01_from_ownp50_L4_16k_g256_b64_zc512 --n 500 --mode free PYTHONPATH=. python diagnostics/wave_rollout_gif.py c5_r5_wave_nat3_tok01_from_ownp50_L4_16k_g256_b64_zc512 --route 8 --crops ../data/synthetic/maze_v2_houses/crops/v4ns --store c4_512_val ``` `REPRODUCE.md` in the repository lists every command with wall times. ## Related models - [`mxv456/spatial-wave-search-256m`](https://huggingface.co/mxv456/spatial-wave-search-256m): the 256 m network, the stronger one on its own window (78 % of 500 held-out routes, 60 % on a never-seen district, 51 % on house mazes). - [`mxv456/qwen3-vl-2b-lora-map-routes`](https://huggingface.co/mxv456/qwen3-vl-2b-lora-map-routes): the Qwen3-VL-2B LoRA fine-tune on the same routes, the vision-language baseline of the repository's `PAPER.md` (49.6 % under the same rule). ## Limitations One city for training; held-out routes of the training district and one never-seen district of the same city; single seed; the success rule scores the drawing as a set of cells; long routes (13+ fronts) are mostly unsolved at this size. ## Citation and licence Marvin Uhlmann, *Spatial reasoning from scratch on real city data*, 2026, [github.com/Marvel4U/spatial-reasoning-from-scratch](https://github.com/Marvel4U/spatial-reasoning-from-scratch). Code and weights MIT; the Amsterdam layers carry their own licences (3DBAG CC BY 4.0, BGT CC0, AHN CC0, OSM ODbL, Overture CDLA-Permissive), listed in the repository's `DATA_LICENSES.md`.