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

[dario-loi]

Track

Track 1 — Graph Neural Networks (GNNs)

Team Name

howyadoin

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

Model

Directed Sheaf Neural Network (DSNN)

Status

Ready for review

Summary

This PR contributes a TopoBench-native implementation of the Directed Sheaf
Neural Network (DSNN) by Fiorini et al. (ICLR 2026). Sheaf Neural Networks
attach a $d$-dimensional stalk to every node and edge, glue them with learned
restriction maps, and diffuse features with $L^{\mathcal{F}} =
\delta^{\top}\delta$. That operator cannot see edge direction, because it is
invariant to the orientation chosen per edge.

DSNN removes that blindness with a single factor (Definition 1). The stalks
become complex, and one of each edge's two restriction maps picks up a
unit-modulus phase read off the binary adjacency,

$$T^{(q)}_{uv} = \exp!\big(i,2\pi q,(A_{uv} - A_{vu})\big), \qquad \tilde{\mathcal{F}}_{v \lhd e} = \mathcal{F}^{0}_{v \lhd e} T^{(q)}_{uv}.$$

The resulting directed sheaf Laplacian
$L^{\tilde{\mathcal{F}}} = \tilde{\delta}^{}\tilde{\delta}$ is complex
Hermitian and positive semidefinite (Thm 1); its normalization has spectrum in
$[0, 2]$ (Thm 2); and it specializes to the real sheaf Laplacian when the graph
is undirected (Thm 3), to the Magnetic Laplacian for a trivial sheaf and, at
$q = 1/4$, to the Sign-Magnetic Laplacian (Thm 4), which it factorizes as
$\hat{B}\hat{B}^{}$ (Thm 5). Features are diffused by Eq. 8 and read out as
$(\Re(X) \Vert \Im(X))$.

The Thm 4 correspondence carries the scaling App. C hedges about, and the
docstring and tests are explicit about it: on a digon-free digraph this
operator is twice the Magnetic Laplacian, since Eq. 3 sums over $\Gamma(u)$
while MagNet gives a one-way arc $A_{s,uv} = 1/2$. The factor vanishes on an
all-digon graph, and on a mixed graph the operator equals the Magnetic
Laplacian built on the binary symmetrized adjacency.

Implementation

