mxv456 commited on
Commit
6a1d614
·
verified ·
1 Parent(s): fa72655

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +91 -0
README.md ADDED
@@ -0,0 +1,91 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ library_name: pytorch
4
+ pipeline_tag: image-segmentation
5
+ tags:
6
+ - spatial-reasoning
7
+ - path-finding
8
+ - iterative-computation
9
+ - vision-transformer
10
+ - maps
11
+ - amsterdam
12
+ - from-scratch
13
+ model-index:
14
+ - name: spatial-wave-search-256m
15
+ results:
16
+ - task:
17
+ type: path-finding
18
+ name: route search on map layers, free-running on the network's own scratchpad
19
+ dataset:
20
+ type: custom
21
+ name: De Pijp (Amsterdam) held-out validation routes, 500 routes, 40–500 m walking
22
+ metrics:
23
+ - type: solved-share
24
+ name: "solved (cell rule: connected, no building cell, ≤ 1.10 × walking length)"
25
+ value: 0.78
26
+ - type: solved-share
27
+ name: "solved (polyline rule shared with the VLM baseline)"
28
+ value: 0.76
29
+ - task:
30
+ type: path-finding
31
+ name: never-seen district (Zuid + Centrum), 500 validation routes
32
+ dataset:
33
+ type: custom
34
+ name: Zuid + Centrum 256 m validation routes
35
+ metrics:
36
+ - type: solved-share
37
+ name: "solved (cell rule)"
38
+ value: 0.60
39
+ - task:
40
+ type: path-finding
41
+ name: zero-shot on a synthetic house maze
42
+ dataset:
43
+ type: custom
44
+ name: house maze, 256 m windows, 500 validation routes
45
+ metrics:
46
+ - type: solved-share
47
+ name: "solved (cell rule)"
48
+ value: 0.51
49
+ ---
50
+
51
+ # A 9 M-parameter transformer that runs a path search on its own scratchpad (256 m windows)
52
+
53
+ ![A free-running search on a never-seen district](wave_search_256m_unseen_district_route342_295m.gif)
54
+
55
+ *Figure. A free-running search by this network on a district it never saw (Zuid + Centrum, Amsterdam; 256 m window, 2 m cells): start and goal lie on opposite sides of one building, the route is 295 m, 2.4 × the straight line. Each frame is one pass; the orange cells are the network's whole output, fed back as its next input; its own state token (SEARCH → BACK → DRAW → DONE) picks the next pass.*
56
+
57
+ The main result of [spatial-reasoning-from-scratch](https://github.com/Marvel4U/spatial-reasoning-from-scratch): a small vision transformer trained from scratch on spatially aligned city map layers runs a search over many passes, reading back only its own drawing, and solves **78 %** of 500 held-out routes (96 / 89 / 63 % for routes of 2–3 / 4–5 / 6+ fronts), **60 %** on a district it never saw and **51 %** on synthetic house mazes it never trained on. Under one shared rule it beats the same network drawing the path in one pass (37 %) and a Qwen3-VL-2B fine-tuned with LoRA on 19.3k of the same routes (50 %), and the gap grows with route length. It is **not** a vision-language model: input and output are rasters.
58
+
59
+ ## What it does
60
+
61
+ - **Input:** a 256 m × 256 m window drawn as 17 aligned planes at 1 m per pixel, two markers in a marker plane, and a scratchpad plane holding its own previous output.
62
+ - **Output:** the whole next scratchpad on a 128 × 128 grid of 2 m cells, plus one state token.
63
+ - **Algorithm 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. One pass 2.4 ms on an RTX 3060; a route 57 ms (10 passes on average).
64
+
65
+ ## Model and training
66
+
67
+ 4 blocks, width 384, 6 heads, 16 px patches (256 tokens), learned relative position bias, two condition tokens (state, task), per-cell 2-class head and 41-class token head; 8.86 M parameters. 48k steps on 100k De Pijp routes (cosine, batch 128, pad noise, annealed change-cell weighting, token loss weight 0.1), then 16k steps with half of the input drawings replaced by the network's own stored drawings ("natural noise"), the target staying the teacher's. Run id `c5_r5_wave_nat3_tok01_ownp50_from48k_L4_16k_g128_store100k`.
68
+
69
+ ## How to use
70
+
71
+ ```bash
72
+ git clone https://github.com/Marvel4U/spatial-reasoning-from-scratch
73
+ # place this file as runs/checkpoints/c5_r5_wave_nat3_tok01_ownp50_from48k_L4_16k_g128_store100k.pt
74
+ # unpack eval_bundle_v0.2.tar.gz of the GitHub release and copy its data/ and runs/ into the clone (REPRODUCE.md section 8)
75
+ cd harness
76
+ PYTHONPATH=. python diagnostics/wave_rollout_eval.py c5_r5_wave_nat3_tok01_ownp50_from48k_L4_16k_g128_store100k --n 500 --mode free
77
+ PYTHONPATH=. python diagnostics/wave_rollout_gif.py c5_r5_wave_nat3_tok01_ownp50_from48k_L4_16k_g128_store100k --route 342 --crops ../data/amsterdam/zuid_centrum/crops/v4ns --store c4_256_val
78
+ ```
79
+
80
+ ## Related models
81
+
82
+ - [`mxv456/spatial-wave-search-512m-hero`](https://huggingface.co/mxv456/spatial-wave-search-512m-hero): the same network continued at 512 m windows (routes to 1.1 km; the maze animation of the repository's README and `PAPER.md`).
83
+ - [`mxv456/qwen3-vl-2b-lora-map-routes`](https://huggingface.co/mxv456/qwen3-vl-2b-lora-map-routes): the vision-language baseline.
84
+
85
+ ## Limitations
86
+
87
+ One city for training; single seed; the headline depends on the route mix (75 % on the first 200 routes, 64 % before natural noise); the success rule scores the drawing as a set of cells, and a polyline extracted from it scores 76 %; long routes remain the failure mode.
88
+
89
+ ## Citation and licence
90
+
91
+ 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; data licences in the repository's `DATA_LICENSES.md`.