REPRODUCE.md

# Reproducing the 8k Perceiver (private HSS 0.5388, 5th place)

The submitted entry is `checkpoint_8192.pt`, the raw 8k Perceiver. It is the end
of a resolution curriculum: the organizers' 2048 → 4096 baseline produces
`checkpoint.pt`, which we then fine-tune at 8192 points to produce
`checkpoint_8192.pt`. The architecture is identical at every stage — only the
input point budget grows.

The Perceiver training code is the organizers' package, bundled here under
`s23dr_2026_example/` (`train.py`, `tokenizer.py`, `model.py`, `losses.py`).

## Inference

```bash
pip install -r requirements.txt
python script.py
```

`script.py` loads `checkpoint_8192.pt`, fuses and priority-samples each scene to
8192 points (6144 COLMAP + 2048 depth), runs the Perceiver, and writes
`submission.json` (`{order_id, wf_vertices, wf_edges}` per scene). No seam, no
augments (`CONF_THRESH=0.5`).

## Architecture

Every stage shares one config (`configs/base.json`):

```
Perceiver: hidden=256, ff=1024, latent_tokens=256, latent_layers=7
  encoder_layers=4, decoder_layers=3, cross_attn_interval=4
  num_heads=4, kv_heads_cross=2, kv_heads_self=2
  qk_norm=True (L2), rms_norm=True, dropout=0.1
  segments=64, segment_param=midpoint_dir_len, segment_conf=True
  behind_emb_dim=8, vote_features=True, activation=gelu
```

## Curriculum

The Perceiver is trained by a staged resolution curriculum: from scratch at
2048 points, then fine-tuned at 4096 and 8192. Each resolution step adds 45k
fine-tuning steps, the last 20k a linear cooldown, at a gentle learning rate
(3e-5) that preserves the lower-resolution representations. Stages A and B are
the organizers' baseline; stage C is ours. The generic invocation is:

```bash
python -m s23dr_2026_example.train \
    --cache-dir hf://usm3d/s23dr-2026-sampled_<N>:train \
    --seq-len <N> [--resume <previous_checkpoint>] --aug-rotate --aug-flip
```

### Stage A — 2048, from scratch  *(organizers)*

```
Data:   sampled_2048_v2:train
Steps:  0 -> 125,000     LR: 3e-4, warmup 10,000     Batch: 32
Loss:   sinkhorn (eps=0.1, iters=20, dustbin=0.3) + conf (weight 0.1)
Seed:   353
```

Trains the Perceiver from random init. The 2048 budget keeps the train/val gap
low; training directly at high resolution overfits. **Public test HSS 0.4273.**

### Stage B — 4096 fine-tune + cooldown  *(organizers)* → `checkpoint.pt`

```
Resume: Stage A          Data: sampled_4096_v2:train
Steps:  125,000 -> 170,000  (45k; last 20k linear cooldown)
LR:     3e-5             Batch: 64
```

Switches the input to 4096 points; the gentle LR adapts without disturbing the
learned representation (LR > 1e-4 forgets it). The result is the organizers'
released 4k checkpoint, `checkpoint.pt` — **public test HSS 0.4470**.

### Stage C — 8192 fine-tune + cooldown  *(ours)* → `checkpoint_8192.pt`

```
Resume: checkpoint.pt    Data: organizers' released 8k samples
Input:  8192 points = 6144 COLMAP + 2048 depth
Steps:  170,000 -> 215,000  (45k; last 20k linear cooldown)
LR:     3e-5             Batch: 64
```

Resumes the 4k checkpoint and continues the same gentle fine-tune at 8192 points.
This is the only stage we contribute, and the single largest gain in the system:
doubling the input from 4096 to 8192 points lifts the raw model from 0.4470 to
**0.5004** public HSS (a +0.053 jump, larger than the entire hand-crafted hybrid
contributes at 4k). Retuning the confidence threshold from 0.5 to 0.65 reaches
our public best of 0.5009; the submitted entry uses 0.5. This is
`checkpoint_8192.pt` — **public test HSS 0.5004, private 0.5388 (5th place)**.

## Data

The organizers publish pre-sampled point clouds (`sampled_2048` / `sampled_4096`
/ `sampled_8192`) on the Hugging Face Hub; the curriculum above trains directly
on them. `training/gen_sampled_16384.py` regenerates a sampled set at an
arbitrary `--seq-len` from the organizers' `cached_full_pcd_v2` cache, in the
same format — we used it to try a 16384 budget (see below).

## Negative results (kept for the record, not on the inference path)

- **16384 resolution** regressed relative to 8192. The generator is
  `training/gen_sampled_16384.py`; the model was not shipped.
- **Per-scene router** (`training/train_routing_gbt.py` with
  `training/oracle_sources_{train,validation}.json`): a gradient-boosted router
  choosing 4k / 8k / hand-crafted per scene recovered only ~4.5% of the
  per-scene oracle ceiling.
- **Point Transformer V3 encoder** (`experiments/ptv3/`): a stronger encoder,
  too slow for the T4 2-hour budget. Trained checkpoint, logs, and code are
  archived there.

## Evaluation sets

Two splits matter for the numbers above:

- **Public test** — the competition harness scores `submission.json` against the
  hidden test set and posts to the leaderboard. Every HSS in this document
  (4k 0.4470, 8k 0.5004, private 0.5388) is a public/private test number.
- **Dev val** — the tail of the published training set, used during development
  to pick checkpoints. We do not quote dev-val numbers here, since the
  leaderboard scores are the ones that decide the entry.