Track: Track1; Team name: howyadoin; Model: SheafAN

[dario-loi]

Track

Track 1 — Graph Neural Networks (GNNs)

Team Name

howyadoin

• Dario Loi — Northeastern University
• Gabriele Onorato — Northeastern University

Model

Sheaf Attention Networks (SheafAN)

Status

Ready for review

Summary

This PR contributes a TopoBench-native implementation of Sheaf Attention
Networks (SheafAN) by Barbero et al. (NeurIPS 2022 Workshop on Symmetry
and Geometry in Neural Representations), a generalisation of GAT to
cellular sheaves. Each edge carries both a GAT-style scalar attention
coefficient and a learned d x d restriction map (orthogonal by default);
the per-layer update is the attention-weighted sheaf-adjacency message
pass from equation (5) of the paper, with an optional residual variant
(equation 6 / Res-SheafAN) toggled via the residual flag.

The implementation reuses NSD's sheaf-learner, orthogonal parameterization
and sparse index plumbing where possible, and adds three new pieces
under nsd_utils/: a GAT-style attention module, sheaf-adjacency
builders (one per restriction-map family), and three inductive SheafAN
models mirroring NSD's diag / bundle / general variants. The bundle
variant with O(d) restriction maps is the paper-faithful setting and is
the default in the Hydra config.

Implementation

• Adjacency builders mirroring NSD's Laplacian builders, scaled by
  per-direction attention coefficients with identity self-loops
  (topobench/nn/backbones/graph/nsd_utils/adjacency_builders.py).
• Multi-head GAT-style attention with row-stochastic softmax over
  source neighbours, mirroring torch_geometric.nn.GATConv's
  head/dim flexibility (nsd_utils/san_attention.py).
• Three inductive SheafAN model variants — diag / bundle / general
  — with optional Res-SheafAN residual update
  (nsd_utils/inductive_attention_models.py).
• SANEncoder wrapper plugged into the TBModel pipeline, mirroring
  NSDEncoder's public API (topobench/nn/backbones/graph/san.py).
• Hydra config (configs/model/graph/san.yaml) referencing
  SANEncoder with paper-style defaults
  (sheaf_type=bundle, d=3, num_heads=4).
• Unit tests covering all variants, multi-head attention,
  adjacency builders and residual mode (70 tests,
  test/nn/backbones/graph/test_san.py); coverage on the four new
  files is 100% / 100% / 100% / 98% (well above the 93%
  threshold).
• graph/san added to test/pipeline/test_pipeline.py so the
  end-to-end pipeline is exercised in CI.
• Challenge notebook (2026_tdl_challenge/run_evaluation.ipynb)
  pointed at graph/san and run end-to-end over the full
  GraphUniverse grid (12 settings × 3 seeds × 2 experiments = 72
  runs); the auto-generated results.json is included.

Reference

Barbero, Bodnar, Sáez de Ocáriz Borde, Liò, "Sheaf Attention Networks,"
NeurIPS 2022 Workshop on Symmetry and Geometry in Neural Representations
(Extended Abstract Track).

• OpenReview: https://openreview.net/forum?id=LIDvgVjpkZr
• PDF: https://openreview.net/pdf?id=LIDvgVjpkZr

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a Sheaf Attention Network (SAN / SheafAN) graph backbone to TopoBench, including the underlying inductive attention model implementation, adjacency builders, configuration, and tests.

Changes:

• Introduces SANEncoder plus SAN attention, inductive model variants (diag/bundle/general), and adjacency builders.
• Adds a Hydra model config for graph/san and wires SAN into the pipeline test model list.
• Adds extensive unit tests covering encoder init/forward, attention normalization, self-loop augmentation, and adjacency builder shapes.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
topobench/nn/backbones/graph/san.py	New SAN encoder wrapper integrating inductive SAN variants into the training pipeline.
topobench/nn/backbones/graph/nsd_utils/san_attention.py	Implements multi-head GAT-style attention used by SAN.
topobench/nn/backbones/graph/nsd_utils/inductive_attention_models.py	Adds inductive SAN variants and the core forward/update logic.
topobench/nn/backbones/graph/nsd_utils/adjacency_builders.py	Adds builders that assemble attention-weighted sheaf adjacency blocks.
test/pipeline/test_pipeline.py	Adds graph/san to the pipeline models exercised by the test.
test/nn/backbones/graph/test_san.py	New unit test suite for SAN components.
configs/model/graph/san.yaml	New Hydra config to run SAN as a TBModel.
2026_tdl_challenge/run_evaluation.ipynb	Updates evaluation notebook to run with graph/san.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dario-loi]

Waiting on organizer feedback on #330 to post updated results.json, the current one still suffers from low epoch budgets