Add SETUP.md — end-to-end setup instructions

README.md

@@ -12,7 +12,7 @@ Code for running **SRA**, a modular future-interaction graph that plugs into thr
 trajectory predictors — **MID** (DDPM), **LED** (leapfrog-DDPM) and **MoFlow** (flow matching) —
 on **NBA**, **Soccer** and **Football**.
 
-## 👉 Start here: [`RUNNING.md`](RUNNING.md)
+## 👉 Start here: [`SETUP.md`](SETUP.md) — download, install, run
 
 It covers the required directory layout, environment setup, the exact training command for each
 host × dataset, the E2 ablation settings, environment-variable switches, the adapter contract,
@@ -20,6 +20,7 @@ and known gotchas.
 
 ## Documents
 
+- [`SETUP.md`](SETUP.md) — end-to-end setup from scratch (env, data, paths, first run)
 - [`RUNNING.md`](RUNNING.md) — how to run every host × dataset
 - [`GAMEFORMER_SRA.md`](GAMEFORMER_SRA.md) — GameFormer+SRA negative result (does SRA generalize to feedforward models?)
 - [`sample_data/README.md`](sample_data/README.md) — bundled 100-scene NBA smoke-test subset

SETUP.md

@@ -0,0 +1,153 @@
+# Setup — from nothing to a running experiment
+
+Copy-paste block. Assumes conda + an NVIDIA GPU. `$SRA` is wherever you want everything to live.
+
+```bash
+export SRA=$HOME/sra && mkdir -p $SRA && cd $SRA
+```
+
+## 1. Environment
+
+```bash
+conda create -n sra python=3.11 -y
+conda activate sra
+pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/cu121
+pip install easydict pyyaml tensorboard tqdm scipy matplotlib gitpython huggingface_hub numpy
+
+# cuDNN fix — REQUIRED for MID and LED (otherwise .backward() dies with
+# "Could not load library libcudnn_cnn_train.so.8 ... undefined symbol")
+export LD_LIBRARY_PATH="$(ls -d $CONDA_PREFIX/lib/python3.11/site-packages/nvidia/*/lib | tr '\n' ':')$LD_LIBRARY_PATH"
+```
+
+## 2. Code
+
+```bash
+cd $SRA
+git clone https://huggingface.co/po03087/sra-trajectory-code code
+# MoFlow/, MID/ and LED/ MUST stay siblings — MID and LED import the SRA graph from ../MoFlow
+ls code   # -> LED  MID  MoFlow  RUNNING.md  SETUP.md  GAMEFORMER_SRA.md  sample_data  standalone
+```
+
+## 3. Data (+ LED pretrained cores)
+
+```bash
+cd $SRA
+huggingface-cli download po03087/sra-trajectory-data sra_data_full.zip \
+  --repo-type dataset --local-dir .
+# or: wget https://huggingface.co/datasets/po03087/sra-trajectory-data/resolve/main/sra_data_full.zip
+
+unzip -q sra_data_full.zip -d data
+ls data   # -> nba  sport  LED_pretrained_core  README.md
+```
+
+## 4. Put the files where each host expects them
+
+The three hosts use **different path conventions** — this is the step that goes wrong most often.
+
+```bash
+cd $SRA
+
+# MoFlow — NBA lives inside the repo
+mkdir -p code/MoFlow/data/nba/original
+cp data/nba/original/nba_*.npy code/MoFlow/data/nba/original/
+
+# LED — NBA path is HARDCODED to ./data/files/nba_{train,test}.npy
+mkdir -p code/LED/data/files
+cp data/nba/original/nba_*.npy code/LED/data/files/
+
+# LED — pretrained core denoising models (REQUIRED; LED crashes without them)
+mkdir -p code/LED/results/checkpoints
+cp data/LED_pretrained_core/*.p code/LED/results/checkpoints/
+
+# LED — sport data_dir is read from the YAML, not the CLI
+sed -i "s|^data_dir .*|data_dir                     : '$SRA/data/sport/soccer'|"   code/LED/cfg/sport/soccer.yml
+sed -i "s|^data_dir .*|data_dir                     : '$SRA/data/sport/football'|" code/LED/cfg/sport/football.yml
+
+# MID and MoFlow read sport data straight from $SRA/data/sport/... via --data_dir
+```
+
+Sanity check:
+
+```bash
+python - <<'PY'
+import numpy as np, os, glob
+SRA = os.environ['SRA']
+for p, want in [(f"{SRA}/code/MoFlow/data/nba/original/nba_train.npy", (32500,30,11,2)),
+                (f"{SRA}/code/MoFlow/data/nba/original/nba_test.npy",  (12500,30,11,2)),
+                (f"{SRA}/code/LED/data/files/nba_train.npy",           (32500,30,11,2)),
+                (f"{SRA}/data/sport/soccer/train.npy",                  (7164,30,23,2)),
+                (f"{SRA}/data/sport/football/train.npy",               (37859,30,23,2))]:
+    a = np.load(p, mmap_mode='r'); print(("ok  " if a.shape==want else "BAD "), p, a.shape)
+print("LED cores:", [os.path.basename(x) for x in glob.glob(f"{SRA}/code/LED/results/checkpoints/*.p")])
+PY
+```
+
+## 5. Smoke test (2 minutes, no real training)
+
+```bash
+cd $SRA/code/MoFlow
+CUDA_VISIBLE_DEVICES=0 python fm_nba_graph_v6.py \
+  --cfg cfg/nba/cor_fm.yml --exp smoke --data_dir ../sample_data/nba \
+  --n_train 100 --n_test 100 --batch_size 8 --epochs 1 \
+  --fm_in_scaling --tied_noise --top_n_neighbors 5 --uncertainty_weight 0.01
+```
+
+## 6. Real training — SRA on each host × dataset
+
+```bash
+cd $SRA/code
+```
+
+**MoFlow**
+```bash
+cd $SRA/code/MoFlow
+# NBA
+CUDA_VISIBLE_DEVICES=0 python fm_nba_graph_v6.py \
+  --cfg cfg/nba/cor_fm.yml --exp nba_sra --data_dir ./data/nba \
+  --batch_size 192 --epochs 150 --fm_in_scaling --tied_noise \
+  --top_n_neighbors 5 --uncertainty_weight 0.01
+# soccer / football  (swap soccer <-> football)
+CUDA_VISIBLE_DEVICES=0 python fm_sport_graph_v6.py \
+  --cfg cfg/sport/football.yml --exp football_sra --data_dir $SRA/data/sport/football \
+  --batch_size 64 --epochs 100 --top_n_neighbors 5 --uncertainty_weight 0.01
+```
+
+**MID** — note NBA takes the `original/` dir *directly* (unlike MoFlow)
+```bash
+cd $SRA/code/MID
+# NBA
+CUDA_VISIBLE_DEVICES=0 python main_nba_mid_graphv6_v3.py \
+  --data_dir $SRA/data/nba/original --exp_name mid_nba_sra \
+  --epochs 100 --batch_size 32 --lr 1e-3 --eval_every 5 --sampling ddim --sampling_step 10
+# football  (soccer: main_soccer_mid_graphv5_sigma_output.py)
+python main_football_mid_graphv5_sigma.py \
+  --data_dir $SRA/data/sport/football --exp_name mid_football_sra --gpu 0 \
+  --epochs 100 --batch_size 64 --lr 1e-3 --graph_lr_mult 1.0 --eval_every 1 \
+  --top_n_neighbors 5 --uncertainty_weight 0.01 \
+  --train_mode two_pass --sampling ddim --sampling_step 20
+```
+
+**LED** — must be launched from the `LED/` directory (hardcoded relative paths)
+```bash
+cd $SRA/code/LED
+# NBA
+python main_led_nba_graph.py --cfg led_augment --gpu 0 --train 1 \
+  --use_v6_graph --use_sigma --top_n 5 --uncertainty_weight 1.0 --residual_on eps
+# soccer / football
+python main_sport_led.py --cfg football --gpu 0 --train 1 --use_v6_graph --residual_on eps
+```
+
+## Gotchas that will bite
+
+| Symptom | Fix |
+|---|---|
+| `undefined symbol ... libcudnn_cnn_train.so.8` | the `LD_LIBRARY_PATH` export in §1 |
+| LED: `FileNotFoundError: ./data/files/nba_train.npy` | copy NBA files there **and** run from `LED/` |
+| LED: crash loading `base_diffusion_model*.p` | copy the cores into `LED/results/checkpoints/` |
+| LED sport reads the wrong data | edit `data_dir` in the YAML — LED sport ignores a CLI `--data_dir` |
+| MoFlow: `FileNotFoundError .../original/original/...` | `--data_dir` must be the **parent** of `original/` |
+| MID sport ADE stuck ≈0.46 | use `--graph_lr_mult 1.0`, not 3.0 |
+| dense sport (`--top_n_neighbors 22`) OOM at BS64 | use `--batch_size 32` |
+| `ImportError: tensorboardX` | use `torch.utils.tensorboard` |
+
+See [`RUNNING.md`](RUNNING.md) for the E2 ablation settings and all environment-variable switches.