|
Download README.md from mxv456/spatial-wave-search-512m-hero: direct link, hf CLI and curl.
- Browser
- Download file 5.44 kB
-
https://huggingface.co/mxv456/spatial-wave-search-512m-hero/resolve/main/README.md
- Command line
-
hf download hf://mxv456/spatial-wave-search-512m-hero/README.md
-
curl -L -o README.md https://huggingface.co/mxv456/spatial-wave-search-512m-hero/resolve/main/README.md
5.44 kB
| 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) | |
|  | |
| *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`. | |