Initial RRoG GNN runner

1 files changed, 100 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f07c90f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,100 @@
+# RRoG-GNN Runner
+
+This repo runs the current RRoG/TRM-on-GNN experiment grid.
+
+Core rule:
+
+```text
+view/graph aggregation happens once; recursive compute is edge-free hidden-state refinement.
+```
+
+The main reported table is:
+
+```text
+Task x Backbone -> classic baseline
+Task x Backbone x fixed-RRoG -> delta against the matching classic row
+```
+
+`classic` is the non-RRoG baseline for every backbone: `T=0`, `n_sup=1`.
+
+## One-command Run On 2x A6000
+
+On a clean machine with two visible GPUs:
+
+```bash
+git clone git@github.com:YurenHao0426/rrog-gnn-runner.git
+cd rrog-gnn-runner
+./scripts/setup_and_run_two_a6000.sh
+```
+
+Defaults:
+
+- GPU0: `zinc-cycle56` over 17 backbones, `classic + fixed-rrog`
+- GPU1: `ogbg-molhiv` over 17 backbones, `classic + fixed-rrog`
+- Results: `runs/*.json`
+- Logs: `logs/*.log`
+- Summaries: `summaries/*.md`
+
+If the environment already has compatible `torch`, `torch_geometric`, and `ogb`:
+
+```bash
+SKIP_SETUP=1 ./scripts/setup_and_run_two_a6000.sh
+```
+
+To override CUDA wheel index during setup:
+
+```bash
+TORCH_INDEX_URL=https://download.pytorch.org/whl/cu121 ./scripts/setup_env.sh
+```
+
+## Common Commands
+
+Smoke test:
+
+```bash
+./scripts/setup_env.sh
+DEVICE=cuda:0 ./scripts/run_smoke.sh
+```
+
+Run the paired ZINC matrix only:
+
+```bash
+DEVICE=cuda:0 EPOCHS=200 ./scripts/run_zinc_cycle56_full.sh
+```
+
+Run one OGB molecular task:
+
+```bash
+TASK=ogbg-molhiv DEVICE=cuda:1 EPOCHS=100 ./scripts/run_ogb_mol_task_full.sh
+```
+
+Run all selected OGB molecular tasks serially on one GPU:
+
+```bash
+DEVICE=cuda:1 ./scripts/run_ogb_mol_all_tasks.sh
+```
+
+Collect summaries:
+
+```bash
+./scripts/collect_results.sh
+```
+
+## Backbones
+
+The implemented 2D view/backbone list is shared across ZINC and OGB:
+
+```text
+gin, gine, gcn, graphsage, gatv2, graphconv, transformer, pna,
+gen, film, resgated, tag, sgc, cheb, arma, mf, appnp
+```
+
+For ZINC `gine`, there are no bond features, so GINE uses a learned constant edge token.
+For OGB molecular tasks, GINE and edge-aware backbones use OGB bond encodings.
+
+## Notes
+
+- Runs are resumable at the cell level: scripts skip existing expected JSON files.
+- ZINC cycle-count cache is generated under `data/cycle_cache`.
+- OGB datasets are downloaded under `data/ogb`.
+- Override data/runs locations with `RROG_DATA_DIR` and `RROG_RUNS_DIR`.