• Backbone at topobench/nn/backbones/graph/dsnn.py (DSNNEncoder), with
  the operator split across seven modules under dsnn_utils/:
  laplacian_builders.py (the Eq. 2-3 assembly and the Eq. 5
  normalization, one builder per restriction-map family), phase.py
  (Definition 1's charge and the induced orientations), laplace.py
  (support symmetrization and the edge pairing), complex_ops.py (the
  real lifting of Appendix D, the complex ReLU of §3, complex dropout and
  unwind), discrete_models.py (the Eq. 8 diffusion stack),
  sheaf_models.py (the learned $\Phi$) and orthogonal.py (the $O(d)$
  retraction).
• No complex tensor is ever materialized. Appendix D's real lifting
  carries all the arithmetic, so autograd, scatter/gather and reduced
  precision behave conventionally and the sparse helpers, which document
  no complex support, are used inside their contract.
• Hydra configs for the three restriction-map families the paper
  benchmarks: configs/model/graph/dsnn.yaml (Diag-DSNN),
  dsnn_ortho.yaml (O(d)-DSNN) and dsnn_general.yaml (Gen-DSNN), plus
  dsnn_degree.yaml for the induced orientation described below. Every
  non-obvious value carries the paper grid (App. F) it comes from; where a
  grid leaves the choice free we take the value already in
  configs/model/graph/nsd.yaml, so a DSNN-vs-NSD comparison isolates the
  operator and nothing else.
• Unit tests asserting the paper's theorems rather than tensor shapes:
  Hermitian-ness and a real diagonal (Thm 1), PSD by both quadratic form
  and spectrum (Thm 1), $\mathrm{spec}(L_N) \subseteq [0,2]$ with the
  bound attained and a negative control that breaks it (Thm 2), collapse
  to the repo's existing NSD builder on undirected input (Thm 3), the
  Magnetic and Sign-Magnetic Laplacians against independently written
  references (Thm 4), the $\hat{B}\hat{B}^{*}$ factorization (Thm 5), the
  Eq. 8 update against a dense complex reference using an explicit
  $I_n \otimes W_1$, Eq. 7 recovery at $\varepsilon = 0$, permutation
  equivariance, and an overfit check on a task only directions reveal.
  223 tests in test/nn/backbones/graph/test_dsnn.py.
• All nine new files at 100% line coverage (493 statements, 0 missed).
• graph/dsnn and graph/dsnn_degree added to
  test/pipeline/test_pipeline.py, so CI exercises both the real and the
  complex operator path end to end.
• Sphinx pages for dsnn and all seven dsnn_utils modules
  (docs/api/), mirroring the existing nsd / nsd_utils layout.
• Challenge notebook run end to end over the full GraphUniverse grid
  (12 settings $\times$ 3 seeds $\times$ 2 experiments $= 72$ runs) on
  graph/dsnn_degree; the auto-generated results.json is included.
  run_evaluation.ipynb differs from main in exactly one cell,
  MODEL_CONFIG, and the guard hash in cell 6 still matches
  expected_hash.

The undirected-benchmark problem, and what we did about it

Every graph dataset in TopoBench, and every graph GraphUniverse generates, is
undirected. On undirected input $A = A^{\top}$, so

$$T^{(q)}_{uv} = \exp!\big(i,2\pi q,(A_{uv} - A_{vu})\big) = e^{0} = 1$$

for every $q$. This is Theorem 3, and it is exact rather than approximate: the
operator is bitwise identical across the whole charge grid, its imaginary part
is identically zero, and DSNN reduces to real Neural Sheaf Diffusion. Run as
provided, the model's headline contribution is unreachable and the q entry in
its config does nothing.

2026_tdl_challenge/dsnn_directionality.ipynb establishes three things about
that regime:

1. The claim is measured, not asserted. In float64 the deviation across the
   charge grid is not $10^{-16}$ but exactly zero, for all three families; the
   operator also equals the real sheaf Laplacian that TopoBench's own NSD port
   builds from the same restriction maps. We additionally census GraphUniverse
   and confirm every generated graph is undirected.

2. The paper's Figure 2 is reproduced at its exact scale. On the directed
   stochastic block model of Appendix E ($n = 2500$, $C = 5$), where node
   features are in-degree plus out-degree and so carry no class signal, the
   label is recoverable only from edge directions. DSNN with a non-zero charge
   separates the communities; the same model at $q = 0$, which Theorem 3 makes
   exactly direction-blind sheaf diffusion, sits at chance, as does a
   feature-only probe.

3. dsnn_degree.yaml reaches the directed regime. It derives an orientation
   from the lexicographic key (degree, neighbour-degree sum), orienting
   $a \to b$ when $a$'s key is smaller and leaving ties undirected. Both keys
   are isomorphism invariants, so the model stays permutation equivariant,
   unlike a tie-break on node index, which we also ship as
   orientation="index" so the contrast is visible. This is an extension
   rather than part of the paper, and it is labelled as such in the config
   header, the module docstring and the notebook.

A phase derived from a graph distance is deliberately not offered: BFS layering
forces $|\pi(b) - \pi(a)| \le 1$ on every edge, making
$L = U^{*}L^{\mathcal{F}}U$ a pure gauge transformation, isospectral with plain
sheaf diffusion. What makes a phase genuinely directional is non-zero holonomy
around cycles, so on a tree no induced orientation can help. GraphUniverse runs
at average degree 1-2 in half the grid, which is close to tree-like, so we do
not expect dsnn_degree to gain much there.

Notes on faithfulness

Deviations from the published definition, each flagged where it is
implemented:

• The phase sign. Definition 1 prints $\exp(+i2\pi q(\cdot))$, but its own
  worked example ($q = 1/4$ giving $-i$) requires the conjugate. We default to
  the printed formula and expose the other as phase_sign. The notebook shows
  that either reading satisfies Theorem 4 against the matching MagNet
  convention, and that the two operators are conjugate and isospectral, so the
  discrepancy does not have to be adjudicated to be handled. A consequence:
  $q$ and $1 - q$ are equivalent, so $q \in [0, 1/2]$ suffices when searching.
• $\Im(X^{0}) = 0$. Input features are real and the paper does not specify an
  imaginary part for $X^{0}$; zeros keep the readout's two halves from being
  duplicates at the first layer.
• $\varepsilon$ is reparametrized as $1 + \tanh(\varepsilon)$ and tiled over
  the nodes (shape $[d, 1]$), so the $[-1, 1]$ range Eq. 8 asks for holds by
  construction rather than by clipping.
• add_lp / add_hp are not implemented. They are axes of the paper's
  hyperparameter grid (App. F) rather than part of Eq. 8, they are absent from
  the NSD port already in TopoBench, and they are orthogonal to
  directionality, which is what this model contributes.
• edge_weight is accepted and ignored, because Definition 1 builds the phase
  from the binary adjacency.
• The edge pairing was re-implemented. TopoBench's NSD port matches each arc to
  its reverse with an $[m/2, m, 2]$ broadcast comparison, which is $O(m^2)$ in
  memory and would need hundreds of gigabytes at the scale of the Figure 2
  reproduction. The sort-based replacement in dsnn_utils/laplace.py agrees
  with it exactly wherever the reference can run, and also tolerates
  self-loops, which trip the reference's edge-count assertion. nsd_utils is
  left untouched.

Against the authors' implementation

We also read the reference code
(https://github.com/hakanaktas0/DSNN), which exposes several switches the paper
never mentions. Where it and the paper disagree we follow the paper, except in
one place where the reference is solving a real numerical problem:

• We follow the reference on normalization, and it matters more than it looks.
  For the general family $\tilde{D}^{-1/2}$ needs a matrix inverse square root,
  and the backward pass of eigh divides by eigenvalue gaps, so it is
  ill-behaved on a degree block with repeated eigenvalues. Like the reference,
  we detach $\tilde{D}^{-1/2}$ and jitter the blocks by $U(-0.001, 0.001)$
  while training.

  This is not cosmetic. On the DSBM of §7 ($n = 2500$, mean degree 210, where
  degree blocks are near-degenerate) Gen-DSNN scores 0.25 when the gradient is
  routed through eigh and 0.96 when it is detached, same seed and protocol;
  Diag-DSNN reproduces 0.968 either way, since it is the general family alone
  that has full degree blocks and so reaches that path. We report this because
  the deviation is invisible in unit tests, since every theorem test passes
  under both, and only shows up as a family that silently will not train.
  test_block_normalization_survives_repeated_eigenvalues and
  test_degree_block_jitter_is_training_only pin the behaviour down.

• Orthogonal maps use Cayley rather than the reference's Householder default,
  which needs the external torch_householder package. Both land in $SO(d)$,
  so the reflection component of $O(d)$ is unreachable either way.

• The orthogonal family predicts $d(d-1)/2$ parameters, not the reference's
  $d(d+1)/2$: skew-symmetrizing $A = P - P^{\top}$ annihilates the diagonal, so
  $d$ of those have identically zero gradient.
  test_orthogonal_parameterization_has_no_dead_parameters pins this down.

• $\Im(X^{0}) = 0$ where the reference defaults to copying the real part, and
  complex dropout drops whole entries where the reference defaults to
  independent masks. The first keeps unwind's two halves from being
  duplicates at layer one; the second preserves the argument of surviving
  entries.

• The reference additionally learns a scalar weight per arc for the orthogonal
  family. It is on by default there but appears nowhere in the paper, so we
  keep the plain $\deg(u) I_d$ of Eq. 3.

One config choice to flag: stalk dimension $d = 2$. The paper searches
$d \in {2, \dots, 5}$ (App. F); $d = 2$ divides the harness-pinned width of
64 exactly, so no hidden channel is lost to rounding, and it is the smallest
value that leaves orthogonal and general restriction maps non-trivial.

Benchmark

Grid run on graph/dsnn_degree, the config whose complex path is live on
undirected input; 72 runs, 18,077 parameters on community detection and 17,754
on triangle counting, ~1.0 s/train epoch.

Task	Result
Community detection (accuracy)	$0.308 \pm 0.027$ over 36 runs
Triangle counting (MSE)	spans orders of magnitude with triangle count; per-setting values in results.json

2026_tdl_challenge/outputs/2026-07-31_14-54-32/results.json

graph/dsnn, dsnn_ortho and dsnn_general ship as configs but were not run:
by Theorem 3 all three are exactly real on GraphUniverse, so their numbers
would be Neural Sheaf Diffusion with the Eq. 8 readout, not DSNN.

Reference

Fiorini, Aktas, Duta, Coniglio, Morerio, Del Bue, Liò, "Sheaves Reloaded: A
Directional Awakening," ICLR 2026.

• ArXiv: https://arxiv.org/abs/2506.02842
• Reference implementation: https://github.com/hakanaktas0/DSNN

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB