SETUP.md

# 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.