Track: Track2; Team name: howyadoin; Model: DSHN

[dario-loi]

Track

Track 2 — Topological Neural Networks (TNNs)

Team Name

howyadoin

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

Model

Directional Sheaf Hypergraph Network (DSHN)

Status

Ready for review

Summary

This PR contributes a TopoBench-native implementation of Directional Sheaf
Hypergraph Networks (DSHN) by Mule et al. (ICLR 2026). DSHN attaches a
vector space (a stalk) to every node and hyperedge, glues them with learned
restriction maps, and encodes hyperedge direction as a phase: an incidence
in the tail set picks up $e^{-2\pi i q}$, one in the head set does not. The
resulting Directed Sheaf Hypergraph Laplacian

$$L^{\mathcal{F}} = D_V - \left(B^{(q)}\right)^{\dagger} D_E^{-1} B^{(q)} \qquad \text{(Eq. 1-3)}$$

is complex Hermitian, and one layer diffuses complex features with
$Q^{\mathcal{F}}_N = I - L^{\mathcal{F}}_N$ (Eq. 9). Setting $q = 0$ collapses
the phase to $1$ and recovers direction-blind diffusion, which is how the same
operator covers directed and undirected hypergraphs in one definition.

Implementation

• Backbone with both models of the paper (topobench/nn/backbones/hypergraph/dshn.py):
  DSHN, which learns the restriction maps end to end, and DSHNLight
  (light=true), which builds the operator outside the autograd graph so
  $\Phi$'s parameters stay fixed and only the projection layer adapts (p. 8,
  the variant that still fits where DSHN runs out of memory in Table 6).
• Operator split into three modules under dshn_utils/:
  laplacian.py (the Eq. 1-3 assembly, the charge phase of Eq. 4, the
  block normalization, and the Appendix D.5 orientation), complex_ops.py
  (complex ReLU, dropout, LayerNorm, unwind), and sheaf_builders.py
  (the diagonal, orthogonal and general restriction-map families).
• Hydra configs for the diagonal family the paper benchmarks
  (configs/model/hypergraph/dshn.yaml), the induced-orientation variant
  (dshn_directed.yaml), DSHNLight (dshn_light.yaml), and the two
  restriction-map families the reference implements but the paper does not
  benchmark (dshn_ortho.yaml, dshn_general.yaml). Every non-obvious
  value carries the paper section or the reference flag it comes from.
• Unit tests asserting the paper's theorems rather than tensor shapes:
  the Appendix E counterexample reproduced against its closed form (this
  operator is PSD where the $1/\delta_e$ diagonal of Duta et al. 2023 gives
  $\lambda_{\min} = (1-\sqrt{17})/6$), Hermitian-ness (Thm 1), the
  Dirichlet energy identity (Thm 2), $\lambda_{\max} \leq 1$ (Thm 3),
  reduction to $(D-A)/2$ on graphs (Thm 4), PSD-ness (Cor 1), and
  $q$-invariance on undirected input (Thm 6). 68 tests in
  test/nn/backbones/hypergraph/test_dshn.py, including an overfit check,
  a test that DSHNLight really does freeze $\Phi$, and degenerate cases
  (isolated nodes, singleton hyperedges, $d = 1$).
• All five new files at 100% line coverage (296 statements, 0 missed).
• hypergraph/dshn and hypergraph/dshn_directed added to
  test/pipeline/test_pipeline.py, so CI exercises both the real and the
  complex operator path end to end.
• Sphinx pages for dshn and dshn_utils (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
  hypergraph/dshn_directed; 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-lifting problem, and what we did about it

Every TopoBench graph2hypergraph lifting produces an undirected
hypergraph. On undirected input $H(e) = \emptyset$, so every phase product of
Eq. 4 is

$$\overline{S^{(q)}_{u \lhd e}} S^{(q)}_{v \lhd e} = \overline{e^{-2\pi i q}} e^{-2\pi i q} = 1$$

regardless of $q$: the operator is exactly real and its spectrum is exactly
independent of the charge. Run as lifted, DSHN's headline contribution is
unreachable and the q entry in its config does nothing.

Two things follow, and 2026_tdl_challenge/dshn_directionality.ipynb
establishes both:

1. The directed half is reachable, using the paper's own construction.
   Appendix D.5 orients a hyperedge away from the node it is centred on:
   $T(e_v) = {v}$, $H(e_v) = N(v)$. TopoBench's default khop lifting builds
   exactly one hyperedge per node, so the centre is recoverable and the
   construction applies directly. This is orientation="star", shipped as
   dshn_directed.yaml and the config the benchmark grid was run with. The
   notebook shows the imaginary mass rising with $q$ under star and pinned
   at zero under none, with the operator staying Hermitian and inside
   $[0, 1]$ throughout.

2. What the undirected case does give is positive semidefiniteness. The
   paper presents this as a contribution in its own right (p. 7): it "provides
   the first definition of a Sheaf Hypergraph Laplacian suitable for
   undirected hypergraphs", differing from Duta et al. (2023) only in the
   diagonal coefficient $1 - 1/\delta_e$ against $1/\delta_e$. That one
   coefficient is the entire difference, and it is what makes the operator a
   valid diffusion operator. We spell this out because PR Track: Track2; Team name: s/pairwise/ho; Model: SheafHyperGNN #321 implements
   SheafHyperGNN, which is the $1/\delta_e$ operator, so the boundary
   between the two submissions is exactly this coefficient.

The notebook also runs a small end-to-end control: a synthetic directed
hierarchy where the label is recoverable only from structure, half the nodes
held out. Accuracy is identical for none at $q = 0$ and $q = 0.25$ and for
star at $q = 0$, the three cases where the operator provably does not depend
on the charge, and moves only when an orientation and a non-zero charge are
both present. Five seeds on one synthetic task: the invariances are exact, the
magnitudes are indicative.

Notes on faithfulness

The paper and the authors' reference implementation
(https://github.com/EmaMule/DirectionalSheafHypergraphs, where the model is
named SheafGeDi) disagree in five places. We default to the published
definition in each and flag the deviation in the docstring:

• add_identity=False. The reference defaults to true, adding $D_V + I$,
  which appears in neither Eq. 2 nor Eq. 7. Exposed as a flag.
• The charge uses the paper's $e^{-2\pi i q}$ on tails; the reference uses the
  conjugate.
• The imaginary part of $X_0$ is zero-initialized. The reference copies the
  real part (x_img = data.x.clone().detach(), with zeros_like commented
  out), which on undirected input makes unwind emit two identical halves.
• $\sigma$ is applied after every layer, per Eq. 9; the reference omits it
  after the last.
• Only the MLP_var1 restriction-map predictor is implemented. var2/var3
  are undocumented; the authors' published best configuration happens to use
  var3, but since final accuracy is not what we are reproducing, we prefer
  the predictor the paper specifies.

Two smaller notes on the orthogonal family, which the reference implements but
the paper never benchmarks:

• TopoBench's existing Orthogonal class takes $d(d+1)/2$ parameters and
  forms $A = P - P^{\top}$, which annihilates the diagonal, so $d$ of those
  parameters have identically zero gradient. We predict only the $d(d-1)/2$
  that do anything. test_ortho_builder_has_no_dead_parameters pins this
  down.
• The reference defaults to a Householder parameterization, which needs the
  external torch_householder package. We use Cayley (and expose
  matrix_exp), both of which land in $SO(d)$, so the reflection component of
  $O(d)$ is unreachable here.

One config choice to flag: stalk dimension $d = 2$. The paper searches
$d \in {1, \dots, 6}$ (§D.3) and its published best configurations use
$d = 6$ for DSHN and $d = 4$ for DSHNLight. $d = 2$ is the smallest value that
leaves orthogonal and general restriction maps non-trivial, and the operator
costs $O\left(\sum_e \delta_e^2 d^2\right)$, which is what the challenge grid
has to fit into.

Benchmark

Grid run on hypergraph/dshn_directed, 72 runs, 37,678 parameters,
~1.6 s/train epoch.

Task	Result
Community detection (accuracy)	$0.463 \pm 0.129$ 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-30_13-32-07/results.json

Reference

Mule, Fiorini, Purificato, Siciliano, Coniglio, Silvestri, "Directional Sheaf
Hypergraph Networks: Unifying Learning on Directed and Undirected
Hypergraphs," ICLR 2026.

• ArXiv: https://arxiv.org/abs/2510.04727
• Reference implementation: https://github.com/EmaMule/DirectionalSheafHypergraphs

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB