Track: Track1; Team name: topolab; Model: GREAD

[uiharu-kazari]

GREAD — Graph Neural Reaction-Diffusion Networks (Track 1)

Checklist

• My pull request has a clear and explanatory title.
• My pull request passes the Linting test.
• I added appropriate unit tests and I made sure the code passes all unit tests.
• My PR follows PEP8 guidelines.
• My code is properly documented, using numpy docs conventions, and I made sure the documentation renders properly.
• I linked to issues and PRs that are relevant to this PR. (none applicable — challenge submission)

Description

Paper: Choi et al., GREAD: Graph Neural Reaction-Diffusion Networks, ICML 2023 (arXiv:2211.14208). Reference implementation: jeongwhanchoi/GREAD.

What this PR adds

• Backbone topobench/nn/backbones/graph/gread.py — reaction–diffusion ODE on graphs, integrated with the explicit Euler method (Eq. (5)), with exact terminal-time handling (full steps plus a shorter final step). Implements the diffusion term of Eq. (7) and all paper reaction terms (Eq. (10): fisher, allen-cahn, zeldovich, st, fb, fb3; Eq. (14): bspm; plus none), scalar α/β gates and the beta_diag "(VC)" variant, optional source term, and both rw / gcn adjacency normalizations following the reference get_rw_adj(..., norm_dim=1) / gcn_norm_fill_val. Docstrings cite the paper's equation numbers throughout; the one deliberate deviation (the fb/fb3 sign convention follows the reference code rather than Eq. (10) as printed) is documented in the docstring. Fully sparse message passing — no dense N×N matrix is ever materialized.
• Configs (one per significant variant, per the challenge rules): configs/model/graph/gread.yaml (bspm, the paper's headline blurring–sharpening variant), gread_fisher.yaml, gread_allen_cahn.yaml, gread_zeldovich.yaml, gread_source_term.yaml.
• Tests test/nn/backbones/graph/test_gread.py — 40 tests, 100% line coverage of gread.py. These verify semantics, not just shapes: manual multi-step Euler integration (including the partial final step), closed-form normalized-adjacency values, per-reaction-term math, beta_diag vs scalar-gate discrimination, self-loop-weight closed forms, dropout train/eval behavior, and error handling for invalid configurations.
• Pipeline test test/pipeline/test_pipeline.py registers all five configs (end-to-end training on MUTAG).
• Official benchmark 2026_tdl_challenge/run_evaluation.ipynb (only the MODEL_CONFIG line changed, protected-cell hash intact) and the auto-generated outputs/2026-08-02_gread-vc/results.json: the full 72-run grid (12 regimes × 2 tasks × 3 seeds), no non-finite values. Headline in-distribution means: community-detection accuracy 0.4816, triangle-counting MSE/triangles 0.8773.
• Supplementary analysis 2026_tdl_challenge/analysis_gread.ipynb — uses all 864 committed measurements (the official heatmaps show only the diagonal of the 12×12 transfer matrix) to decompose OOD behavior: community detection is governed by the evaluation regime (difficulty effect, R² 0.85 vs 0.03), while triangle counting is governed by the training regime (a genuine distribution-shift failure via scale miscalibration, R² 0.41 vs 0.12 on a log scale).

Issue

No linked issue — this is a TDL Challenge 2026 submission (Track 1).

Additional context

• Update (Aug 2): the benchmarked config now pins beta_diag: true (the reference implementation's tuned default for every dataset; the initial submission benchmarked the non-default scalar gate). The full 72-run grid was re-run under the unmodified harness and the committed results.json replaced: community detection improved in all 12 regimes (mean 0.4504 → 0.4816), triangle counting in 10 of 12 (0.9206 → 0.8773). The analysis notebook is re-executed against the new study.

• Team: topolab (registration form submitted with this PR's ID).

• Could a maintainer please tag this PR with track-1-gnn? (No triage rights.)

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB